v0.3.0 — real external tool stack + coordinator

.changeset/external-tool-stack.md

@@ -0,0 +1,11 @@
+---
+"@drmahdikazempour/agent-stack": minor
+---
+
+v0.3.0 — real external tool stack + coordinator.
+
+- **Full permissive stack wired in** (the `max` profile / `init --all`): rtk (Apache-2.0) + code-review-graph, graphify, caveman, claude-handoff, gbrain (all MIT), over the built-in fallbacks. Detect → install-if-missing → use.
+- **Multi-toolchain installer** — cargo / uv / pipx / pip / bun / `claude plugin`, tried in order with fallthrough on failure (e.g. a PEP-668 pip3 falls through to a working pip). Prints the tool's own install command as guidance when no toolchain is available; never auto-runs `curl|sh`.
+- **MCP registration** — code-review-graph's server is merged into `.mcp.json` (preserving user-defined servers); the SessionStart hook refreshes the external graph backend when active.
+- **Tool coordinator** — generated `CLAUDE.md` and `AGENTS.md` route each job to the right tool, with built-ins named as the explicit fallback. Cursor mirror references only the portable subset (rtk + MCP/CLI graph tools).
+- **Honest sourcing** — every install/MCP command transcribed from each repo's own docs; the two unlicensed candidates (token-optimizer, intent-layer) dropped since permissive members cover their function. Single source of truth: `integrations/tools.json`.

CREDITS.md

@@ -1,50 +1,47 @@
 # Credits & prior art
 
-agent-stack stands on the shoulders of the Claude/agent token-optimization ecosystem. This file is a transparent record of every project that inspired or is integrated by agent-stack, how it relates, and under what license.
+agent-stack stands on the shoulders of the Claude Code token-optimization ecosystem. This file is a transparent record of every project agent-stack integrates or was inspired by, how it relates, and under what license.
 
 > **Transparency notes**
-> - agent-stack **does not vendor** (copy in) any third-party code. Its built-in code map and output compression are original MIT code in [`src/builtin/`](src/builtin/), inspired by — not derived from — the tools below.
-> - The **only** tool agent-stack auto-installs is `ccusage`.
-> - "Optional" tools are used **only if their genuine binary is already on your PATH** (detect-only); they are never auto-installed, because the bare npm names are unrelated/squatted packages.
-> - Links reflect the handles cited in this project's PRD. Where a canonical repository wasn't specified upstream, the tool is named without a link rather than guessing a URL.
+> - agent-stack **does not vendor** (copy in) any third-party code. Its built-in code map and output compression are original MIT code in [`src/builtin/`](src/builtin/), and act as the **fallback** when an external tool isn't installed.
+> - Every integrated tool below is **permissive** (MIT / Apache-2.0). There is no consent gate and nothing non-permissive is wired in.
+> - Tools are **detected first**; a missing one is installed via its own toolchain (cargo / uv / pipx / bun / `claude plugin`). When no toolchain is available, agent-stack prints the tool's own install command as guidance and never silently runs a `curl | sh` one-liner.
+> - All commands in [`integrations/tools.json`](integrations/tools.json) were transcribed from each repo's own `INSTALL.md` / `README` / `.mcp.json` — not guessed.
 
-## Integrated (used directly)
+## Integrated stack (the `max` profile / `init --all`)
 
