@mmerterden/multi-agent-pipeline 8.6.0

package/docs/adr/0001-three-model-triage.md

@@ -0,0 +1,81 @@
+# 1. CLI-aware parallel review with Opus triage
+
+**Status:** Accepted · 2025 · Amended 2026-04 (CLI-aware reviewer set)
+
+## Context
+
+Code review is the phase where the pipeline most commonly ships wrong work. A
+single reviewer model — whether Opus, Sonnet, or GPT — systematically misses
+certain failure classes and hallucinates others. Worse, reviewer output tends
+to be noisy: style nitpicks, out-of-scope findings, and repeated observations
+across diffs.
+
+We need a review stage that:
+
+1. Catches real bugs and security issues reliably.
+2. Doesn't block on false positives.
+3. Doesn't inflate token cost to the point the pipeline becomes unaffordable.
+
+## Decision
+
+Phase 4 runs **reviewers in parallel** on the same diff. The reviewer set is
+determined by the host CLI, because GPT-5.4 is only natively reachable from
+Copilot CLI — Claude Code has no first-class GPT bridge, and round-tripping
+would add latency without improving signal.
+
+**Claude Code (2 parallel reviewers):**
+
+- **Opus** — deep security and architecture focus
+- **Sonnet** — quality, correctness, naming
+
+**Copilot CLI (3 parallel reviewers):**
+
+- **Opus** — deep security and architecture focus
+- **GPT-5.4** — edge cases and cross-provider diversity
+- **Sonnet** — quality, correctness, naming
+
+Their raw findings are then passed to a **separate Opus triage agent** that
+classifies each finding as `accepted`, `deferred`, or `rejected`. Only
+`accepted` blocking items loop back to Phase 3 for rework.
+
+Deterministic gates (build, lint, test, secret scan) run before any AI
+reviewer is invoked — no point paying for review on code that doesn't build.
+
+## Consequences
+
+Positive:
+
+- Three different model lineages each catch a different slice of issues.
+- The triage pass filters the noise that individual reviewers can't filter
+  about themselves — it has scope context from Phase 1/2 that single reviewers
+  don't carry.
+- Hallucinated findings get rejected instead of looping the pipeline forever.
+- `validate-triage.mjs` enforces the triage output contract at runtime; a
+  malformed triage blocks progression with explicit error codes.
+
+Negative / costs:
+
+- On Copilot CLI, running three reviewers costs ~3× the review-phase tokens
+  vs. one reviewer. On Claude Code the 2-reviewer set costs ~2×. Offset: the
+  failure rate would otherwise force more Phase 3 re-runs, which are much
+  more expensive.
+- Triage agent introduces a single point of failure; validator + fallback
+  (treat all findings as accepted after double-failure) bounds the damage.
+- Cross-provider (GPT) dependency on Copilot CLI — if the provider is down,
+  the pipeline continues with 2 reviewers (Opus + Sonnet) and a warning.
+- Cross-CLI asymmetry: Copilot CLI catches a slice of failures (edge cases
+  via GPT diversity) that Claude Code's 2-model set misses. Accepted as a
+  tradeoff against platform reachability.
+
+## Alternatives Considered
+
+**Single reviewer (Opus only):** simpler, cheaper, but misses edge cases
+the other model lineages catch. Trialed in early v2 — noticeable false
+negatives on concurrency bugs.
+
+**Two reviewers + no triage:** cheaper still. Rejected because the raw
+finding noise overwhelmed Phase 3 loops in early experiments.
+
+**Tournament / voting:** all 3 reviewers, majority wins per finding. Too
+many false positives still slipped through majority vote when the same
+hallucination appeared in 2/3 reviewers (convergent failure mode).

package/docs/adr/0002-instruction-driven-flag.md

