@mhd-ghaith-abtah/flow 0.7.2-beta.0 → 0.8.0-beta.1

package/CHANGELOG.md

@@ -6,6 +6,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0-beta.1] — 2026-05-23
+
+### Added
+- **`flow install-skills` command** — closes the bootstrap gap between npm install and Claude Code slash command discovery. After `npm install -g @mhd-ghaith-abtah/flow@beta`, run `flow install-skills` to symlink the four `skills/flow-*` directories into `~/.claude/skills/` (or `<project>/.claude/skills/` with `--scope project` for the team-commit pattern; `--scope both` for both). Idempotent (skips already-correctly-linked targets); refuses to clobber real directories at the target without `--force`; replaces wrong-source symlinks silently. 9 new tests covering home/project/both scopes, refusal-without-force, force-replace, dry-run, idempotent re-run, and wrong-source-symlink replacement. README + docs/usage.md updated with the corrected bootstrap order (`npm install -g` → `flow install-skills` → `/flow-init`).
+
+## [0.8.0-beta.0] — 2026-05-23
+
+### Added
+- **E6-006 — `flow init --yes` headless orchestrator + integration tests** — closes E6. `lib/init/orchestrate.js` chains `detect()` → `askAll()` (pre-populated answers short-circuit each prompt) → upstream dispatchers (bmad → ecc → caveman, halt-on-error by default, `--continue-on-error` to override) → MCP registration → optional BMad migration → `scaffold()` (writes `flow.config.yaml` + `docs/flow/{stories,journeys,retros,archive}` + `sprint.yaml` + `deferred.md` + `install-state.json`). `lib/init/scaffold.js` exports pure `buildFlowConfig(plan)` and `scaffold(plan, opts)` with `--force` overwrite + skip-existing semantics; `defaultAnswersForProfile(catalog, profile, overrides)` resolves a profile into a complete Answers object so non-interactive callers (CI, tests) drive the full chain without firing any prompt. `lib/commands/init.js` rewritten: outside Claude Code with `--yes` → runs the orchestrator end-to-end and prints a manifest; outside Claude Code without `--yes` → prints both paths (headless vs slash-command); inside Claude Code → nudges to `/flow-init` slash command (skill workflow still owns the interactive ceremony per ROADMAP principle #6). README install section updated with the new headless flow. 13 new tests across orchestrate (chain logic, scope override threading, BMad migration trigger) + scaffold (file content shape, force/skip behavior, dryRun manifest); orchestrate tests deliberately stay `dryRun: true` to avoid shelling out (each upstream dispatcher would otherwise `npx`-fetch real network packages). 156/156 pass (was 143, +13).
+
+### Added
+- **E6-005 — `flow sprint <subcommand>` CLI** — pure-YAML headless port of the non-LLM `/flow-sprint` subcommands. Six subcommands wired: `add` (append a story with explicit id/title/epic + optional tags/why/issue/status), `next` (flip first backlog story to doing, stamp `started_at`), `status` (grouped-by-epic render with per-epic and overall counts; `--json` for scriptable output), `done <id>` (flip to done, stamp `completed_at`, append `--note` to notes array; refuses non-review/doing sources without `--force`), `deferred` (parse + render `docs/flow/deferred.md`), `import-bmad` (wraps `migrate-bmad.js` — same backup/rollback semantics). Round-trip preservation: `lib/sprint/store.js` uses yaml's Document API rather than parse+stringify so comments + ordering survive each mutation. Operations live in `lib/sprint/operations.js` as pure functions (addStory, nextStory, setStatus, summarize, parseDeferred); `lib/commands/sprint.js` is the thin CLI shell on top. Wired into `bin/flow.js` USAGE + dispatch + yargs string/boolean lists (new flags: `--id`, `--title`, `--epic`, `--tags`, `--why`, `--issue`, `--note`, `--project`, `--status`, `--force`). LLM-driven `retro` and `scope-review` stay slash-command-only per ROADMAP principle #6 (one source of truth per behavior). 21 new tests (143/143 pass) covering happy paths, duplicate-id rejection, unknown-epic rejection, missing-field validation, --force semantics, note appending, round-trip comment preservation, --epic restriction for next, orphan-epic bucket in summarize, and parseDeferred open-vs-resolved separation.
+
+### Added
+- **E6-004 — `lib/init/migrate-bmad.js` BMad → Flow migration** — headless port of `/flow-init` step 11. Public surface: `findBmadState(cwd)`, `parseBmadStories(yaml)`, `parseBmadDeferred(md)`, `backupBmadState(state, ts)`, `migrate(cwd, opts)`, `rollback(cwd, ts)`. Migration writes `docs/flow/sprint.yaml` + per-story stubs under `docs/flow/stories/` + `docs/flow/deferred.md`. Backup-first: every source file gets a `.flow-backup-<ts>` copy before any write; if backup fails, halt before any mutation; if parse/write fails, automatic rollback restores backups + removes the produced `docs/flow/` tree (only when it didn't pre-exist — pre-existing Flow content survives rollback via a sentinel-file check). BMad status → Flow status mapping (`in-progress → doing`, `ready-for-dev → backlog`, etc.) with backlog as the unknown-value fallback so migration is non-lossy. Handles both flat-map and nested `stories:` shapes in BMad's sprint-status. `_bmad/` is intentionally left in place so BMad slash commands keep working post-migration. 15 new tests covering parse edge cases (nested shape, unknown statuses, non-story keys), backup creation, end-to-end migration with stub generation + status mapping verification, malformed-input rollback path, and pre-existing-docs/flow preservation. 122/122 pass.
+
+### Added
+- **E6-003 — `lib/init/mcp.js` MCP dispatcher** — headless port of `/flow-init` step 9. Exports `buildCommand(mcp)` (pure), `isInstalled(mcp, opts)` (probes `claude mcp list`), `install(mcp, opts)`, `installAll(mcps, opts)`, `resolveMcps(catalog, ids)`. Idempotent by default: skips MCPs that already appear in `claude mcp list` unless `force=true`. Auth handling stays out of the dispatcher — it surfaces `requiredEnv` (for `api_token` MCPs) and `authInstructions` (for `oauth_browser`) in the result so the orchestrator can route secrets to whatever store the user picked at Q9, and `flow doctor` can reuse the same module to report MCP state without touching secrets. State record carries `auth`, `scope`, and `auth_state: 'pending'` for oauth flows so doctor knows when an MCP isn't usable yet. 8 new tests covering tokenization, resolveMcps unknown-id throw, auth=none / oauth_browser / api_token paths, and installAll sequencing. 107/107 pass.
+
+### Added
+- **E6-002 — `lib/init/upstreams/{bmad,ecc,caveman}.js` + `common.js` dispatchers** — pure `buildCommand(plan)` + async `install(plan, opts)` for each upstream. BMad assembles `npx bmad-method install --tools claude-code --yes --modules a,b,c` from the curated subset. ECC resolves an `installer_path` from local candidates first then falls back to the github-pinned `npx -y -p "github:affaan-m/ECC#98bd5174" ecc-install`; routes `--target` via the E7-003 `target_by_scope` map (`user → claude`, `project → claude-project`). Caveman runs the fork-pinned `npx -y "github:mhd-ghaith-abtah/caveman#flow-pin-v0.1"` and honors `FLOW_INSPECT_INSTALL_SCRIPTS=1` by halting before execution (returns `inspect_only: true` in the state record + a hint at how to review the fork). All three short-circuit on `subset === 'none'` so the orchestrator can call them uniformly. State records include `install_scope` (ECC), `fork_tag` + `upstream_pr` (Caveman), and `modules` (BMad) so `flow doctor` can read them. 18 new tests cover command shape, target routing, `--with`/`--without` plumbing, missing-target throw, inspect-only skip path, and `subset=none` no-op. 99/99 pass.
+
+### Added
+- **E6-001 — `lib/init/detect.js` + `lib/init/questions.js` + `lib/init/recommendation.js`** — port of the `/flow-init` skill workflow's project-detection and Q&A primitives into pure Node modules. `detect()` returns a typed `Detection` (git root, package manager, primary stack, framework, BMad/ECC/Caveman presence with versions, existing MCPs, available CLIs, flow-already-configured). `recommendProfile(detection)` picks one of `minimal | mini | standard | team` from the detected shape with a one-line reason. `questions.js` exports `askProfile`, `askIssueTracker`, `askPr`, `askE2e`, `askVerify`, `askBmadSubset`, `askEccSubset`, `askEccScope`, `askCavemanSubset`, `askMigrateBmad`, `askSecretsStore`, and `askAll` (composed flow). All prompts use `@inquirer/prompts` and short-circuit on pre-populated answers so `--yes`-style zero-question installs can drive the same code path. 19 new tests covering detection edge cases (bare dir, lockfile variants, framework, CLAUDE.md, ECC user-scope + project-scope + collision, BMad version parse, Caveman plugin-cache + legacy hook detection) and the recommendation decision tree. Tests 81/81 pass (was 62). Foundation for E6-002 → E6-006.
+
+### Added
+- **E7-004 — `flow doctor` probe for ECC scope collision** — new `Collisions` section in the doctor report. Detects when ECC content exists at BOTH `~/.claude/rules/ecc` and `<cwd>/.claude/rules/ecc` (the scenario where a user switched `--ecc-scope` without uninstalling the prior scope's content). Severity `⚠` (exit 1) because both scopes loading the same skill set into Claude Code at once is confusing and skill-resolution order is undefined. The fix-hint reads `install_scope` from `install-state.json` to identify which directory is the *active* one and suggests `rm -rf <stale_dir>`; falls back to a "set the scope first via /flow-init or --ecc-scope, then clean up" message when no scope is recorded. Cheap probe (two `existsSync` calls), runs on every `flow doctor`. 3 new tests covering collision-detected / no-collision / unknown-scope hint. 62/62 pass.
+
+### Changed
+- **E7-005 — Profiles + README documented for the ECC scope option** — `docs/profiles.md` gained an "ECC scope" column in the at-a-glance table, a per-profile `ECC install scope` line under each profile (`user` for mini/standard/minimal/default, `project` for team), and a new "ECC install scope" section explaining the 3-layer resolution (catalog default → profile → `--ecc-scope` CLI override). README FAQ caveat updated to describe shipped behavior (was: "ships in v0.8 once E7-002 → E7-005 land"; now: "team defaults to project, others to user, override via `--ecc-scope`"). E7 epic body of work (E7-001 upstream PR + E7-002 catalog plumbing + E7-002.5 CLI flag + E7-003 install consumer + E7-005 docs) now ends.
+
+### Added
+- **E7-003 — Install path consumes the scope flag** — `catalog.yaml > upstreams.ecc.installer` gained `target_arg` + `target_by_scope` (`user → claude`, `project → claude-project`). `base_args` is now scope-agnostic (was `--target claude` hardcoded). `/flow-init` skill workflow updated to compose the install command from `target_arg` + `target_by_scope[ecc_install_scope]` and record `install_scope` + `target` in install-state. `flow doctor --repair-upstream ecc` now reads the recorded scope and emits the right install command (project-scope users get `--target claude-project` + `<projectRoot>/.claude/rules` paths; user-scope unchanged). Also fixed the doctor command's stale `npx @everything-claude-code/ecc install --target claude` reference — same bug as the catalog `cmd_fallback` typo, now resolved by reusing the post-merge github pin. 1 new test for project-scope routing; existing test extended with scope assertion. 59/59 pass.
+- **`--ecc-scope <user|project>` CLI flag** — explicit override on top of the profile default for `flow plan` and `flow install`. Lets users pick a non-default scope without authoring a new profile (e.g. `flow install --profile team --ecc-scope user` or `flow plan --profile mini --ecc-scope project`). Throws on invalid value so typos like `--ecc-scope=projet` fail loud instead of silently falling through to the profile default. 4 new tests covering override directions + typo guard.
+- **E7-002 — Catalog `ecc_install_scope` plumbing** — `upstreams.ecc.install_scope_default` (defaults to `user`) and per-profile `ecc_install_scope` (`user|project`) flow through `resolveProfile` so the resolved profile exposes the scope to downstream consumers. `team` profile now declares `ecc_install_scope: project`; `minimal`/`mini`/`standard` inherit `user`. `flow plan` surfaces the scope next to the ECC subset (e.g. `ECC:  flow-essentials-plus-tdd  (scope: project)`). Schema + JSDoc updated. Data plumbing only — E7-003 will consume the field to swap `--target claude` → `--target claude-project` at install time. 3 new tests (54/54 pass).
+
+### Changed
+- **ECC installer pinned to post-merge github commit** — `catalog.yaml` ECC `cmd_fallback` now `npx -y -p "github:affaan-m/ECC#98bd5174" ecc-install` (was a broken `npx @everything-claude-code/ecc install` reference — wrong package name, returned 404). The pin targets the merge commit of affaan-m/ECC#2006 (`claude-project` install target) so Flow can route the team profile to project-scope ECC. ECC npm `latest` is currently `ecc-universal@1.10.0` (2026-04-15), which predates the merge by ~36 days, so the npm package would NOT have the target. New catalog fields: `upstream_npm_package`, `upstream_npm_latest`, `upstream_npm_status`, `pinned_commit`. Will swap back to `npx ecc-universal install` once affaan-m cuts a `2.x` release. Also fixed stale `installer_path_candidates` entries (removed a global-npm path that referenced the bogus package name; added `~/development/personal/ecc-fork/install.sh` for contributors with a local clone). README FAQ updated with the distribution caveat.
+- **Caveman installer swapped to a temporary fork pin** — `catalog.yaml` Caveman `installer.cmd` now `npx -y "github:mhd-ghaith-abtah/caveman#flow-pin-v0.1"` (was upstream curl-pipe-bash). The fork carries the project-scope gating patches from JuliusBrussee/caveman#407 applied on top of upstream `main`. Reason: upstream Caveman has a ~134-PR backlog with ~5 merges/month, so waiting for #407 to land would block Flow's team profile for months. The fork is documented as temporary in `catalog.yaml` (new fields: `upstream_repo`, `upstream_pr`, `fork_status`) with an explicit swap-back plan. Doctor probe shows the fork status so users know when upstream merges. README updates the FAQ + "Upstream contributions" section to reflect the conditional compose-vs-fork strategy.
+
+### Added
+- **Upstream ECC PR merged** — [affaan-m/ECC#2006](https://github.com/affaan-m/ECC/pull/2006) adds a `claude-project` install target (project-scope ECC), symmetric with the existing user-scope `claude` target. Closes the install-target matrix for Claude Code (now 7 project-scope + 4 home-scope adapters) and removes the need for Flow's `HOME=$PROJECT/.flow-vendor` shim. Closes E7-001. Unblocks E7-002 → E7-005 (catalog scope flag, init wiring, doctor probe, docs).
+- **Flow published to npm** as [`@mhd-ghaith-abtah/flow@0.7.2-beta.0`](https://www.npmjs.com/package/@mhd-ghaith-abtah/flow). End-to-end smoke clean: local install, global install (`flow` on PATH), `npx -y @mhd-ghaith-abtah/flow@beta`, all four profiles resolve, `flow doctor` probes catalog + state + adapters + upstreams. 78 transitive deps, 81 kB tarball. Closes E1-002 (the last open BLOCKING story from the v0.6.1 review handoff).
+
+### Changed
+- README gained an FAQ entry on per-project ECC installs (via the merged `claude-project` target) and a new "Upstream contributions" subsection under Credits listing ECC #2006 (merged) and Caveman #407 (in review).
+- README Install section refreshed for the npm publish — now shows four paths (`/flow-init` slash command, `npm install -g @mhd-ghaith-abtah/flow@beta`, `npx -y @mhd-ghaith-abtah/flow@beta`, clone for development). Status block updated from "not yet published" to "published as beta, soaking before latest promotion".
+
+### Added
+- `ROADMAP.md` — multi-epic arc through v0.7.x (stabilize) → v0.8 (npx-first + ECC project-scope) → v0.9 (multi-agent) → v1.0 (stable). Explicit out-of-scope guardrails (no multi-repo orchestration, no SaaS, no LLM provider abstraction, etc.). Decision log appended as design calls land. Linked from README FAQ.
+- Sprint backlog gained 24 forward-looking stories under new epics E6 (npx-first install), E7 (ECC project-scope), E8 (multi-agent, demand-gated), E9 (beta soak). E7-001 (ECC upstream PR) is marked `ready` — next actionable item.
+
 ## [0.7.2-beta.0] — 2026-05-19
 
 ### Changed

package/README.md

@@ -20,19 +20,31 @@ Existing per-story workflows are token-heavy. BMad's create-story re-reads epics
 
 ## Install
 
-> **Status (v0.7.0):** the `npx` install path is not yet published to npm. The headless CLI (`node bin/flow.js plan / install / doctor / add / remove / uninstall`) is fully working from a clone. Slash commands are the recommended primary path. `npx @mhd-ghaith-abtah/flow init` lands once the package is published; tracked as E1-002 in `docs/flow/sprint.yaml`.
+> **Status (v0.7.2-beta.0, published 2026-05-19):** Flow is live on npm as a **beta channel**. Stable `latest` will be promoted from beta after a soak period. Expect minor breaking changes between beta releases until then.
 
 ```bash
-# Inside Claude Code (recommended)
-/flow-init
+# 1. Install the Node CLI + bootstrap the Claude Code surface
+npm install -g @mhd-ghaith-abtah/flow@beta
+flow install-skills                             # one-time; symlinks 4 skills into ~/.claude/skills/
 
-# Headless (works today against a clone — npm publish pending)
+# 2. Then EITHER (interactive):
+/flow-init                                      # inside Claude Code
+
+# OR (headless, no Claude Code needed):
+flow init --profile standard --yes              # chains detect → upstreams → MCPs → scaffold
+
+# Useful at any point:
+flow plan --profile standard                    # preview without executing
+flow doctor                                     # health check
+
+# Dev clone (contributors):
 git clone https://github.com/mhd-ghaith-abtah/flow.git
-cd flow && npm install && tools/dev-link.sh
-flow plan --profile standard
+cd flow && npm install && tools/dev-link.sh     # dev-mode equivalent of install-skills + PATH link
 ```
 
-The slash-command path runs the same interactive installer. It detects your project shape, asks ~8 questions, then:
+The `flow install-skills` step is what makes `/flow-init` resolve in Claude Code — npm puts the package in your global node_modules, but Claude Code only scans `~/.claude/skills/`. After install-skills, both paths (interactive slash or headless CLI) reach the same orchestrator and write the same files. Override individual knobs via `--ecc-scope`, `--bmad-subset`, `--ecc-subset`. Full guide: [docs/usage.md](docs/usage.md).
+
+The installer detects your project shape, then:
 - Installs Flow's four skills (`flow-init`, `flow-sprint`, `flow-story`, `flow-doctor`)
 - Optionally invokes `npx bmad-method install` with a curated module list
 - Optionally invokes ECC's `install.sh` with a curated profile
@@ -44,6 +56,8 @@ The slash-command path runs the same interactive installer. It detects your proj
 
 ## Quickstart
 
+> **Want every option in one place?** See the long-form [Usage Guide](docs/usage.md) — installation paths, daily workflow, sprint commands, profiles, ECC scope, maintenance, uninstall, full CLI reference, common scenarios (recipe book), and troubleshooting. The block below is the 30-second version.
+
 ```bash
 $ /flow-init                                              # one time per project
 $ /flow-sprint add "First story" --epic E1 --tags ui      # add a story
@@ -66,14 +80,14 @@ All three are mode flags on the same skills, not different code paths.
 
 Pick one per category in `flow.config.yaml`:
 
-| Category | v0.1 adapters |
+| Category | Available |
 |---|---|
 | Issue tracker | `linear`, `github-issues`, `none` |
 | PR platform | `github`, `none` |
 | E2E | `playwright-mcp`, `none` |
 | Verify | `make`, `pnpm`, `custom` |
 
-More coming in v0.2: `jira`, `notion`, `plain`, `gitlab`, `bitbucket`, `cypress`, `slack`, `discord`.
+Additional adapters (Jira, Notion, Plain, GitLab, Bitbucket, Cypress, Slack, Discord, etc.) land when a real user surfaces a concrete use case — see Flow's [validate-demand-before-building principle](ROADMAP.md#guiding-principles). The adapter contract in `adapters/<family>/<name>/_interface.md` is small (one YAML manifest + a handful of skill workflows) so PRs are welcome.
 
 ## Architecture
 
@@ -124,7 +138,10 @@ ECC owns the per-story primitives (`/plan`, `/prp-implement`, `/code-review`, `/
 Yes for now — Flow expects it. Caveman compresses Claude's responses ~75% in `full` mode, which is what makes mini-profile's 20k-tokens-per-story claim realistic. `/flow-init` installs it automatically with the right registration (see `tools/fix-caveman-shrink.sh` if the MCP proxy gets mis-registered).
 
 **Caveman is now active in every Claude Code session, even my non-Flow projects. Can I scope it?**
-Caveman's `SessionStart` hook activates globally by default. Native project-scope gating is shipping upstream via [JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407) (filed and reviewed by Flow's maintainer; awaiting upstream merge). The PR adds `.caveman-enable` / `.caveman-disable` marker files, a `CAVEMAN_PROJECT_SCOPE` env var, and config-driven `projectScope.allow[]` / `deny[]` lists. To opt into allowlist mode today, set `~/.config/caveman/config.json` to `{"defaultMode": "off"}` — Caveman stays silent everywhere except projects with `.caveman-enable` in their root. Flow's `/flow-init` drops that marker automatically, so Flow-managed projects keep working. `/flow-doctor` surfaces a probe for "Caveman active outside a Flow project" until the PR merges.
+Yes, in Flow-managed projects this works out of the box. Flow installs Caveman from a **temporary fork** ([mhd-ghaith-abtah/caveman @ `flow-pin-v0.1`](https://github.com/mhd-ghaith-abtah/caveman/tree/flow-pin-v0.1)) that carries the project-scope gating patches from [JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407) on top of upstream `main`. The fork exists because upstream Caveman has a ~134-PR review backlog with ~5 merges/month — waiting for #407 to merge would block Flow for months. **When #407 merges upstream, Flow swaps the catalog back to `JuliusBrussee/caveman` and deletes the fork.** The `.caveman-enable` marker Flow drops in your project root works identically against upstream and the fork, so the swap is a no-op at the project level. To opt into project-scope gating in non-Flow projects today, you can either install Caveman from the same fork tag or set `~/.config/caveman/config.json` to `{"defaultMode": "off"}` and rely on the markers globally. `/flow-doctor` surfaces a probe for "Caveman fork in use — track upstream PR #407" so you know when to expect the swap.
+
+**Can I install ECC per-project instead of into `~/.claude/`?**
+Yes — the `claude-project` install target merged into ECC's `main` via [affaan-m/ECC#2006](https://github.com/affaan-m/ECC/pull/2006) on 2026-05-19 (filed and merged same-day by Flow's maintainer). Pass `--target claude-project` and ECC lands under `<projectRoot>/.claude/rules/ecc` + `<projectRoot>/.claude/skills/ecc` instead of `~/.claude/`. Symmetric with `--target claude` (home-scope) — same namespacing, same locale handling, no breaking change. **Profile defaults (shipped 2026-05-20):** `team` defaults to project-scope; `mini`/`standard`/`minimal` default to user-scope. Override via `flow plan --profile <name> --ecc-scope <user|project>` or `flow install --profile <name> --ecc-scope <user|project>` — typos like `--ecc-scope=projet` fail loud instead of silently falling through to the profile default. **Distribution caveat:** the current ECC npm `latest` is `ecc-universal@1.10.0` (2026-04-15), which predates the merge by ~36 days, so `npx ecc-universal` will NOT have the target yet. Flow's catalog pins to the post-merge commit via `npx -y -p "github:affaan-m/ECC#98bd5174" ecc-install` until affaan-m cuts the next ECC release (`2.0.0`) — at which point we swap back to the npm package. Useful for monorepos, polyglot workspaces, or teams that want ECC scoped per-repo without contaminating the developer's global Claude Code config.
 
 **Which profile should I pick?**
 - `mini` — solo, single repo, light review, no formal PR process → ~20k/story
@@ -134,7 +151,7 @@ Caveman's `SessionStart` hook activates globally by default. Native project-scop
 You can swap profiles with `/flow-init --update --profile <name>` — it's just a different bundle, not a different codepath.
 
 **What if I don't use GitHub?**
-Pick `adapter:pr-none` during `/flow-init` and configure `verify` + `e2e` to whatever you do use. GitLab + Bitbucket adapters are planned for v0.2.
+Pick `adapter:pr-none` during `/flow-init` and configure `verify` + `e2e` to whatever you do use. GitLab and Bitbucket PR adapters are unscheduled — the adapter contract is small enough to ship one in a weekend, and PRs are welcome (see `adapters/pr/<name>/_interface.md`).
 
 **How do I upgrade Flow?**
 `/flow-init --update` is idempotent. It re-detects project shape, diffs against `install-state.json`, and applies only the deltas. Upstream installers (BMad / ECC / Caveman) are re-invoked only when their pinned subset changes.
@@ -148,6 +165,9 @@ Yes — it's intentionally team-shared (adapter choices, review policy, verify c
 **Where do I report bugs?**
 [github.com/mhd-ghaith-abtah/flow/issues](https://github.com/mhd-ghaith-abtah/flow/issues). Run `/flow-doctor` first — it surfaces known-bug patterns automatically.
 
+**What's the roadmap?**
+See [ROADMAP.md](ROADMAP.md). v0.7.x is stabilization, v0.8 is npx-first install + ECC project-scope, v0.9 is multi-agent (Codex / Cline / Cursor / 30+ others). Explicit out-of-scope list there too.
+
 ## Credits
 
 Flow stands on:
@@ -157,6 +177,17 @@ Flow stands on:
 - **[spec-kit](https://github.com/github/spec-kit)** by GitHub — spec-driven development pattern
 - **[AI Dev Tasks](https://github.com/snarktank/ai-dev-tasks)** by snarktank — lean PRD + tasks pattern
 
+### Upstream strategy
+
+Flow's preference is to send features upstream rather than fork. When upstream is responsive, we contribute. When upstream is bandwidth-constrained, we maintain a **transparent temporary fork with an explicit deprecation plan**.
+
+Active and historical contributions:
+
+- **[affaan-m/ECC#2006](https://github.com/affaan-m/ECC/pull/2006)** — `claude-project` install target (project-scope ECC). **Merged 2026-05-19.** Closes the install-target matrix for Claude Code and removes the need for `HOME=$PROJECT/...` shims. Same-day review and merge by maintainer.
+- **[JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407)** — project-scope gating via marker files, env var, and allow/deny lists. *Filed 2026-05-19. Sitting in a ~134-PR backlog at ~5 merges/month, so Flow ships a **temporary fork** ([mhd-ghaith-abtah/caveman @ `flow-pin-v0.1`](https://github.com/mhd-ghaith-abtah/caveman/tree/flow-pin-v0.1)) with the patches applied. Catalog will swap back to upstream the day #407 merges.*
+
+This is the rule: **compose over reinvention, contribute when accepted, fork transparently with a swap-back plan when contribution is blocked.** Forks are documented in `catalog.yaml` with `upstream_repo` + `upstream_pr` + `fork_status` fields so the deprecation path is auditable.
+
 ## License
 
 MIT

package/adapters/e2e/playwright-mcp.md

@@ -76,7 +76,7 @@ Uses the Playwright MCP server. Runs an interactive browser session, executes jo
 
 ## screenshot_diff(baseline_path, current_path)
 
-Optional — v0.1 returns `{ diff_pct: null, note: "not implemented" }`. v0.2 will use `pixelmatch` or `odiff`.
+Optional — currently returns `{ diff_pct: null, note: "not implemented" }`. A real pixel-diff (likely `pixelmatch` or `odiff`) is unscheduled; PRs welcome. Until then, callers should treat a `null` diff_pct as "skip the diff gate".
 
 ## Failure handling
 

package/adapters/issue-tracker/_interface.md

@@ -36,7 +36,7 @@ Called before `transition_to_done`. Confirm the linked PR is actually merged so
 
 ## Config keys
 
-Adapters declare the keys they need in `flow.config.yaml > integrations.issue_tracker.*`. The Flow installer prompts for these at first install or when the adapter is swapped in via `flow adapter swap`.
+Adapters declare the keys they need in `flow.config.yaml > integrations.issue_tracker.*`. The Flow installer prompts for these at first install or when the adapter is swapped via `flow add adapter:issue-tracker-<id>` (or a hand-edit of `flow.config.yaml`).
 
 ## Failure handling
 

package/adapters/verify/make.md

@@ -14,7 +14,7 @@ Runs `make verify` (or another target). Standard for repos that wrap their build
 
 ## precheck
 
-1. `test -f Makefile` → if false, halt: "No Makefile at repo root. Either create one with a `{{target}}:` target or switch to `flow adapter swap verify pnpm` / `custom`."
+1. `test -f Makefile` → if false, halt: "No Makefile at repo root. Either create one with a `{{target}}:` target or switch via `flow add adapter:verify-pnpm` / `flow add adapter:verify-custom`."
 2. `grep -q '^{{target}}:' Makefile` → if false, halt: "Makefile is present but has no `{{target}}:` target."
 
 ## run

package/bin/flow.js

@@ -24,6 +24,7 @@ ${chalk.bold('Usage:')}
 ${chalk.bold('Commands:')}
   init                          Interactive first-time setup (same as /flow-init in Claude Code)
   install                       Non-interactive install with flags
+  install-skills                Symlink Flow skills into ~/.claude/skills/ (bootstrap)
   plan                          Dry-run: show the resolved install plan
   status                        What's installed where
   doctor [--mcp <id>]           Health check
@@ -34,13 +35,14 @@ ${chalk.bold('Commands:')}
   list-components [--family X]  List available components
   list-mcps                     List MCP servers Flow tracks
   mcp <add|remove|reauth> ...   Manage MCP servers
-  adapter <swap|list> ...       Manage active adapters
+  sprint <subcommand> ...       Sprint state ops: add | next | status | done | deferred | import-bmad
   help [command]                Show help
 
 ${chalk.bold('Common flags:')}
   --profile <name>              mini | standard | team | minimal | full
   --bmad-subset <name>          none | planning-only | planning-plus-research | creative-thinking | test-architecture | full | passthrough
   --ecc-subset <name>           none | flow-essentials | flow-essentials-plus-tdd | security-heavy | research-heavy | use-ecc-default | passthrough
+  --ecc-scope <user|project>    Override the profile's ECC install scope (user = ~/.claude/, project = ./.claude/)
   --with <component>            Add a component on top of the profile
   --without <component>         Remove a component from the profile
   --scope home|project|both     Install scope (default: both)
@@ -67,8 +69,8 @@ Version ${PKG.version} · ${chalk.dim(PKG.homepage)}
 `;
 
 const COMMANDS = [
-  'init', 'install', 'plan', 'status', 'doctor', 'add', 'remove', 'uninstall',
-  'list-profiles', 'list-components', 'list-mcps', 'mcp', 'adapter', 'help', 'version', '--version'
+  'init', 'install', 'install-skills', 'plan', 'status', 'doctor', 'add', 'remove', 'uninstall',
+  'list-profiles', 'list-components', 'list-mcps', 'mcp', 'sprint', 'help', 'version', '--version'
 ];
 
 async function main() {
@@ -94,8 +96,8 @@ async function main() {
   // Parse remaining args. Note: no global `scope` default — each command sets
   // its own (install: both; uninstall: project, for safety).
   const args = yargsParser(argv.slice(1), {
-    string: ['profile', 'bmad-subset', 'ecc-subset', 'with', 'without', 'scope', 'catalog-source', 'mcp', 'family', 'repair-upstream'],
-    boolean: ['dry-run', 'json', 'yes', 'execute', 'remove-stories', 'remove-backups', 'archive-unused', 'migrate-bmad', 'verbose'],
+    string: ['profile', 'bmad-subset', 'ecc-subset', 'ecc-scope', 'with', 'without', 'scope', 'catalog-source', 'mcp', 'family', 'repair-upstream', 'id', 'title', 'epic', 'tags', 'why', 'issue', 'note', 'project', 'status'],
+    boolean: ['dry-run', 'json', 'yes', 'execute', 'remove-stories', 'remove-backups', 'remove-project-ecc', 'archive-unused', 'migrate-bmad', 'verbose', 'force', 'continue-on-error', 'repair', 'update'],
     array: ['with', 'without'],
     alias: { y: 'yes' }
   });

package/catalog.yaml

@@ -225,17 +225,45 @@ upstreams:
 
   ecc:
     name: "Everything Claude Code"
-    repo: "https://github.com/affaan-m/everything-claude-code"
+    # Pinned to a post-merge commit on ECC main so users get the
+    # `claude-project` install target (merged via affaan-m/ECC#2006 on
+    # 2026-05-19). Current ECC npm `latest` is 1.10.0 (2026-04-15) and
+    # predates the merge by ~36 days, so npm install would NOT have the
+    # target until affaan-m cuts the next release (2.0.0).
+    # SWAP PLAN: when ecc-universal@2.x lands on npm, switch
+    # `cmd_fallback` to `npx ecc-universal install` and pin a version.
+    # install_scope_default — where ECC lands when a profile doesn't override:
+    #   - "user"    → ~/.claude/rules/ecc + ~/.claude/skills/ecc (legacy default)
+    #   - "project" → <projectRoot>/.claude/rules/ecc + .../skills/ecc
+    # Per-profile override lives at profiles.<name>.ecc_install_scope.
+    # E7-003 will wire this into base_args so --target swaps to
+    # claude-project when scope == "project". Today's E7-002 only plumbs
+    # the data through profile resolution.
+    install_scope_default: "user"
+    repo: "https://github.com/affaan-m/ECC"
+    upstream_npm_package: "ecc-universal"
+    upstream_npm_latest: "1.10.0"
+    upstream_npm_status: "predates claude-project merge; github pin used until 2.x publishes"
+    pinned_commit: "98bd5174"
     detect:
       check_cmd: "test -d ~/.claude/rules/common"
       version_path: "~/.claude/rules/VERSION"
       installer_path_candidates:
+        # Local dev paths — if a contributor has ECC cloned locally we use
+        # it. Otherwise fall through to cmd_fallback (github npx pin).
         - "~/dev-tools/everything-claude-code/install.sh"
-        - "/usr/local/lib/node_modules/@everything-claude-code/ecc/install.sh"
+        - "~/development/personal/ecc-fork/install.sh"
     installer:
       cmd: "{installer_path}"
-      cmd_fallback: "npx @everything-claude-code/ecc install"
-      base_args: "--target claude"
+      cmd_fallback: "npx -y -p \"github:affaan-m/ECC#98bd5174\" ecc-install"
+      # base_args is scope-agnostic now. Callers must prepend the
+      # `--target <id>` flag chosen via `target_by_scope[ecc_install_scope]`.
+      # Kept empty so a future shared arg (e.g. --yes) has somewhere to live.
+      base_args: ""
+      target_arg: "--target"
+      target_by_scope:
+        user: claude            # ~/.claude/{rules,skills}/ecc
+        project: claude-project # <projectRoot>/.claude/{rules,skills}/ecc
       profile_arg: "--profile"
       with_arg: "--with"
       without_arg: "--without"
@@ -270,8 +298,21 @@ upstreams:
 
   caveman:
     name: "Caveman"
-    repo: "https://github.com/JuliusBrussee/caveman"
-    description: "Output-compression layer for Claude Code (~46% input, ~75% output token savings). Flow expects Caveman to be active so its outputs stay tight."
+    # TEMPORARY FORK NOTICE
+    # ---------------------
+    # Flow currently installs Caveman from a patched fork pinned at
+    # github:mhd-ghaith-abtah/caveman#flow-pin-v0.1. The fork carries the
+    # project-scope gating patches from JuliusBrussee/caveman#407 (filed
+    # 2026-05-19, sitting in a ~134-PR upstream backlog with ~5 merges/month).
+    # The upstream repo is the source of truth; the fork tracks `main` and
+    # applies only the gating delta on top.
+    # SWAP PLAN: when #407 merges upstream, flip `repo` + `installer.cmd`
+    # back to JuliusBrussee/caveman and delete this notice (E2-006 ↻).
+    repo: "https://github.com/mhd-ghaith-abtah/caveman"
+    upstream_repo: "https://github.com/JuliusBrussee/caveman"
+    upstream_pr: "https://github.com/JuliusBrussee/caveman/pull/407"
+    fork_status: "temporary — pending upstream merge of #407"
+    description: "Output-compression layer for Claude Code (~46% input, ~75% output token savings). Flow expects Caveman to be active so its outputs stay tight. Installed from a Flow-maintained fork until project-scope gating lands upstream."
     detect:
       # Current Caveman installer routes via Claude Code's plugin marketplace —
       # files land under ~/.claude/plugins/cache/caveman/, NOT the legacy
@@ -280,12 +321,16 @@ upstreams:
       check_cmd: "find $HOME/.claude/plugins -path '*caveman*SKILL.md' -print -quit 2>/dev/null | grep -q . || test -f $HOME/.claude/skills/caveman/SKILL.md || test -f $HOME/.claude/hooks/caveman-config.js"
       hooks_cmd: "ls $HOME/.claude/hooks/caveman-* 2>/dev/null"
     installer:
-      cmd: "curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash"
+      # Pinned to a stable tag on the Flow-maintained fork. The tag carries the
+      # #407 gating patches applied on top of upstream main. To inspect before
+      # running, set $FLOW_INSPECT_INSTALL_SCRIPTS=1 and Flow will download +
+      # diff against upstream first.
+      cmd: "npx -y \"github:mhd-ghaith-abtah/caveman#flow-pin-v0.1\""
       # Mirror of detect.check_cmd — succeeds for either the plugin-marketplace
       # layout (current) or the legacy ~/.claude/skills/caveman/ layout (older
       # installer releases). Verifies "the install landed somewhere we can find".
       verify_after_cmd: "find $HOME/.claude/plugins -path '*caveman*SKILL.md' -print -quit 2>/dev/null | grep -q . || test -f $HOME/.claude/skills/caveman/SKILL.md || test -f $HOME/.claude/hooks/caveman-config.js"
-      security_note: "Caveman ships only via curl-pipe-bash. Flow will surface this and ask for confirmation unless --yes is passed. To inspect the script before running, set $FLOW_INSPECT_INSTALL_SCRIPTS=1 — Flow will download to /tmp first, pause for review, then execute."
+      security_note: "Caveman installs via npx from a Flow-maintained fork (pinned tag flow-pin-v0.1). Fork = upstream main + JuliusBrussee/caveman#407 patches. Flow will surface this and ask for confirmation unless --yes is passed. To inspect the fork's source before running: gh repo view mhd-ghaith-abtah/caveman --branch flow-pin-v0.1 OR set $FLOW_INSPECT_INSTALL_SCRIPTS=1."
     available_modes: [lite, full, ultra, wenyan]
     curated_subsets:
       none:
@@ -356,6 +401,10 @@ profiles:
     bmad_subset: full
     ecc_subset: flow-essentials-plus-tdd
     caveman_subset: full
+    # team-profile default: ECC lands per-project so each Flow-managed repo
+    # gets its own ECC selection without contaminating ~/.claude/. Becomes
+    # active once E7-003 wires the scope flag into the install command.
+    ecc_install_scope: project
     # Note: review.use_separate_model is set to true in the generated
     # flow.config.yaml for this profile (spawns one reviewer with a different
     # model for fresh perspective). The previous `features` block here

package/docs/adapters.md

@@ -1,8 +1,8 @@
 # Adapters
 
-Flow's per-category adapter system lets you swap integrations without changing any skill code. There are four adapter families today; more land in v0.2.
+Flow's per-category adapter system lets you swap integrations without changing any skill code. There are four adapter families today; additional adapters and families land when there's a concrete use case (see Flow's [validate-demand-before-building principle](../ROADMAP.md#guiding-principles)).
 
-## Families + v0.1 options
+## Families + available picks
 
 | Family | Picks | What it does |
 |---|---|---|
@@ -11,7 +11,7 @@ Flow's per-category adapter system lets you swap integrations without changing a
 | `e2e` | `playwright-mcp`, `none` | End-to-end test driver — run journeys, capture artifacts |
 | `verify` | `make`, `pnpm`, `custom` | Verify command — typecheck + lint + unit tests in one |
 
-Coming in v0.2: `jira`, `notion`, `plain` (issue-tracker); `gitlab`, `bitbucket` (pr); `cypress` (e2e); `slack`, `discord` (notification — new family).
+**Likely-but-unscheduled** (PRs welcome — the adapter contract is small): Jira, Notion, Plain (issue-tracker); GitLab, Bitbucket (pr); Cypress (e2e); Slack, Discord (notification — would be a new family). None of these are on the roadmap today; the adapter contract in `adapters/<family>/<name>/_interface.md` is small enough that a contributor can ship one in a weekend.
 
 ## Picking adapters
 
@@ -54,8 +54,11 @@ Each adapter is a markdown file with sections for each operation in the family's
 
 ## Swapping after install
 
+Two supported paths:
+
 ```
-flow adapter swap pr github-issues   # not yet implemented in v0.7
+flow add adapter:pr-github-issues
+flow remove adapter:pr-github
 ```
 
 Or hand-edit `flow.config.yaml`:

package/docs/profiles.md

@@ -4,12 +4,12 @@ Profiles are named bundles that pick the right adapters + upstream subsets + MCP
 
 ## At a glance
 
-| Profile | Best for | Tokens/story | Review | E2E | PR | Issue tracker |
-|---|---|---:|---|---|---|---|
-| `mini` | Solo, one repo, light review | ~20k | `code-review` only | none | GitHub | GitHub Issues |
-| `standard` | Solo/small team, formal review | ~40k | `code-review` + language reviewer + security on risk tags | Playwright MCP | GitHub | GitHub Issues |
-| `team` | Multi-repo, multi-LLM review | ~60k | + adversarial + edge-case + separate-model reviewer | Playwright MCP | GitHub (sibling PRs) | Linear |
-| `minimal` | Bare Flow, no upstreams | <10k | none | none | none | none |
+| Profile | Best for | Tokens/story | Review | E2E | PR | Issue tracker | ECC scope |
+|---|---|---:|---|---|---|---|---|
+| `mini` | Solo, one repo, light review | ~20k | `code-review` only | none | GitHub | GitHub Issues | user |
+| `standard` | Solo/small team, formal review | ~40k | `code-review` + language reviewer + security on risk tags | Playwright MCP | GitHub | GitHub Issues | user |
+| `team` | Multi-repo, multi-LLM review | ~60k | + adversarial + edge-case + separate-model reviewer | Playwright MCP | GitHub (sibling PRs) | Linear | **project** |
+| `minimal` | Bare Flow, no upstreams | <10k | none | none | none | none | user |
 
 ## What each profile changes
 
@@ -19,6 +19,7 @@ Profiles are named bundles that pick the right adapters + upstream subsets + MCP
 - **MCPs:** none
 - **BMad subset:** `none`
 - **ECC subset:** `none`
+- **ECC install scope:** `user` (inherits the catalog default — no scope-relevant ECC content is installed at `none` anyway)
 - **Caveman:** `full`
 
 Just `sprint.yaml` + story files. No upstream integration. Useful when you want Flow's state model without any of the per-story machinery.
@@ -30,6 +31,7 @@ Extends `minimal`. Adds:
 - **Adapters:** `issue-tracker-github-issues`, `pr-github`, `verify-make`
 - **MCPs:** `context7`
 - **ECC subset:** `flow-essentials` (just `/plan`, `/prp-implement`, `/code-review`, `/update-docs`)
+- **ECC install scope:** `user` (lands under `~/.claude/{rules,skills}/ecc` — shared across all your projects)
 
 What you get: full per-story orchestration through `/flow-story` with the lightest possible review. No E2E, no language-specific reviewers, no adversarial reviewers.
 
@@ -41,6 +43,7 @@ Extends `mini`. Adds:
 - **MCPs:** + `playwright`
 - **BMad subset:** `planning-only` (PRD, architecture, epic generation; no per-story BMad re-reads)
 - **ECC subset:** `flow-essentials-plus-tdd` (adds `/tdd` and TDD harness)
+- **ECC install scope:** `user` (inherited from `mini` — same `~/.claude/{rules,skills}/ecc` mount)
 
 What you get: full orchestration + E2E coverage for tagged stories + BMad planning artifacts on demand.
 
@@ -51,12 +54,38 @@ Extends `standard`. Adds:
 - **Adapters:** overrides `issue-tracker-github-issues` → `issue-tracker-linear`
 - **MCPs:** + `linear`
 - **BMad subset:** `full`
+- **ECC install scope:** `project` (lands under `<projectRoot>/.claude/{rules,skills}/ecc` so each Flow-managed repo keeps its own ECC selection; nothing bleeds into the developer's global `~/.claude/`)
 - **Review:** `use_separate_model: true` — spawns one reviewer with a different model (e.g., Sonnet alongside Opus) for cross-model perspective on tagged-risky stories
 
 What you get: full orchestration + Linear-driven sprint sync + cross-model code review on high-risk stories.
 
 > **What you don't get (despite earlier docs promising it):** multi-repo coordinated sibling PRs and per-adapter-call audit logs. Those were aspirational features in the team-profile description through v0.7.0 with zero implementation behind them. Stripped on 2026-05-19 (sprint story E5-007). Read-only multi-repo awareness (story-id touches N repos → aggregate PR status) is tracked as a deferred backlog item; surface a real use case and we'll design it properly.
 
+## ECC install scope
+
+Where ECC's rules + skills land on disk. Two values:
+
+| Scope | Install root | Use case |
+|---|---|---|
+| `user` | `~/.claude/rules/ecc` + `~/.claude/skills/ecc` | Solo dev or single primary project — ECC is shared across every Claude Code session on the machine |
+| `project` | `<projectRoot>/.claude/rules/ecc` + `<projectRoot>/.claude/skills/ecc` | Multi-project, polyglot, or team setups — each Flow-managed repo keeps its own ECC selection without bleeding into `~/.claude/` |
+
+Resolved scope per layer (later wins):
+
+1. **Catalog default** — `upstreams.ecc.install_scope_default: user` in `catalog.yaml`. Fallback when nothing else applies.
+2. **Profile** — each profile's `ecc_install_scope` field. `team` is the only stock profile that overrides to `project`; the rest inherit `user`.
+3. **CLI flag** — `--ecc-scope <user|project>` on `flow plan` and `flow install`. Highest priority. Typos like `--ecc-scope=projet` fail loud.
+
+```
+flow plan --profile team                  # team default → project
+flow plan --profile team --ecc-scope user # explicit override → user
+flow plan --profile mini --ecc-scope project # explicit override → project
+```
+
+Under the hood, the scope picks the ECC installer's `--target` flag: `user` → `--target claude`, `project` → `--target claude-project`. The `claude-project` target merged into ECC via [affaan-m/ECC#2006](https://github.com/affaan-m/ECC/pull/2006) on 2026-05-19; Flow's catalog pins to that commit (`npx -y -p "github:affaan-m/ECC#98bd5174" ecc-install`) until ECC publishes `ecc-universal@2.x` to npm (current latest is `1.10.0`, which predates the merge).
+
+`/flow-doctor --repair-upstream ecc` reads the recorded scope from `install-state.json` and emits the right rules-dir + `--target` arg in its repair instructions — no manual translation needed.
+
 ## Swapping profiles
 
 ```