-| Project | License | How agent-stack uses it |
-|---|---|---|
-| [ryoppippi/ccusage](https://github.com/ryoppippi/ccusage) | MIT | Auto-installed; the neutral source of truth for token-usage baselines and `measure` reports. |
-
-## Optional integrations (detect-only — used if present on PATH)
+| Project | License | Integration | How agent-stack uses it |
+|---|---|---|---|
+| [ryoppippi/ccusage](https://github.com/ryoppippi/ccusage) | MIT | npm binary | Always installed; neutral source of truth for token-usage baselines and `measure` reports. |
+| [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | Apache-2.0 | PATH binary | Command proxy — route heavy git/npm/build/test output through it to cut 60-90% of tokens. Composes with the built-in `compress`. Installed via `cargo install --git` (never crates.io `rtk`, a different project). |
+| [tirth8205/code-review-graph](https://github.com/tirth8205/code-review-graph) | MIT | MCP server | Primary code map — its MCP server (`uvx code-review-graph serve`) is merged into `.mcp.json`; the SessionStart hook runs `code-review-graph update`. Replaces the built-in regex code map when present. |
+| [safishamsi/graphify](https://github.com/safishamsi/graphify) | MIT | CLI / skill | Knowledge graph for whole-repo, multi-file-type questions. PyPI package is `graphifyy`; CLI stays `graphify`. |
+| [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) | MIT | Claude Code plugin | Terse-output mode. Installed via `claude plugin marketplace add` + `claude plugin install`. |
+| [willseltzer/claude-handoff](https://github.com/willseltzer/claude-handoff) | MIT | Claude Code plugin | Session continuity (`/handoff:create`, `/handoff:resume`). |
+| [garrytan/gbrain](https://github.com/garrytan/gbrain) | MIT | Bun CLI / plugin | Persistent cross-session memory. Requires Bun; an embedding API key enables vector search (keyword search works without). |
 
-| Project | License | Role |
-|---|---|---|
-| `rtk` | Apache-2.0 | Shell-output compression (alternative to the built-in `compress`). |
-| `codegraph` | MIT | Code graph backend (alternative to the built-in code map). |
-| [tirth8205/code-review-graph](https://github.com/tirth8205/code-review-graph) | MIT | Review-focused graph for the `review` profile. |
-| [safishamsi/graphify](https://github.com/safishamsi/graphify) | MIT | Multimodal graph for the `multimodal` profile. |
-| [rhuss/cc-spex](https://github.com/rhuss/cc-spex) | Apache-2.0 | Spec-driven workflow for the `spec` profile. |
+**Cursor portability:** only `rtk` and the MCP/CLI graph tools (`code-review-graph`, `graphify`) are referenced in the Cursor mirror. The Claude Code plugins (`caveman`, `claude-handoff`, `gbrain`) are Claude-Code-only and are intentionally not named for Cursor.
 
-## Opt-in (runtime shell-out only, behind `--allow-noncommercial`)
+## Considered but dropped (no clear license)
 
-These are **never vendored** and never auto-installed; they are shelled out to at runtime only when you explicitly enable them.
+These cover functions already provided by permissive members of the stack, so they were dropped rather than wired in:
 
-| Project | License | Role |
+| Project | License | Why dropped |
 |---|---|---|
-| [mksglu/context-mode](https://github.com/mksglu/context-mode) | Elastic-2.0 | Large-output sandbox for the `research` profile. |
-| [alexgreensh/token-optimizer](https://github.com/alexgreensh/token-optimizer) | PolyForm Noncommercial | Deep token audit (`audit --deep`). |
+| [alexgreensh/token-optimizer](https://github.com/alexgreensh/token-optimizer) | NOASSERTION (no clear license) | Token/compaction savings already covered by `rtk` + `caveman` + the built-in `compress`. |
+| [orban/intent-layer](https://github.com/orban/intent-layer) | none (no LICENSE file) | Intent-driven "read only what matters" already covered by `code-review-graph` + `graphify`. |
 
 ## Prior art & inspiration
 
-Patterns, taxonomy, and ideas that shaped agent-stack's design — not integrated, but gratefully acknowledged.
+Patterns and ideas that shaped agent-stack's design — not integrated.
 
 | Project | License | Influence |
 |---|---|---|
 | [nadimtuhin/claude-token-optimizer](https://github.com/nadimtuhin/claude-token-optimizer) | MIT | The generated-file taxonomy (`CLAUDE.md`, `COMMON_MISTAKES.md`, `ARCHITECTURE_MAP.md`). |
 | [obra/superpowers](https://github.com/obra/superpowers) | MIT | Workflow-kernel and command patterns. |
 | [vercel-labs/skills](https://github.com/vercel-labs/skills) | MIT | Cross-agent skill installation model. |
-| `caveman` | MIT | Terse output-style inspiration (agent-stack's "terse mode"). |
-| [garrytan/gbrain](https://github.com/garrytan/gbrain) | — | Long-term memory tier (future roadmap). |
+| [garrytan/gstack](https://github.com/garrytan/gstack) | MIT | The reviewer/coordinator skill taxonomy. |
 
 ## License compatibility
 
-agent-stack is **MIT**. Its default install pulls only MIT/Apache-2.0 tooling. Non-permissive tools (Elastic-2.0, PolyForm Noncommercial) are gated behind `--allow-noncommercial` and are never vendored — CI fails if any code under `src/` imports them. See [`integrations/licenses.json`](integrations/licenses.json).
+agent-stack is **MIT** and integrates only MIT / Apache-2.0 tooling — no consent flag, nothing non-permissive. agent-stack never vendors third-party code. The single source of truth for every tool's source, install strategy, integration kind, and license is [`integrations/tools.json`](integrations/tools.json).

README.md

@@ -183,7 +183,7 @@ A **profile** bundles a graph backend + compression + skill set + hook config. `
 | 🟣 `multimodal` | built-in map | built-in | ≥ 5 PDFs / video / large images |
 | 🟡 `spec` | built-in map | built-in | spec-kit / cc-spex detected |
 | ⚪ `research` | none | built-in | `--profile research --allow-noncommercial` |
-| 🔴 `max` | built-in map | built-in **+ terse** | `--all` — everything on at once |
+| 🔴 `max` | external graph + built-in fallback | built-in **+ terse + rtk** | `--all` — full external stack on at once |
 
 ```bash
 agent-stack profile use review   # swap & regenerate
@@ -241,13 +241,12 @@ agent-stack uninstall                # restore backup, remove generated files
 
 | Flag | Effect |
 |------|--------|
-| `--all` | Turn on **every** feature at once (the `max` profile) |
+| `--all` | Full external stack at once (the `max` profile): rtk + code-review-graph + graphify + caveman + claude-handoff + gbrain |
 | `--yes` | Skip the single confirm prompt |
 | `--dry-run` | Print the plan, write nothing |
-| `--targets claude,cursor` | Force the host list (skip auto-detect) |
+| `--targets claude,cursor` | Force the host list (Cursor gets the portable subset: rtk + MCP graph tools) |
 | `--profile <name>` | Force a profile (`code` `review` `multimodal` `spec` `research` `max`) |
-| `--no-install` | Don't install `ccusage` (configs only) |
-| `--allow-noncommercial` | Enable opt-in adapters (`context-mode`, `token-optimizer`) |
+| `--no-install` | Write configs only; print install guidance instead of installing |
 | `--overwrite` | Replace existing files instead of merging (still backs up) |
 | `--force` | Re-run even if already installed |
 
@@ -291,14 +290,14 @@ agent-stack/
 │   ├── constants.ts            # all spec values (token budgets, limits)
 │   ├── core/                   # detect · plan · safe-writer · backup · token estimator
 │   ├── builtin/                # graph (code map) · compress (output compression)
-│   ├── generate/               # claude · cursor · mcp file builders
-│   ├── adapters/               # ccusage + detect-only externals; install + hooks
+│   ├── generate/               # claude · cursor · mcp · coordinator file builders
+│   ├── adapters/               # registry · detect-tools · install · hooks
 │   ├── wire-hooks.ts           # SOLE writer of settings.json hooks
 │   ├── activate.ts             # post-write verification chain
 │   ├── audit.ts                # token-budget linting
 │   └── commands/               # init + maintenance commands
 ├── skills/                     # 5 Agent Skills (stack-bootstrap, -doctor, …)
-├── integrations/               # profiles.json · versions.json · licenses.json
+├── integrations/               # profiles.json · tools.json
 ├── templates/                  # generation notes
 └── test/                       # vitest: unit · golden · e2e init in a tmpdir
 ```
@@ -408,16 +407,21 @@ Yes — `init` is idempotent. A matching prior install is a no-op unless you pas
 
 ## 🙏 Credits & prior art
 
-agent-stack composes ideas from across the Claude/agent token-optimization ecosystem. It **vendors none** of them — its built-in code map and compression are original MIT code, and the only tool it auto-installs is `ccusage`. Full, transparent attribution (integrated vs. optional vs. inspiration, with licenses) lives in **[CREDITS.md](CREDITS.md)**.
+agent-stack composes a permissive, real tool stack. It **vendors none** of it — its built-in code map and compression are original MIT code that act as the **fallback** when a tool isn't installed. Every integrated tool is MIT or Apache-2.0; nothing non-permissive is wired in. Tools are detected first, then installed via their own toolchains (cargo / uv / pipx / bun / `claude plugin`), with guidance when a toolchain is missing. Full, transparent attribution with licenses and exact install commands lives in **[CREDITS.md](CREDITS.md)** and **[integrations/tools.json](integrations/tools.json)**.
 
-At a glance:
+The `max` profile (`init --all`) activates, all at once:
 
-| Relationship | Projects |
-|---|---|
-| **Integrated** | [ccusage](https://github.com/ryoppippi/ccusage) (measurement) |
-| **Optional** (detect-only) | `rtk`, `codegraph`, [code-review-graph](https://github.com/tirth8205/code-review-graph), [graphify](https://github.com/safishamsi/graphify), [cc-spex](https://github.com/rhuss/cc-spex) |
-| **Opt-in** (`--allow-noncommercial`) | [context-mode](https://github.com/mksglu/context-mode), [token-optimizer](https://github.com/alexgreensh/token-optimizer) |
-| **Inspiration** | [claude-token-optimizer](https://github.com/nadimtuhin/claude-token-optimizer), [superpowers](https://github.com/obra/superpowers), [vercel-labs/skills](https://github.com/vercel-labs/skills), `caveman` |
+| Tool | License | Integration | Job |
+|---|---|---|---|
+| [ccusage](https://github.com/ryoppippi/ccusage) | MIT | npm binary | Token-usage measurement (always on) |
+| [rtk](https://github.com/rtk-ai/rtk) | Apache-2.0 | PATH binary | Command proxy — cut heavy command output 60-90% |
+| [code-review-graph](https://github.com/tirth8205/code-review-graph) | MIT | MCP server | Primary code map (graph with edges + impact radius) |
+| [graphify](https://github.com/safishamsi/graphify) | MIT | CLI / skill | Knowledge graph for whole-repo, multi-file-type questions |
+| [caveman](https://github.com/JuliusBrussee/caveman) | MIT | Claude Code plugin | Terse-output mode |
+| [claude-handoff](https://github.com/willseltzer/claude-handoff) | MIT | Claude Code plugin | Session continuity (`/handoff:*`) |
+| [gbrain](https://github.com/garrytan/gbrain) | MIT | Bun CLI / plugin | Persistent cross-session memory |
+
+The generated `CLAUDE.md` and `AGENTS.md` carry a **tool coordinator** that routes each job to the right tool, with the built-ins named as the explicit fallback. Cursor gets only the portable subset (`rtk` + the MCP/CLI graph tools). **Inspiration** (not integrated): [claude-token-optimizer](https://github.com/nadimtuhin/claude-token-optimizer), [superpowers](https://github.com/obra/superpowers), [vercel-labs/skills](https://github.com/vercel-labs/skills), [gstack](https://github.com/garrytan/gstack).
 
 ## 🔗 References
 

integrations/profiles.json

@@ -47,13 +47,14 @@
       "requires": []
     },
     "max": {
-      "description": "Everything on at once: code map + compression + terse output + all skills, agents, and hooks + measurement. Maximum token reduction.",
+      "description": "Everything on at once: the full external tool stack (rtk + code-review-graph + graphify + caveman + claude-handoff + gbrain) layered over agent-stack's built-ins, plus all skills, agents, hooks, and measurement. Maximum token reduction.",
       "graph": "builtin",
       "compression": "builtin",
       "caveman": true,
       "skills": ["stack-bootstrap", "stack-doctor", "stack-graph-profile", "stack-handoff", "stack-measure"],
       "agents": ["stack-explorer", "stack-reviewer"],
-      "requires": []
+      "requires": [],
+      "tools": ["rtk", "code-review-graph", "graphify", "caveman", "claude-handoff", "gbrain"]
     }
   }
 }