@@ -0,0 +1,62 @@
+# 2. `instructionDriven` flag as explicit pipeline fork
+
+**Status:** Accepted · 2025
+
+## Context
+
+The main 9-phase pipeline is TDD-centric. The Figma-to-SwiftUI workflow is
+config-driven (design tokens, Code Connect, Wiki generation) and does not
+map onto the red-green-refactor cycle. Earlier versions handled this with
+implicit branching in Phase 3 — "if the task has a Figma URL, fork here".
+
+Implicit branches had three problems:
+
+1. Hard to debug — no single place where the fork was decided.
+2. Silent failure when instruction files were missing or misnamed — Phase 6
+   would fall through to standard commit flow, losing Figma-specific steps.
+3. Phase 7 audit couldn't tell which branch was actually taken.
+
+## Decision
+
+Introduce an explicit boolean `instructionDriven` in `agent-state.json`
+(`agent-state.schema.json:95`). Set at Phase 0 Step 9 after inspecting the
+parsed task input (`figmaUrl` + detected instruction files). All downstream
+phases that need to fork read this flag.
+
+Phase 6 uses a **deterministic truth table** (documented at
+`phase-6-commit.md:25`) to dispatch:
+
+| `instructionDriven` | `instructionFiles.commit` exists | Action |
+| ------------------- | -------------------------------- | ------ |
+| true  | yes | Instruction-driven path |
+| true  | no  | Log error, set `instructionDrivenFallback=true`, use standard path |
+| false | —   | Standard path |
+
+## Consequences
+
+Positive:
+
+- Fork decision is a single, auditable flag in state.
+- Missing instruction files fail loud (`instructionDrivenFallback` surfaced in
+  Phase 7 report) instead of silent.
+- The Figma pipeline could be extracted to its own package without changing
+  main pipeline code — it just writes the flag + files, and the main pipeline
+  reads them.
+
+Negative:
+
+- Adds a schema field that must be maintained forever once shipped.
+- Introduces a coupling between the Figma pipeline's instruction file naming
+  and the main pipeline's expectations. Mitigated by documenting the contract
+  in `instructionFiles` schema sub-object.
+
+## Alternatives Considered
+
+**Implicit detection (current-task-has-Figma-URL):** previous approach.
+Rejected because a task might have a Figma URL but not need instruction-driven
+mode (e.g. `/multi-agent "Fix text spacing in FigmaDesign-X"`).
+
+**Separate top-level command (`/figma-to-swiftui` bypasses `/multi-agent`):**
+considered. Rejected because it duplicates the 9-phase scaffolding
+(branch creation, state management, Phase 6 commit flow). The current design
+lets Figma reuse Phases 0, 6, 7 wholesale.

package/docs/adr/0003-unified-shared-skills.md

@@ -0,0 +1,55 @@
+# 3. Unified `skills/shared/` for Claude Code + Copilot CLI
+
+**Status:** Accepted · 2026-04 (v3.5.0) · Amended 2026-04 (v5.3.3 — internal `core/external/` split, install destination unchanged)
+
+## Context
+
+Up through v3.4, skills were split into `pipeline/skills/claude/` (84 iOS-only)
+and `pipeline/skills/copilot/` (60 Android/web + pipeline). Zero overlap.
+Consequences:
+
+- Claude users could not invoke `multi-agent-*` pipeline skills (they were
+  Copilot-only).
+- Copilot users couldn't access iOS/SwiftUI guidance.
+- Two directories meant two places to add or update a skill — drift was
+  inevitable, and unnoticed.
+- README claim "145 skills" was not accurate for either CLI.
+
+## Decision
+
+Collapse both directories into `pipeline/skills/shared/`. Installer copies
+the same set to both `~/.claude/skills/` and `~/.copilot/skills/`. Both CLIs
+now ship with identical skill coverage (145 skills as of 3.5.0).
+
+Fifteen loose `*.md` files that were in the old copilot tree were normalized
+to the canonical `folder/SKILL.md` shape.
+
+## Consequences
+
+Positive:
+
+- Downloaders get the same capability regardless of which CLI flag they
+  installed with.
+- Adding a skill is now a single write.
+- Skill index (`pipeline/skills/shared/README.md`) auto-generates from a
+  single source.
+- Unblocks the 4.0 single-source-for-commands-and-skills plan — same
+  directory structure, just needs content unification.
+
+Negative:
+
+- Disk footprint per install is ~1.5× larger than before for users who
+  only wanted iOS or only wanted web.
+- Some iOS skills are noise for backend-only users and vice versa.
+  Mitigated by the categorized index — easy to browse and ignore.
+
+## Alternatives Considered
+
+**Keep two directories, add symlinks / install-time copy:** would have fixed
+the drift-risk but not the "which CLI gets what" asymmetry in the source.
+Hidden complexity.
+
+**Per-stack skill packs (`skills/ios/`, `skills/android/`, …) with
+install-time filter:** tempting. Rejected for 3.5.0 because the install-time
+filter would need a stack detector exact enough to not exclude relevant
+cross-cutting skills. Revisit for 4.0.

package/docs/adr/0004-zero-dependency-philosophy.md

@@ -0,0 +1,60 @@
+# 4. Zero runtime dependencies
+
+**Status:** Accepted · 2025
+
+## Context
+
+`package.json` dependencies are a long-term liability: each one is a
+supply-chain attack surface, a breaking-change source, and a peer-dep
+compatibility puzzle. For a CLI tool that installs itself into user shells
+and runs with write access to `~/.claude/` and `~/.copilot/`, the blast
+radius of a compromised dependency is large.
+
+At the same time, some conveniences — JSON Schema validators (`ajv`), YAML
+parsers (`yaml`), templating engines — would be trivial to pull in and would
+shorten a few scripts.
+
+## Decision
+
+`@mmerterden/multi-agent-pipeline` ships with **zero runtime dependencies**.
+Devs can add dev dependencies freely (ESLint, Prettier, c8), but the
+published package (the `pipeline/` tree, `install.js`, `index.js`) must
+import only from Node.js core modules.
+
+Consequences:
+
+- `validate-triage.mjs`, `validate-{reviewer,analysis,planning}.mjs`,
+  `write-state.mjs`, `migrate-state.mjs` all hand-roll their JSON Schema
+  validation. Slower to write, but zero attack surface.
+- `validate-schemas.mjs` is a shallow checker — catches "the schema file is
+  itself malformed", doesn't deep-validate every instance. That's what the
+  runtime validators are for.
+- Install is fast: `npm install` against the published package is a single
+  tarball, no transitive resolution.
+
+## Consequences
+
+Positive:
+
+- No supply-chain surface in the published package.
+- No Node version interop headaches — Node 18+ core APIs are stable enough.
+- `npx @mmerterden/multi-agent-pipeline install` runs instantly from cold.
+
+Negative:
+
+- Some scripts are longer than they'd be with a library.
+- Hand-rolled validators can drift from the JSON Schema they claim to enforce.
+  Mitigated by smoke tests: each validator has a matching `smoke-*.sh` with
+  ≥10 assertions covering the enum / edge paths.
+- Adding a new validator requires writing the boilerplate by hand.
+
+## Alternatives Considered
+
+**Pull in `ajv` for real schema validation:** clean and standard. Rejected
+because of supply-chain surface + bundle bloat (adds ~200 kB gzipped).
+
+**Optional deps — use `ajv` if installed, fall back otherwise:** too clever.
+"Sometimes validated, sometimes not" is worse than either extreme.
+
+**Bundle dependencies into the published tarball:** would remove the install-
+time resolution but keep the code surface. Defeats the point.

package/docs/adr/0005-lazy-phase-docs.md

@@ -0,0 +1,68 @@
+# 5. Lazy-loaded phase docs with per-phase token budget
+
+**Status:** Accepted · 2025
+
+## Context
+
+Phase specs are model-facing instructions. When the orchestrator (Claude Code
+or Copilot CLI) enters a phase, it reads the phase doc and follows the steps.
+If all phase docs were loaded up front, the context window would fill with
+instructions for phases not yet relevant, leaving less room for the actual
+code being worked on.
+
+Additionally, phase docs are the easiest part of the pipeline to inflate
+accidentally — examples, prose, caveats pile up. Without a budget, phase
+docs silently grow until they push useful content out of context.
+
+## Decision
+
+Each phase doc is a separate file (`pipeline/commands/multi-agent/refs/phases/
+phase-N-*.md`) that the orchestrator loads only when entering that phase.
+
+`pipeline/schemas/token-budget.json` defines `warn` and `max` thresholds per
+phase. The `smoke-token-budget.sh` check approximates token count for each
+phase doc and fails the build if any phase exceeds its `max`.
+
+Current budgets (v3.5.0):
+
+- Phase 0: warn 3500 / max 4000 (INIT is interactive + token-heavy)
+- Phase 1: warn 1200 / max 1500
+- Phase 2: warn  800 / max 1000
+- Phase 3: warn 1500 / max 1800
+- Phase 4: warn 1800 / max 2200 (triage + 3-model review is verbose)
+- Phase 5: warn  600 / max  800
+- Phase 6: warn 2400 / max 2800 (commit + PR + issue body update)
+- Phase 7: warn 1800 / max 2200
+
+Total phase doc budget: 14,300 tokens across 8 phases, loaded incrementally.
+
+## Consequences
+
+Positive:
+
+- Context window stays available for the code under review.
+- Budgets surface "this phase is getting bloated" early (warn) before they
+  become blocking (max).
+- A PR that inflates a phase doc past `max` fails CI — hard forcing function
+  against doc rot.
+
+Negative:
+
+- Cross-phase references require either duplication (bad) or jumping back to
+  a phase's doc (imperfect). Mitigated by keeping phase docs self-contained
+  and putting cross-cutting rules in `refs/rules.md`, loaded once at Phase 0.
+- The token estimator is approximate (character-count based); true token
+  cost varies by model. Budgets err on the generous side to avoid false
+  failures.
+
+## Alternatives Considered
+
+**Single monolithic phase doc:** what the pipeline started with. Rejected
+after `modes.md` + phase docs added up to >8K tokens just for instructions.
+
+**Dynamic budget (load until context fills):** too lossy. Some phases
+(Phase 4 triage) would silently lose content mid-instruction.
+
+**Per-model budgets (Opus gets bigger, Sonnet gets smaller):** over-engineered
+for current needs. Same budgets work across the models the pipeline uses
+today. Reconsider if per-model skew becomes measurable.

package/docs/adr/0006-skills-core-external-split.md

@@ -0,0 +1,52 @@
+# 6. `shared/core/` vs `shared/external/` source organization
+
+**Status:** Accepted · 2026-04 (v5.3.3)
+
+## Context
+
+ADR-0003 (v3.5.0) collapsed the split `skills/claude/` + `skills/copilot/` into a single `skills/shared/` tree. That resolved drift between CLIs and made skill authoring a single-write operation. Two years later the flat tree carries 148 directories.
+
+By v5.3.x the maintenance burden of the flat tree became visible in everyday work:
+
+- **Source navigation.** Browsing `pipeline/skills/shared/` on GitHub shows 148 sibling directories with no hint which ones are load-bearing for the pipeline vs. which ones are third-party imports.
+- **Code review cost.** Changes under `shared/` have very different risk profiles depending on which kind of skill changed. `multi-agent-sync/SKILL.md` is pipeline-critical — any drift breaks cross-CLI parity. `ios-developer/SKILL.md` is a reference guide imported from upstream — edits almost never affect pipeline behavior.
+- **Grep noise.** `grep -r skills/shared/` produces 148× the noise it should when searching for pipeline code.
+- **Audit findings.** The v5.3.0 audit flagged this as technical debt worth addressing once the pipeline stabilized.
+
+## Decision
+
+Keep the single-write benefit of ADR-0003. Split the source layout into two subdirectories by origin / blast radius:
+
+```
+pipeline/skills/shared/
+├── core/         — 21 multi-agent* orchestration skills (pipeline-critical)
+├── external/     — 127 iOS / Android / generic skills imported from upstream
+└── README.md     — skill index
+```
+
+**Install destination is unchanged.** Both trees flatten into `~/.claude/skills/` and `~/.copilot/skills/`; skill discovery at runtime sees the same flat list of 148 skills regardless of where they live in source. ADR-0003's core decision ("same coverage on both CLIs") is preserved.
+
+`install.js` was updated to `copyDir(sharedCoreSrc, CLAUDE_SKILLS)` + `copyDir(sharedExternalSrc, CLAUDE_SKILLS)` — two reads, same flat write.
+
+## Consequences
+
+Positive:
+
+- Source browsing separates the 21 files that get changed by pipeline work from the 127 that get refreshed on upstream sync.
+- Code review can apply different scrutiny by subdirectory. A PR touching `external/*` is almost always a mechanical refresh; a PR touching `core/*` is pipeline logic.
+- Grep / Glob queries can scope to `core/` or `external/` cheaply (`rg --glob 'shared/core/**'`).
+- Prepares for a future per-stack install filter (ADR-0003's deferred "skills/ios/" idea) by making "external" a single unit.
+
+Negative:
+
+- `install.js` walks two source trees instead of one. Implementation cost: 6 lines.
+- Every smoke test and doc reference that hard-coded `pipeline/skills/shared/multi-agent-*/` as a path had to update to `pipeline/skills/shared/core/multi-agent-*/`. One-time sweep.
+- ADR-0003's "single source of truth" wording becomes "single install target from two logical sources" — slightly more nuance to explain.
+
+## Alternatives Considered
+
+**Per-stack tree (`skills/ios/`, `skills/android/`, ...):** the original idea ADR-0003 deferred. Rejected for v5.3.x because install-time stack filtering still needs a stack detector accurate enough not to exclude relevant cross-cutting skills (e.g. `api-security-best-practices` applies to both backend and mobile). Revisit when the stack-detection story is solid.
+
+**Leave the flat tree alone:** the 148-dir tree is cosmetically ugly but functionally correct. Rejected because the blast-radius distinction between `multi-agent*` skills and upstream mirrors is real and recurring; naming it in the source layout documents it.
+
+**Soft categorization via `SKILL.md` frontmatter (`category: core`):** would support tooling but wouldn't help the primary use case (source browsing on GitHub). Rejected as insufficient on its own.

package/docs/adr/0007-multi-tool-adapter-framework.md

@@ -0,0 +1,110 @@
+# 7. Multi-tool adapter framework + token-preserving uninstall
+
+**Status:** Accepted · 2026-04-27 (v7.7.0 / v7.9.0)
+
+## Context
+
+Through v7.6, the pipeline shipped to two CLIs only: Claude Code and Copilot CLI. Both expose **subagent dispatch** — the ability for the orchestrator to fan out work to parallel sub-agents with their own model, prompt, and context. This is a hard prerequisite for the 8-phase pipeline (Phase 1 parallel exploration, Phase 4 multi-reviewer review, Phase 7 multi-channel reporting).
+
+Users started asking: "can it work with Cursor / Windsurf / Cline / Copilot Chat / Continue / Zed?" The honest answer is mixed:
+
+- **Subagent dispatch:** none of those tools expose it. So the orchestration layer cannot run there; only single-shot rules / instructions are loaded into a chat context.
+- **Knowledge layer:** the pipeline's value is split roughly 30/70 between orchestration and content. The 193 SKILL.md catalog + 12 rules describe how to write good Swift / Compose / TypeScript / etc. — that part is genuinely portable and would benefit users on tools where the orchestration can't run.
+
+Three forces shaped this decision:
+
+1. We didn't want to fork the project per tool.
+2. We didn't want to silently drop support claims (e.g. saying "works with Cursor" when only the rules were loaded but the user expected `:dev` and `:review` to run).
+3. We needed a clean opposite for every install path. Once `npx ... install --cursor` writes 174 files into a user's repo, there must be a documented, **token-preserving** way to remove them all in one step.
+
+## Decision
+
+We introduce a tiered support model and a uninstaller that's contractually forbidden from touching credential storage.
+
+### Tier 1 — Full pipeline (orchestration + knowledge)
+
+Tools with subagent dispatch get the full 8-phase pipeline.
+
+- **Claude Code** (default, `--claude`)
+- **Copilot CLI** (`--copilot`)
+
+Both install slash commands / skills, agent personas, scripts, rules, and the full skills tree to `$HOME/.claude/` or `$HOME/.copilot/`.
+
+### Tier 2 — Knowledge layer only (v7.7.0)
+
+Tools without subagent dispatch but with a documented rules / instructions format. Pipeline orchestration commands are filtered out (they have no callable surface here); rules + skills catalog port natively to each tool's format.
+
+- **Cursor** (`--cursor`) — `.cursor/rules/multi-agent-*.mdc` + `.cursorrules` legacy fallback
+- **Windsurf** (`--windsurf`) — `.windsurfrules` (single file, marker-wrapped)
+- **Cline** (`--cline`) — `.clinerules/multi-agent-*.md` per-skill files
+
+### Tier 3 — Knowledge layer (v7.9.0)
+
+Three more tools with the same contract.
+
+- **GitHub Copilot Chat** (`--copilot-chat`) — `.github/copilot-instructions.md` marker-wrapped + `.github/instructions/multi-agent-*.instructions.md` per-skill
+- **Continue.dev** (`--continue`) — `.continue/rules/multi-agent-*.md` per-skill
+- **Zed AI** (`--zed`) — `.rules` single file, marker-wrapped
+
+### Tier 4 — Manual port
+
+Closed/proprietary tools (JetBrains AI, Codeium, Tabnine, Amazon Q Developer) get no automated installer. Skill content can be copy-pasted; PRs welcome.
+
+### Adapter framework
+
+All non-Tier-1 adapters share `pipeline/adapters/_base.mjs`:
+
+- **`parseFrontmatter`** / **`walkSkills`** — read SKILL.md, return name + frontmatter + body
+- **`inferGlobs`** — map skill name → glob pattern (`**/*.swift`, `**/*.{kt,kts}`, etc.) for tools that scope rules by file pattern
+- **`replaceManagedBlock`** / **`removeManagedBlock`** — read/write/strip the `<!-- multi-agent-pipeline:begin / end -->` marker pair inside a user-owned file. Lets us share rules files (`.windsurfrules`, `.rules`, `copilot-instructions.md`) with content the user already authored.
+- **`withoutOrchestrationSkills`** — filter `multi-agent-*` core skills (the orchestration namespace) from the export. They have no callable surface in Tier 2 / Tier 3 tools.
+- **`concatSkills`** — single-document concatenation for adapters that emit one rules file (Windsurf, Zed) instead of per-skill files.
+
+Each adapter exports a `{ name, install, uninstall }` contract. New adapters are mostly format-mapping over this base; adding a fourth would be ~150 LOC.
+
+### Token-preserving uninstall
+
+Every install path has a documented opposite via `npx @mmerterden/multi-agent-pipeline uninstall` (or `delete` alias). Slash command: `/multi-agent:delete` with a Copilot CLI peer `multi-agent-delete`.
+
+The uninstaller is **contractually forbidden** from touching:
+
+1. Personal access tokens stored in macOS Keychain / Windows Credential Manager / Linux libsecret.
+2. `~/.claude/CLAUDE.md` and `~/.claude/multi-agent-preferences.json` (user customizations).
+3. User content outside the `<!-- multi-agent-pipeline:begin / end -->` markers in any shared rules file.
+
+The contract is enforced statically by `smoke-delete-flow.sh` step 7:
+
+```bash
+grep -qE "credential-store|delete-generic-password|cmdkey /delete|secret-tool clear" uninstall.mjs
+# fail varsa exit 1 — pattern eklenirse build kırılır
+```
+
+A future refactor that adds any credential-store deletion API to the uninstaller fails the build before it ships. Same posture for adapter modules: `smoke-adapters-tier3.sh` step 6 scans every Tier 3 adapter file.
+
+## Consequences
+
+Positive:
+
+- One framework, six adapter targets. Tier 4 tools could be added incrementally without touching the orchestrator.
+- Clear contract about what works where: Tier 1 = full pipeline, Tier 2/3 = knowledge layer only, Tier 4 = manual. No overpromising.
+- Marker-wrapped blocks let us cohabit user-authored content cleanly. Users who ran `--zed` then later edited their `.rules` get their content back after `uninstall --zed`.
+- Token-preserving uninstall is a reversible commitment. Removing the pipeline can never accidentally cost the user a re-auth round across Jira / GitHub / Bitbucket / Confluence / Vercel / Firebase / Telegram.
+- Installer flag set is backward-compatible: zero-flag default still installs Claude Code exactly as v7.6 did.
+
+Negative / costs:
+
+- 6 adapters means 6 places where the format mapping can drift from upstream tool changes. Mitigation: round-trip smoke tests for each adapter exercise install + uninstall on every PR.
+- `--all-tools` writes ~900 files (174 cursor + ~50 windsurf concat + 173 cline + 161 copilot-chat + 161 continue + 1 zed) into the user's repo. Acceptable — `.gitignore` patterns already cover most of these (`.cursor/`, `.continue/`, `.clinerules/`), and `:delete` cleans them all in one step.
+- Per-tool format drift across tool versions (e.g. Cursor's `.mdc` format changes in 2027) requires per-adapter maintenance. Insulated from the orchestrator: bumping a Tier 2/3 tool format never touches Phase 1-7 logic.
+
+## Alternatives Considered
+
+**Refuse non-orchestration tools entirely:** simplest. Rejected because users on Cursor / Copilot Chat are a large slice of the pipeline's potential audience, and they get real value from the rules + skills catalog even without orchestration.
+
+**Single "universal rules format" exported once, users hand-port:** simpler ship, but every user repeats the porting work, and no idempotent uninstall is possible without per-tool knowledge of where the rules ended up.
+
+**Symlink mode (one rules dir, every tool reads from it):** elegant but no Tier 2/3 tool actually supports a single canonical location. Each tool insists on its own path (`.cursor/rules/`, `.windsurfrules`, `.clinerules/`, etc.).
+
+**Generate adapters from a manifest at install time** instead of shipping per-adapter `.mjs` files: less code in the repo, but worse DX (debugging a generated adapter is painful) and harder to test per-tool round-trips. Per-adapter modules with shared `_base.mjs` won the readability tradeoff.
+
+**Allow uninstall to clean credential entries:** rejected outright. Removing the tool should be a reversible decision; re-auth across Jira / GitHub / Bitbucket / Confluence / Vercel / Firebase / Telegram on every install + uninstall cycle is a poor user experience. The static check makes this guarantee permanent.

package/docs/adr/0008-installer-modularization-and-secret-leak-defense.md

@@ -0,0 +1,98 @@
+# 8. Installer modularization + secret-leak defense
+
+**Status:** Accepted · 2026-04-27 (v8.0.0)
+
+## Context
+
+Two pressures collided during the v7.x line:
+
+1. **Installer monolith.** `install.js` reached 1246 LOC by v7.9.1. It mixed flag parsing, three platform installers (Claude / Copilot / six third-party adapters), telemetry, a dev-only file exclusion list, and a 200-line static generator for `copilot-instructions.md`. Reasoning about install behaviour required holding the whole file in your head; reviewers asked for documentation we could not produce because every change touched untyped, intertwined sections.
+
+2. **Secret leaks at deploy time.** During the v7.9.1 production deploy of `mmerterden.dev`, a `vercel deploy --token=vcp_…` invocation failed. The Vercel CLI printed the failed argv verbatim in its retry hint. That leaked the deploy token into the conversation transcript and forced a token rotation. A second incident in the same release window — `git -c user.email=…` overriding the repo-local config — pushed seven commits with the wrong author identity, which Vercel's contributor gate then blocked. Both classes of failure share a root cause: privileged values flowed through argv when the codebase had no audited boundary between provider tools and the orchestration layer.
+
+We needed an architectural answer that prevented both classes of failure from recurring without expanding scope into "rewrite everything as TypeScript" — the project's zero-dependency philosophy (ADR-4) is a hard constraint.
+
+## Decision
+
+### 1. `install.js` becomes a 24-line shim; logic moves under `install/`
+
+The monolith splits into focused modules under `install/`:
+
+```
+install/
+  index.mjs                  — entry point, flag parsing, dispatcher
+  claude.mjs                 — Claude Code installer
+  copilot.mjs                — Copilot CLI installer
+  _adapters.mjs              — third-party adapter dispatch
+  _common.mjs                — shared FS helpers (copyDir, ensureDir, …)
+  _platform-filter.mjs       — --platform=ios|android filter
+  _telemetry.mjs             — opt-in install telemetry
+  _copilot-instructions.mjs  — generator for ~/.copilot/copilot-instructions.md
+  _dev-only-files.mjs        — single source of truth for excluded files
+```
+
+`install.js` keeps its bin entry contract (24 lines, just `import { runInstall } from './install/index.mjs'; await runInstall(process.argv)`). Existing invocations — `npx … install --all`, the `package.json` `./install` export, every smoke test that runs `node install.js` — continue working without API changes. The package.json `files` array adds `install/**/*` so npm publish ships the new modules.
+
+### 2. Install layout is now a regression gate
+
+`pipeline/scripts/smoke-install-layout.sh` (35 assertions) runs the live installer into a temp HOME and proves:
+
+- All 9 expected modules exist under `install/`.
+- `install.js` is under 50 lines and imports `install/index.mjs`.
+- `--claude`, `--copilot`, `--all` produce the same on-disk tree the v7.x monolith produced (file counts, hook registration, multi-agent skill pruning).
+- Cross-target file count parity for shared scripts and agents.
+
+Future refactors must keep this smoke green. Drift is detected before it ships, not after.
+
+### 3. Provider tools wrap CLIs that leak credentials
+
+`pipeline/lib/vercel-deploy.sh` is the safe wrapper around the Vercel CLI. Three properties hold for every invocation:
+
+1. Tokens flow through `VERCEL_TOKEN` env var. The wrapper refuses to deploy if `--token=` appears anywhere in argv — that pattern was the v7.9.1 leak.
+2. Every stdout/stderr line is piped through a `redact_filter` sed pass that scrubs `--token=…`, `vcp_…`, `Bearer …`, `"token":"…"`, and `"VERCEL_TOKEN":"…"` shapes.
+3. Failed deploys exit with a clear marker line; the wrapper does not echo the original argv that the CLI printed in its retry hint.
+
+`pipeline/scripts/smoke-vercel-deploy-redact.sh` (12 assertions) is the regression gate for the redact filter. Each known leak shape has a fixture that must NOT survive redaction.
+
+### 4. Mode dispatch generator + drift smoke
+
+`pipeline/scripts/gen-mode-dispatch.mjs` is the canonical source for the "Required: Phase Tracker Contract" section embedded in every mode dispatch file. `pipeline/scripts/smoke-mode-dispatch-drift.sh` (61 assertions) verifies each mode file declares the right phase list (4-phase for `dev*`, 8-phase for `local`/`autopilot`) and links `refs/tracker-contract.md`.
+
+### 5. Cross-phase cohesion smoke
+
+Schema validation proves each schema is well-formed. It does not prove that producer / consumer phase docs both reference the schema they hand off. `pipeline/scripts/smoke-cross-phase-cohesion.sh` (17 assertions) adds the cohesion gate: Phase 1 → Phase 2 (`analysis-output`), Phase 2 → Phase 3 (`planning-output`), Phase 4 → Phase 4 triage (`reviewer-output`), Phase 4 triage → Phase 6 (`triage-output`), and Phase 6 → Phase 7 (`agent-state`) hand-offs are documented on both sides.
+
+### 6. CI matrix splits into full + lite workflows
+
+`.github/workflows/test.yml` keeps the full matrix (Ubuntu/macOS/Windows × Node 20/22 + credential-store round-trips). `.github/workflows/ci-lite.yml` is the workflow_dispatch-only fast lane (Ubuntu + Node 22, no credential round-trips, ~3 minutes). The lite workflow is the one contributors run via `act` while billing is paused; the full matrix runs on demand for releases.
+
+### 7. Recovery guide gains four new playbooks
+
+`docs/recovery-guide.md` adds: worktree corruption, tracker state corruption, token rotation mid-pipeline, and failed-push force-with-lease decision tree. All four were learned from the v7.9.1 release window.
+
+## Consequences
+
+**What gets easier:**
+
+- Reading the installer. Each module is < 300 LOC and has a single responsibility.
+- Reviewing installer changes. A diff that touches `install/copilot.mjs` is bounded; reviewers do not need to skim 1246 lines of context.
+- Auditing for credential exposure. Every Vercel call goes through one wrapper; future provider integrations follow the same pattern (next: deploy-to-Cloudflare wrapper, npm publish wrapper).
+- Detecting doc drift. Smokes catch missing schema references before docs ship to users.
+
+**What gets harder:**
+
+- Adding a brand-new install target. The contributor must touch `install/index.mjs` (flag wiring), create `install/<target>.mjs` (installer), update `smoke-install-layout.sh` (assertion). That's three files instead of one — but the boundaries are sharp and a smoke fails loudly if anything is missed.
+- Maintaining the static `_copilot-instructions.mjs` generator. The body still has to match the source-of-truth content in `pipeline/commands/multi-agent/`. Plan: in v9 we replace the static template with a generator that reads the actual phase files. For v8 the smoke `smoke-multi-repo-integration.sh` already greps the generator output for canonical strings, so drift is detected.
+
+**What we explicitly chose not to do:**
+
+- Migrate to TypeScript. The zero-dependency rule (ADR-4) still holds; TS would force a build step.
+- Move the install layout assertions into a unit test. Bash + `find` is the right tool — the assertions check a real filesystem tree, not pure logic.
+- Auto-rotate Vercel tokens on detected leak. Rotation is a user decision; the wrapper just makes leaks harder, never silently mints replacements.
+
+## References
+
+- `install/` directory split (this ADR)
+- `pipeline/lib/vercel-deploy.sh` — secret-leak defense wrapper
+- `pipeline/scripts/smoke-install-layout.sh`, `smoke-vercel-deploy-redact.sh`, `smoke-mode-dispatch-drift.sh`, `smoke-cross-phase-cohesion.sh` — regression gates
+- `feedback_vercel_cli_token_leak.md`, `feedback_git_author_repo_local.md`, `feedback_explicit_consent_for_push.md` — incident retrospectives that drove this work

package/docs/adr/README.md

@@ -0,0 +1,33 @@
+# Architecture Decision Records
+
+ADRs capture the reasoning behind architectural choices so future changes
+don't re-litigate the same debates or accidentally reverse a load-bearing
+decision.
+
+Format: lightly adapted from [Michael Nygard's ADR template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Index
+
+| # | Title | Status |
+|---|-------|--------|
+| [0001](./0001-three-model-triage.md)   | CLI-aware parallel review with Opus triage         | Accepted (amended v5.2.2) |
+| [0002](./0002-instruction-driven-flag.md) | instructionDriven flag as explicit pipeline fork  | Accepted |
+| [0003](./0003-unified-shared-skills.md) | Unified `skills/shared/` for Claude Code + Copilot | Accepted (amended v5.3.3) |
+| [0004](./0004-zero-dependency-philosophy.md) | Keep the package zero-runtime-deps                | Accepted |
+| [0005](./0005-lazy-phase-docs.md)      | Lazy-loaded phase docs with per-phase token budget | Accepted |
+| [0006](./0006-skills-core-external-split.md) | `shared/core/` vs `shared/external/` source org    | Accepted |
+| [0007](./0007-multi-tool-adapter-framework.md) | Multi-tool adapter framework + token-preserving uninstall | Accepted (v7.7.0 / v7.9.0) |
+
+## Writing a New ADR
+
+1. Copy `0001-three-model-triage.md` as the template shape.
+2. Increment the number.
+3. Fill in: Context, Decision, Consequences, Alternatives.
+4. Set status to `Proposed` in a PR; the merging reviewer flips it to
+   `Accepted` once discussion closes.
+5. Add the row to the index table above.
+
+## Changing a Past Decision
+
+Don't rewrite ADRs — write a new one that supersedes the old. Set the old
+ADR's status to `Superseded by 00NN` and link both ways.