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

package/CHANGELOG.md

@@ -6,6 +6,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0-beta.3] — 2026-05-23
+
+### Fixed
+- **`flow doctor` now finds `flow.config.yaml` at the canonical `.claude/flow.config.yaml` path** — surfaced by a real install into kaizenpro. Doctor was checking only the legacy root-level `flow.config.yaml` path while `scaffold()` writes to `.claude/flow.config.yaml`. Result: every fresh install reported `Config ℹ not present (run /flow-init)` even though the file was sitting right there, AND the entire Adapters section was suppressed (it depends on a parsed config). Fix: `probeConfig` checks `.claude/flow.config.yaml` first then falls back to the root path for backward compat. 3 new tests pin the behavior (canonical-found / legacy-fallback / canonical-wins-when-both-exist).
+- **`flow uninstall` now removes `.claude/flow.config.yaml`** — same root cause as the doctor bug. `PROJECT_PATHS` listed only the legacy root-level `flow.config.yaml`, leaving the actually-written canonical file in place after uninstall. Fix: PROJECT_PATHS extended with `.claude/flow.config.yaml` + `.claude/flow.config.local.yaml`; legacy root paths kept for backward compat with pre-`.claude/`-convention installs.
+
+### Changed
+- **Docs now recommend `npm install -g` + `flow install-skills --scope project` as the canonical slash-command setup** — surfaced by dogfooding the `npx`-only path into kaizenpro. The pure-npx flow produces symlinks pointing at `~/.npm/_npx/<hash>/node_modules/...` which npm rotates over time; when the cache entry is purged, slash commands silently stop resolving with no error. Single `npm install -g` provides a stable symlink target at `/opt/homebrew/lib/node_modules/...` that survives until `npm uninstall`. README install section + `docs/quickstart.md` + `docs/usage.md §1` all rewritten to lead with the project-scope pattern and demote pure-npx to a "works but with caveats" section (§1d). Rationale: project-scope keeps slash commands out of unrelated Claude Code sessions; stable symlinks mean no broken-pointer debugging when the npx cache rotates. `npx -y ... install-skills --scope project` still works for one-off use, just less durable.
+
+## [0.8.0-beta.2] — 2026-05-23
+
+### Fixed
+- **Headless `flow init --yes` now drops `.caveman-enable` marker** — closes a parity gap between the slash workflow and the headless orchestrator. The slash `/flow-init` (skills/flow-init/workflow.md step 8b) has always dropped a zero-byte `.caveman-enable` in the project root when Caveman is requested, so allowlist-mode users (`~/.config/caveman/config.json` = `{"defaultMode": "off"}`) get Caveman activated there automatically. The headless orchestrator skipped this step despite README + usage.md both claiming the installer "drops a `.caveman-enable` marker". Surfaced by a user dogfooding the v0.8.0-beta.1 npm tarball into their actual project. Fix: `lib/init/orchestrate.js` now writes the marker after the Caveman dispatcher runs (skipped under `dryRun: true`, idempotent if the file already exists, non-fatal on write failure). 3 new tests cover the marker-written / no-marker-when-subset-none / no-marker-in-dry-run cases. docs/usage.md §16d updated — the manual `touch .caveman-enable` workaround is no longer needed on either install path. 191/191 tests pass.
+
+### Changed
+- **Docs audit + greenfield/Caveman sections** — full sweep of every doc file for staleness post-v0.8.0-beta.1. `docs/quickstart.md` rewritten: bootstrap order now includes the `flow install-skills` step (was missing — same gap users hit before the install-skills command shipped), Q count corrected to 9 (was 8 pre-Q7c), ECC install snippet updated from the dead `./install.sh` path to the github-pin form, `/flow-doctor --fix` (which doesn't exist) replaced with `--repair-upstream`, retro output path corrected from `<date>.md` to `<epic-id>-retro.md`. `docs/migrate-from-bmad.md` stops naming specific BMad slash commands (`/bmad-create-prd`, `/bmad-create-story`) since those changed between BMad versions; now points at the BMad 6+ `/bmad:bmm:<step>` namespace as the current shape. `docs/profiles.md` clarifies that tokens-per-story figures assume Caveman = `full`. README's "When to use which command" table swapped specific BMad slash names for a version-agnostic pointer; the install diagram shows the actual github pin + Caveman fork commands. `docs/usage.md` gains two new sections: §2c "Starting from zero (greenfield + BMad planning)" — the PRD → architecture → stories → import-bmad → /flow-story arc for users with only an idea; and §17 "How Caveman enhances Flow" — the token-math justification, mode reference, fork-pin story, opt-out paths.
+
 ## [0.8.0-beta.1] — 2026-05-23
 
 ### Added

package/README.md

@@ -20,18 +20,21 @@ Existing per-story workflows are token-heavy. BMad's create-story re-reads epics
 
 ## Install
 
-> **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.
+> **Status (v0.8.0-beta.2, published 2026-05-23):** Flow is live on npm via the `@beta` dist-tag. `@latest` still points at the older `0.7.2-beta.0` and gets promoted from `@beta` after a soak window with no critical issues. Pin to `@beta` for the new headless install + project-scope ECC + bug fixes.
 
 ```bash
-# 1. Install the Node CLI + bootstrap the Claude Code surface
+# 1. Install the Node CLI (once per machine)
 npm install -g @mhd-ghaith-abtah/flow@beta
-flow install-skills                             # one-time; symlinks 4 skills into ~/.claude/skills/
+flow --version                                  # → 0.8.0-beta.2
 
-# 2. Then EITHER (interactive):
-/flow-init                                      # inside Claude Code
+# 2. Per project — symlink the 4 skills into THIS project's .claude/skills/
+cd /path/to/project
+flow install-skills --scope project --force     # ← recommended scope for slash commands
 
-# OR (headless, no Claude Code needed):
-flow init --profile standard --yes              # chains detect → upstreams → MCPs → scaffold
+# 3. Pick an install path:
+flow init --profile standard --yes              # headless: detect → upstreams → MCPs → scaffold
+# OR, inside Claude Code opened in this project:
+/flow-init                                      # interactive
 
 # Useful at any point:
 flow plan --profile standard                    # preview without executing
@@ -42,7 +45,12 @@ git clone https://github.com/mhd-ghaith-abtah/flow.git
 cd flow && npm install && tools/dev-link.sh     # dev-mode equivalent of install-skills + PATH link
 ```
 
-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 `flow install-skills --scope project` step is what makes `/flow-init` resolve in Claude Code when opened inside the project. Two reasons project scope is the recommended default:
+
+1. **Reliable symlinks.** They point at the stable `/opt/homebrew/lib/node_modules/...` path (or your equivalent npm prefix), so they don't break the way `npx`-based symlinks do when the npx cache rotates.
+2. **No skill pollution elsewhere.** Slash commands only resolve inside this project, not in every Claude Code session you ever open.
+
+If you'd rather have `/flow-*` available globally on your machine, swap step 2 for `flow install-skills` (no `--scope` flag — defaults to `home` / `~/.claude/skills/`). For `npx`-only / no-global-install setups, see [docs/usage.md §1d](docs/usage.md#d-npx--no-install-but-with-a-caveat) — works but requires re-linking before each session. 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`)
@@ -97,7 +105,8 @@ flow install
 ├── Phase B: install Flow's own skills + adapters + templates
 ├── Phase C: delegate to upstream installers
 │   ├── npx bmad-method install --modules <curated subset>
-│   └── ECC ./install.sh --profile <curated subset>
+│   ├── npx -y -p "github:affaan-m/ECC#<commit>" ecc-install --target <user|project> --profile <curated subset>
+│   └── npx -y "github:mhd-ghaith-abtah/caveman#flow-pin-v0.1"   # temporary fork, see Caveman FAQ
 ├── Phase D: install MCP servers (context7, playwright, linear, …)
 ├── Phase E: scaffold flow.config.yaml + docs/flow/
 └── Phase F: smoke test (flow doctor)
@@ -111,8 +120,8 @@ After `/flow-init` you'll have slash commands from all three projects active. Us
 
 | Goal | Command | Owner |
 |---|---|---|
-| Write a PRD, architecture doc, or epic list | `/bmad-create-prd`, `/bmad-create-architecture`, `/bmad-create-epic` | BMad |
-| Generate a fresh story from a BMad epic | `/bmad-create-story` (then `/flow-sprint import-bmad`) | BMad → Flow |
+| Plan a brand-new project (PRD → architecture → stories) | BMad's own workflow (slash names vary by version — BMad 6 uses `/bmad:bmm:2-plan-workflow`, `/bmad:bmm:3-solutioning`, `/bmad:bmm:4-implementation`) | BMad |
+| Import BMad's planning output into Flow | `/flow-sprint import-bmad` or `flow sprint import-bmad` | BMad → Flow |
 | Add a story to the current sprint | `/flow-sprint add "<title>" --epic E1` | Flow |
 | Pick the next story to work on | `/flow-sprint next` | Flow |
 | **Implement → review → verify → commit → PR** | `/flow-story` | Flow (orchestrates ECC) |
@@ -120,11 +129,11 @@ After `/flow-init` you'll have slash commands from all three projects active. Us
 | Just run a code review | `/code-review` | ECC |
 | Just run the documentation updater | `/update-docs` | ECC |
 | Health-check the whole install | `/flow-doctor` | Flow |
-| End-of-sprint retro | `/flow-sprint retro` | Flow |
+| End-of-sprint retro | `/flow-sprint retro E1` (epic-scoped) | Flow |
 
 **Rule of thumb:** if you're moving a story through its lifecycle (plan → code → review → ship), use `/flow-story` — it dispatches to the right ECC primitive at the right phase. If you want to invoke an ECC primitive directly (e.g., to re-review uncommitted code without advancing the story), call it by name; Flow won't get in the way.
 
-**Don't mix:** `/bmad-create-story` and `/flow-sprint add` both create story files. Pick one per project — Flow's import-bmad subcommand bridges the two if you start with BMad and want Flow to take over.
+**Don't double-create:** BMad's create-story slash command and `/flow-sprint add` both produce story files. Pick one per project — Flow's `import-bmad` subcommand bridges the two if you start with BMad and want Flow to take over per-story orchestration.
 
 ## FAQ
 

package/docs/migrate-from-bmad.md

@@ -6,7 +6,7 @@ Flow doesn't replace BMad — it sits on top of it and adds a lightweight per-st
 
 - Your BMad PRD, architecture, and epic documents — `/flow-init` does NOT touch these
 - Your BMad story files in `docs/_bmad-output/stories/` — Flow reads them as references
-- The BMad slash commands — `/bmad-create-prd`, `/bmad-create-epic`, `/bmad-create-story` still work
+- The BMad slash commands keep working — Flow doesn't remove or rename them. The exact slash names depend on which BMad version is installed (BMad 6+ uses the `/bmad:bmm:<step>` namespace, e.g. `/bmad:bmm:2-plan-workflow`, `/bmad:bmm:3-solutioning`, `/bmad:bmm:4-implementation`; older releases used a flatter `/bmad-*` form). Check `~/.claude/skills/` after install to see what BMad registered.
 - `_bmad/_config/manifest.yaml` — Flow records the BMad version for repair
 
 ## What changes
@@ -17,7 +17,7 @@ Flow doesn't replace BMad — it sits on top of it and adds a lightweight per-st
   - `journeys/`, `retros/`, `archive/`, `deferred.md`, `artifacts/`
 - `flow.config.yaml` — adapter + profile config (committed; team-share safe)
 - A new branch convention: `flow/<story-id>-<slug>` — used by `/flow-story` for auto-branching
-- `/flow-story` becomes the per-story orchestrator instead of `/bmad-create-story` + manual stepping
+- `/flow-story` becomes the per-story orchestrator instead of BMad's own per-story workflow + manual stepping
 
 ## Migration
 
@@ -68,14 +68,15 @@ Then create one story stub per entry — `templates/story.md.tmpl` is the shape.
 
 ## Coexistence
 
-Once migrated, you can still create new BMad stories with `/bmad-create-story` and import them into Flow:
+Once migrated, you can still create new stories through BMad's own slash commands (whatever your BMad version exposes) and re-import:
 
 ```
-/bmad-create-story        # writes docs/_bmad-output/stories/E1-002-<slug>.md
-/flow-sprint import-bmad  # detects new BMad story files, generates Flow stubs
+# Run BMad's create-story flow — exact command depends on your BMad version.
+# Then back into Flow:
+/flow-sprint import-bmad      # detects new BMad story files, generates Flow stubs
 ```
 
-The reverse — Flow → BMad — isn't supported. Flow's story stubs are deliberately lighter than BMad's, so round-tripping would lose information. If you need a full BMad-shape story file later, run `/bmad-create-story` and Flow will detect + link it.
+The reverse — Flow → BMad — isn't supported. Flow's story stubs are deliberately lighter than BMad's, so round-tripping would lose information. If you need a full BMad-shape story file later, run BMad's create-story flow and Flow will detect + link it on the next `import-bmad`.
 
 ## Rollback
 

package/docs/profiles.md

@@ -4,13 +4,15 @@ 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 | ECC scope |
+| 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 |
 
+*Tokens-per-story figures assume **Caveman is active in `full` mode** — Caveman compresses Claude Code's responses ~46% on input and ~75% on output, which is the only way these numbers are realistic. Without Caveman, multiply by ~3–4×. See [usage.md §17](usage.md#17-how-caveman-enhances-flow) for the math.
+
 ## What each profile changes
 
 ### `minimal`

package/docs/quickstart.md

@@ -4,28 +4,49 @@ A 10-minute path from zero to first shipped story.
 
 ## Prerequisites
 
-- [Claude Code](https://claude.com/claude-code) installed (`claude` on PATH)
-- Node 20+ (for the `flow` CLI; not strictly required if you only use slash commands)
+- [Claude Code](https://claude.com/claude-code) installed (`claude` on PATH) — only required if you want the `/flow-*` slash commands. The headless CLI works without it.
+- Node 20+
 - Git repo, with `origin` set if you want PRs
 
 ## Install
 
-Inside Claude Code, in your project root:
+```bash
+# 1. Install the Node CLI (once per machine)
+npm install -g @mhd-ghaith-abtah/flow@beta
+flow --version                                # → 0.8.0-beta.2 (or newer)
 
+# 2. Per project — symlink the 4 skills into THIS project's .claude/skills/
+cd /path/to/your/project
+flow install-skills --scope project --force   # ← recommended for slash commands
+
+# 3. Pick a path:
+flow init --profile mini --yes                # headless (no Claude Code needed)
+# OR, inside Claude Code opened in this project:
+/flow-init                                    # interactive Q&A
 ```
-/flow-init
-```
 
-This launches an interactive installer. It will:
+`flow install-skills --scope project` is the bridge — npm puts Flow in `/opt/homebrew/lib/node_modules/...` but Claude Code only resolves slash commands from a scanned path (`~/.claude/skills/` for home scope, `<project>/.claude/skills/` for project scope). Per-project scope is the recommended default because:
+
+- Symlinks point at a stable path that survives until you `npm uninstall`
+- Slash commands only appear inside this project, not in every unrelated Claude Code session
+
+Re-run `flow install-skills --scope project --force` after every Flow upgrade (`npm install -g @mhd-ghaith-abtah/flow@beta`) to refresh the symlinks. It's idempotent.
+
+If you'd rather have `/flow-*` available globally on your machine instead of per-project, omit the `--scope` flag — `flow install-skills` defaults to `home` scope (`~/.claude/skills/`). See [usage.md §1](usage.md#1-installation-paths) for the full breakdown.
+
+## What the installer does
+
+Either path (slash or headless `--yes`) walks the same chain:
 
 1. **Detect project shape** — package manager, framework, existing BMad/ECC install, CLAUDE.md presence
-2. **Ask ~8 questions** — profile (mini/standard/team), adapters (issue tracker, PR platform, E2E, verify), upstream subsets (BMad, ECC, Caveman)
-3. **Delegate to upstream installers** — `npx bmad-method install --modules <curated>`, `ECC ./install.sh --profile <curated>`, plus Caveman
-4. **Set up MCP servers** — context7, playwright, linear (if selected)
-5. **Scaffold docs/flow/ + flow.config.yaml** — sprint.yaml, stories/, journeys/, retros/, deferred.md
+2. **Ask ~9 questions** (interactive only — `--yes` pre-fills from profile defaults):
+   - Q1 profile · Q2–Q5 adapters (issue tracker, PR, E2E, verify) · Q6 BMad subset · Q7 ECC subset · Q7c ECC install scope (user/project) · Q7b Caveman mode · Q8 BMad migration (if detected) · Q9 secrets store
+3. **Delegate to upstream installers** — `npx bmad-method install --modules <curated>`, `npx -y -p "github:affaan-m/ECC#<commit>" ecc-install --target <user|project>`, Caveman from a Flow-maintained fork pinned at `flow-pin-v0.1` (see [usage.md §6](usage.md#6-ecc-install-scope) for the fork-pin story)
+4. **Register MCPs** — context7, playwright, linear, etc. (per profile)
+5. **Scaffold `docs/flow/` + `flow.config.yaml` + `install-state.json`**
 6. **Optionally migrate** an existing BMad `sprint-status.yaml`
 
-Re-running is idempotent — `/flow-init --update` will diff against the recorded state and apply only deltas.
+Re-running is idempotent. To re-resolve against an existing install, see [`flow init --update`](usage.md#8-updating-an-existing-install). To restore deleted scaffold files, see [`flow init --repair`](usage.md#9-repairing-a-broken-install).
 
 ## First story
 
@@ -37,12 +58,12 @@ Re-running is idempotent — `/flow-init --update` will diff against the recorde
 
 `/flow-story` auto-detects the current phase (plan / implement / review / verify / e2e / docs / commit / pr) from `sprint.yaml` + git branch + commit state, and invokes the right ECC primitive at each step. It chains phases automatically until it hits a destructive boundary (commit, PR) or a CRITICAL/HIGH review finding, then pauses for your CONFIRM.
 
-**Useful flags:**
+**Useful `/flow-story` flags:**
 
 | Flag | Effect |
 |---|---|
 | `--auto` | No CONFIRM gates. Use for low-risk stories. |
-| `--auto-merge` | After PR opens, poll `gh pr merge --auto` until CI passes (15-min cap). |
+| `--auto-merge` | After PR opens, poll `gh pr merge --auto` until CI passes (90-second wait cap per attempt; longer CI ends the turn + handoff). |
 | `--hard-review` | Force adversarial + edge-case reviewers regardless of tags. |
 | `--no-review` | Skip code review. Risky. Use for trivial config tweaks. |
 | `--no-verify` | Skip the verify command. Risky. |
@@ -53,30 +74,54 @@ Re-running is idempotent — `/flow-init --update` will diff against the recorde
 
 ## Closing out a story
 
-After a PR merges, `/flow-story` auto-detects the `merge-done` phase and asks for CONFIRM to flip the story to `done`. Or you can do it manually:
+After a PR merges, `/flow-story` auto-detects the `merge-done` phase and asks for CONFIRM to flip the story to `done`. Or do it manually:
 
-```
+```bash
+# Inside Claude Code:
 /flow-sprint done E1-001
+
+# Or headless:
+flow sprint done E1-001 --note "Merged via auto-merge"
 ```
 
 ## End-of-sprint
 
 ```
-/flow-sprint retro
+/flow-sprint retro E1
 ```
 
-Generates `docs/flow/retros/<date>.md` from your last sprint's stories: what shipped, what got deferred, review-finding rollup, verify failure rate.
+Generates `docs/flow/retros/E1-retro.md` (one file per epic, not per date) from the epic's archived story files: shipped count, cycle time, deferred carry-forward, plus blank "What worked / What didn't / Carry into next epic" sections for you to edit.
 
 ## Health check
 
-```
+```bash
+# Inside Claude Code:
 /flow-doctor
+
+# Headless:
+flow doctor
+flow doctor --json
+flow doctor --verbose
+```
+
+Verifies catalog / state / adapter files / MCP registration / required CLIs / upstream installations. Surfaces an ECC scope-collision section when both user-scope and project-scope ECC content exist.
+
+To get repair commands for a specific upstream (BMad / ECC / Caveman pin drift):
+
+```bash
+flow doctor --repair-upstream ecc          # prints the reinstall command
+flow doctor --repair-upstream bmad
+flow doctor --repair-upstream caveman
 ```
 
-Verifies catalog / state / adapter files / MCP registration / required CLIs / upstream installations. Probes for known bugs (caveman-shrink mis-registered, severity-label stripping, loose marker matches). Add `--fix` for safe auto-repairs (prints the commands; doesn't auto-run anything destructive).
+The `--repair-upstream` path prints commands but does NOT auto-run them — upstream installs touch user-scope state, so the user runs them deliberately.
 
-## Next
+## Where to go next
 
-- [profiles.md](profiles.md) — choosing mini vs standard vs team
-- [adapters.md](adapters.md) — picking + swapping integrations
-- [migrate-from-bmad.md](migrate-from-bmad.md) — porting an existing BMad project
+| Goal | Link |
+|---|---|
+| Comprehensive how-to (every flag, every scenario) | [usage.md](usage.md) |
+| Choosing a profile (mini vs standard vs team) | [profiles.md](profiles.md) |
+| Picking + swapping integrations | [adapters.md](adapters.md) |
+| Porting an existing BMad project | [migrate-from-bmad.md](migrate-from-bmad.md) |
+| Starting from zero with planning (PRD → architecture → stories) | [usage.md §2c](usage.md#2c-starting-from-zero-greenfield--bmad-planning) |

package/docs/usage.md

@@ -26,6 +26,7 @@ This is the long-form reference. For the 10-minute first-install path, see [quic
 - [14. Environment variables](#14-environment-variables)
 - [15. Files Flow writes](#15-files-flow-writes)
 - [16. Troubleshooting](#16-troubleshooting)
+- [17. How Caveman enhances Flow](#17-how-caveman-enhances-flow)
 
 ---
 
@@ -33,51 +34,73 @@ This is the long-form reference. For the 10-minute first-install path, see [quic
 
 Flow ships in two surfaces: a Claude Code skill bundle (interactive) and a Node CLI (`flow`, headless). Both invoke the same underlying installers and write the same files.
 
-**Bootstrap order matters.** Claude Code discovers slash commands by scanning `~/.claude/skills/<name>/`. The npm package puts skill files in the install location (typically `~/.npm-global/lib/node_modules/...`), NOT in `~/.claude/skills/`. So `/flow-init` does NOT work after a bare `npm install -g`. You need to run `flow install-skills` once to symlink the four skills into Claude Code's discovery path.
+**Bootstrap order matters.** Claude Code discovers slash commands by scanning `~/.claude/skills/<name>/` (home scope) or `<project>/.claude/skills/<name>/` (project scope). The npm package puts skill files in the install location (typically `/opt/homebrew/lib/node_modules/...` on macOS Homebrew node, or `~/.npm-global/lib/node_modules/...` on other setups), NOT in any of Claude Code's discovery paths. You need to run `flow install-skills` once to symlink the four skills into a discovery path.
 
-### a. From npm (recommended)
+### a. Recommended: `npm install -g` + `flow install-skills --scope project` (per project)
+
+This is the right shape if you want **reliable slash commands** in one or more projects without polluting Claude Code's global skill set.
 
 ```bash
-# 1. Install the Node CLI
+# 1. Once on your machine — installs the `flow` CLI + provides a stable symlink target
 npm install -g @mhd-ghaith-abtah/flow@beta
-flow --version
+flow --version                                  # → 0.8.0-beta.2 (or newer)
 
-# 2. Bootstrap Claude Code surface (links 4 skills into ~/.claude/skills/)
-flow install-skills
+# 2. Per project — symlink the four skills into the project's .claude/skills/
+cd /path/to/project
+flow install-skills --scope project --force
 
-# 3. Now both paths work — pick one per project:
-flow init --profile mini --yes              # headless
-# OR, inside Claude Code:
-/flow-init                                  # interactive
+# 3. Pick your install path
+flow init --profile mini --yes                  # headless
+# OR, inside Claude Code opened in this project:
+/flow-init                                      # interactive
 ```
 
-`flow install-skills` is idempotent — re-run safely after every upgrade to refresh the symlinks. It refuses to clobber existing real directories at the target without `--force`.
+Why this combination is the best default for slash commands:
 
-### b. install-skills scope flag
+- The symlinks point at `/opt/homebrew/lib/node_modules/@mhd-ghaith-abtah/flow/skills/...` — a stable path that persists until you `npm uninstall`. **Never breaks** under normal use.
+- Project-scope means `/flow-*` only resolves when Claude Code is opened inside the project. No skill pollution in unrelated projects.
+- One `npm install -g` covers any number of projects — install-skills per project is the only per-project bootstrap step.
+- Upgrading Flow (`npm install -g @mhd-ghaith-abtah/flow@beta` again later) automatically refreshes every project's symlinks. No re-bootstrap needed.
 
-By default `flow install-skills` writes to `~/.claude/skills/` (home scope). Override:
+### b. Variant: `npm install -g` + `flow install-skills` (user-wide)
+
+If you'd rather have slash commands available **everywhere** on your machine instead of per-project:
 
 ```bash
-flow install-skills                            # default: --scope home
-flow install-skills --scope home               # user-wide ~/.claude/skills/
-flow install-skills --scope project            # team-commit: <cwd>/.claude/skills/
-flow install-skills --scope both               # both
-flow install-skills --dry-run                  # preview
-flow install-skills --force                    # replace existing real dirs
+npm install -g @mhd-ghaith-abtah/flow@beta
+flow install-skills                             # default scope: home (~/.claude/skills/)
 ```
 
-The `--scope project` mode is for teams that want every contributor to get Flow's slash commands the moment they `git clone` the repo — commit `<project>/.claude/skills/flow-*` so Claude Code picks them up automatically when the session is opened inside the project. The user still needs the npm package installed because the symlinks point at it.
+Now `/flow-init` resolves in every Claude Code session. Re-run `flow install-skills` after each `npm install -g` upgrade.
 
-### c. `npx` — no install
+### c. install-skills scope flag
 
 ```bash
-npx -y @mhd-ghaith-abtah/flow@beta install-skills     # one-time bootstrap
+flow install-skills                             # default: --scope home
+flow install-skills --scope home                # user-wide ~/.claude/skills/
+flow install-skills --scope project             # team-commit: <cwd>/.claude/skills/
+flow install-skills --scope both                # both
+flow install-skills --dry-run                   # preview
+flow install-skills --force                     # replace existing real dirs
+```
+
+`--scope project` is the team-commit pattern. Commit `<project>/.claude/skills/flow-*` so any contributor cloning the repo gets the slash commands automatically once they `npm install -g @mhd-ghaith-abtah/flow@beta` on their own machine. The symlinks point at each contributor's local npm install location, so the path is per-machine; what's committed is the four symlink files themselves.
+
+### d. `npx` — no install, but with a caveat
+
+```bash
+npx -y @mhd-ghaith-abtah/flow@beta install-skills --scope project --force
 npx -y @mhd-ghaith-abtah/flow@beta init --profile mini --yes
 ```
 
-`npx` works but the symlink targets the npx cache path, which can disappear when the cache rotates. For ongoing use, prefer `npm install -g`.
+Works for an immediate session, BUT the symlinks point at the npx cache (`~/.npm/_npx/<hash>/node_modules/...`), which npm rotates over time. When the cache entry is purged, the symlinks become broken pointers and `/flow-init` stops resolving with no error. Two ways to handle this:
+
+- **Re-run `npx ... install-skills --scope project --force` before each session that needs slash commands.** Refreshes the symlinks against whatever the current npx cache hash is. Easy to forget.
+- **Or just use path (a) — single `npm install -g` + per-project `flow install-skills`.** Stable symlinks, slash commands always resolve.
 
-### d. Development clone
+`npx` is fine for one-shot use (`flow plan`, `flow doctor`, one-off `flow init`), but for ongoing slash-command access prefer the npm-install-g path.
+
+### e. Development clone (contributors)
 
 ```bash
 git clone https://github.com/mhd-ghaith-abtah/flow.git
@@ -86,8 +109,6 @@ cd flow && npm install && tools/dev-link.sh
 
 `tools/dev-link.sh` is the dev-mode equivalent of `flow install-skills --scope home` — symlinks the four `skills/flow-*` dirs into `~/.claude/skills/` AND puts `flow` on `$PATH` from your clone. Use when you're contributing so changes to skill workflows take effect immediately.
 
-`tools/dev-link.sh` symlinks your clone into `$HOME/.claude/skills/flow-*` and onto `$PATH` as `flow`. Use when you're contributing.
-
 ### e. Verifying the install
 
 ```bash
@@ -191,6 +212,89 @@ Plus, depending on profile:
 - MCPs registered with Claude Code via `claude mcp add`
 - Secrets in `~/.claude/.env.flow` (chmod 600) if any `api_token` MCP was selected
 
+### 2c. Starting from zero (greenfield + BMad planning)
+
+If you have only an idea and no code yet, Flow uses BMad's planning workflow to get you from concept → PRD → architecture → stories → first execution, then takes over per-story orchestration.
+
+**Setup:**
+
+```bash
+mkdir my-idea && cd my-idea
+git init && echo "# My idea" > README.md
+
+npm install -g @mhd-ghaith-abtah/flow@beta
+flow install-skills
+
+# Pick a profile that ships BMad full. `standard` is enough for solo dev:
+flow init --profile standard --yes --bmad-subset full
+```
+
+`--bmad-subset full` installs BMad's `bmm` module (Project Manager, Architect, Product Owner, dev workflows) plus its planning-artifacts directory under `docs/_bmad-output/planning-artifacts/`.
+
+**The planning loop (inside Claude Code):**
+
+Once Flow finishes installing, BMad's slash commands become available. Exact names depend on your BMad version — BMad 6+ uses a `/bmad:bmm:<step>` namespace:
+
+```
+/bmad:bmm:1-analysis          # Optional — competitive research / scope scan
+/bmad:bmm:2-plan-workflow     # PRD (Project Manager agent)
+/bmad:bmm:3-solutioning       # Architecture + tech stack (Architect)
+/bmad:bmm:4-implementation    # Story decomposition (Scrum Master + PO)
+```
+
+Each step writes to `docs/_bmad-output/planning-artifacts/`:
+- `prd.md` — product requirements
+- `architecture.md` — system design
+- `epics.md` — high-level work breakdown
+- `stories/E1-S1-*.md` etc. — individual story files
+
+**Convert BMad's plan into Flow's sprint:**
+
+After BMad produces stories, import them:
+
+```bash
+flow sprint import-bmad
+# OR inside Claude Code:
+/flow-sprint import-bmad
+```
+
+The migrator reads `docs/_bmad-output/implementation-artifacts/sprint-status.yaml`, maps BMad statuses → Flow statuses, and writes `docs/flow/sprint.yaml` with backup-first / rollback-on-failure semantics. BMad's content stays in place — Flow doesn't delete `_bmad/`. See [migrate-from-bmad.md](migrate-from-bmad.md) for the migration mechanics.
+
+**Run the first story through Flow:**
+
+```
+/flow-story E1-S1
+```
+
+Flow takes BMad's story file, runs plan → implement → review → ship on it. BMad gave you the **why** (PRD/architecture); Flow drives the **how** (per-story execution, lighter ceremony, ~5× fewer tokens than BMad's own per-story workflow).
+
+**The whole greenfield arc in one diagram:**
+
+```
+Idea
+ │
+ ▼
+flow init --profile standard --yes --bmad-subset full
+ │
+ ▼
+/bmad:bmm:2-plan-workflow      ── PRD
+ │
+ ▼
+/bmad:bmm:3-solutioning        ── architecture, tech stack
+ │
+ ▼
+/bmad:bmm:4-implementation     ── stories + sprint-status.yaml
+ │
+ ▼
+flow sprint import-bmad        ── stories now live in docs/flow/sprint.yaml
+ │
+ ▼
+/flow-story E1-S1              ── per-story chain
+/flow-story (no args)          ── advance whatever's active
+```
+
+You can also stay in BMad's per-story workflow if you prefer its ceremony. Flow's `/flow-story` is the lighter alternative — same outcome, fewer tokens, slightly less hand-holding.
+
 ---
 
 ## 3. Daily story workflow
@@ -863,15 +967,19 @@ Workaround: pass `--continue-on-error` to skip past upstream failures and inspec
 
 Both `~/.claude/rules/ecc/` and `<project>/.claude/rules/ecc/` exist. Cause: you changed `--ecc-scope` between installs without uninstalling first. The doctor probe reads `install-state.json` to identify the active scope and prints the exact `rm -rf` command for the stale one.
 
-### d. Caveman MCP not active in this session
+### d. Caveman not active in this session
+
+Caveman activates via `~/.claude/hooks/caveman-config.js` on `SessionStart`. Both the slash `/flow-init` and the headless `flow init --yes` (since v0.8.0-beta.2) drop a `.caveman-enable` marker file in your project root when you pick a non-`none` Caveman subset, so allowlist-mode users (`~/.config/caveman/config.json` = `{"defaultMode": "off"}`) get Caveman activated here automatically.
 
-Caveman activates via `~/.claude/hooks/caveman-config.js` on `SessionStart`. If you have `~/.config/caveman/config.json` set to `{"defaultMode": "off"}` (the recommended allowlist mode), drop a `.caveman-enable` marker in the project root:
+If you're on an older Flow version OR you picked `--caveman-subset none` at install time and changed your mind:
 
 ```bash
 touch .caveman-enable
 ```
 
-Flow's `/flow-init` drops this automatically. Restart your Claude Code session for the hook to re-fire.
+Then restart your Claude Code session for the hook to re-fire.
+
+If the marker exists and Caveman still doesn't activate, run `flow doctor` and look at the Caveman row — `version=not pinned` plus an `installed=false` state record means the upstream installer never ran. Re-run `flow init --update` to fix.
 
 ### e. `flow sprint done E1-002` says "expects 'review' or 'doing'"
 
@@ -930,6 +1038,111 @@ This blows away Flow + Flow's project content + project-scope ECC. Does NOT remo
 
 ---
 
+## 17. How Caveman enhances Flow
+
+[Caveman](https://github.com/JuliusBrussee/caveman) is an output-compression layer that runs at the Claude Code session level. It rewrites Claude's responses to use dense prose patterns while preserving full technical content. Code, error messages, commits, and security-relevant text stay normal. Filler — pleasantries, hedging, articles, restating the question — gets dropped.
+
+Flow expects Caveman to be active. The token budgets advertised throughout these docs assume Caveman is on. Without it, the realistic numbers are roughly 3–4× higher.
+
+### a. The concrete numbers
+
+- **~46% input token savings** — Caveman compresses your conversation history before sending it to Claude
+- **~75% output token savings** — Caveman post-processes Claude's responses on the way out
+
+### b. Why Flow needs it specifically
+
+Flow's per-story phase chain runs many small phases (plan → implement → review → docs → commit → PR). Each phase reads context (story file, code diff, review notes) and generates output. Without compression:
+
+- One `/flow-story` invocation pulls ~30–50k of context per phase
+- Chained across phases, a single story costs ~100k input + ~50k output ≈ **~150k tokens**
+- A 10-story sprint ≈ **~1.5M tokens**
+
+With Caveman in `full` mode:
+
+- Per-story cost drops to ~30k tokens
+- 10-story sprint ≈ **~300k tokens**
+
+Flow's "token-light per-story workflow" tagline only works because Caveman compresses both directions.
+
+### c. What it looks like in practice
+
+Without Caveman, a typical assistant response:
+
+> Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by a race condition in the authentication middleware where the token expiry check uses a strict less-than comparison instead of less-than-or-equal-to.
+
+With Caveman in `full` mode:
+
+> Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:
+
+Same technical content, ~75% fewer tokens. Code blocks render normally — Caveman doesn't touch them.
+
+### d. Modes Flow ships
+
+| Mode | Compression | Use when |
+|---|---|---|
+| `none` | 0 | Disabled. Only if you have a specific reason. |
+| `lite` | ~20% | Most readable. Demo / pairing sessions. |
+| `full` | ~75% | **Default for every stock profile.** Recommended baseline. |
+| `ultra` | ~85% | Aggressive — occasionally harder to skim. |
+| `wenyan-*` | varies | Classical Chinese variants (experimental). |
+
+The chosen mode lives in `flow.config.yaml > upstreams.caveman.subset` (the catalog uses the `caveman_subset` field name for the same setting). Override during install via the interactive Q7b prompt; override per-session via Caveman's own `/caveman <mode>` slash command (if installed).
+
+### e. Project-scope gating — the fork story
+
+Caveman's default install activates it **globally** — every Claude Code session on your machine gets compressed output, including unrelated projects. Most users want Caveman only in Flow-managed projects.
+
+Caveman's `.caveman-enable` / `.caveman-disable` marker files solve this, but the feature is in [JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407) — filed 2026-05-19 and still waiting in an upstream queue with ~134 open PRs and ~5 merges/month, so months of wait.
+
+Flow's catalog pins Caveman to 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. The bootstrap order in Flow-managed projects:
+
+1. Flow installs Caveman from the fork (transparent — happens during `/flow-init` or `flow init --yes`).
+2. Flow's `/flow-init` drops a `.caveman-enable` marker file in the project root.
+3. If the user has set `~/.config/caveman/config.json` to `{"defaultMode": "off"}` (allowlist mode), Caveman stays silent everywhere EXCEPT projects with the marker.
+
+You don't have to do anything — Flow's installer handles all of this. The marker file works identically against upstream Caveman and the fork, so when upstream #407 merges, the catalog swap is a no-op at the project level.
+
+### f. How to turn Caveman off in one project
+
+```bash
+touch .caveman-disable          # in the project root
+```
+
+Restart your Claude Code session. Caveman ignores this project. Remove the file to re-enable.
+
+### g. How to opt OUT entirely on this machine
+
+Caveman's CLI (`caveman` on your $PATH after install):
+
+```bash
+caveman off                     # global default off
+caveman on                      # global default on
+caveman <mode>                  # switch active mode
+```
+
+If you want zero Caveman exposure but still want Flow, install with `--caveman-subset none` (interactive Q7b → `none`) and Flow won't invoke the Caveman installer at all. Flow still works — your tokens-per-story figures go up ~3–4×.
+
+### h. Trade-offs Flow accepts
+
+| Pro | Con |
+|---|---|
+| 3–5× lower token bill for the same outcome | Dense responses can be harder to skim for new users |
+| Phase-chain orchestration becomes affordable | Caveman has its own bug surface; `/flow-doctor` probes for known issues |
+| Caveman skill bundle is small (~kB-scale) | Adds another dependency the catalog tracks + Flow has to keep current |
+| The marker-file gating means Caveman doesn't leak into non-Flow projects | The fork pin is temporary — adds a swap-back step when upstream merges #407 |
+
+### i. Tracking the upstream merge
+
+Flow's catalog comments mark Caveman as a temporary fork explicitly. To check upstream merge status yourself:
+
+```bash
+gh pr view 407 --repo JuliusBrussee/caveman --json state,mergedAt
+```
+
+When `state` flips to `MERGED`, Flow's next release will swap `catalog.yaml > upstreams.caveman.installer.cmd` back to the upstream npx command and remove the SWAP PLAN comment block.
+
+---
+
 ## See also
 
 - [Quickstart](quickstart.md) — 10-minute first-install path

package/lib/commands/doctor.js

@@ -131,9 +131,17 @@ function probeJson(path, scope) {
 }
 
 function probeConfig(ctx) {
-  const path = join(ctx.cwd, 'flow.config.yaml');
+  // Canonical path is .claude/flow.config.yaml (where scaffold writes).
+  // Legacy root-level flow.config.yaml is checked as a fallback for installs
+  // done before the .claude/ convention. First-match-wins.
+  const canonicalPath = join(ctx.cwd, '.claude', 'flow.config.yaml');
+  const legacyPath = join(ctx.cwd, 'flow.config.yaml');
+  const path = existsSync(canonicalPath) ? canonicalPath : legacyPath;
   const r = { path, status: '✗', error: null, parsed: null };
   if (!existsSync(path)) {
+    // Surface the canonical path in the "not present" hint so users know
+    // where to look (or where the install would write to next time).
+    r.path = canonicalPath;
     r.status = 'ℹ';
     r.error = 'not present (run /flow-init)';
     return r;

package/lib/commands/uninstall.js

@@ -26,7 +26,9 @@ const HOME_PATHS = [
 
 const PROJECT_PATHS = [
   '.claude/flow',
-  'flow.config.yaml',
+  '.claude/flow.config.yaml',          // canonical (where scaffold writes)
+  '.claude/flow.config.local.yaml',
+  'flow.config.yaml',                  // legacy root-level (for backward compat)
   'flow.config.local.yaml'
 ];
 

package/lib/init/orchestrate.js

@@ -24,6 +24,8 @@
 // files. Integration tests use --dry-run to exercise the full path
 // without polluting the developer's MCP config / installed upstreams.
 
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { resolveProfile } from '../catalog.js';
 import { detect } from './detect.js';
 import { askAll } from './questions.js';
@@ -114,6 +116,24 @@ export async function runInit(opts) {
     return halt('caveman upstream failed', { detection, state, upstreamResults });
   }
 
+  // 4b. Drop the .caveman-enable marker in the project root.
+  // Matches what skills/flow-init/workflow.md does on the slash path: when
+  // Caveman is requested for this project (subset !== 'none'), put a
+  // zero-byte marker so Caveman activates here even when the user has
+  // ~/.config/caveman/config.json set to {"defaultMode": "off"} (allowlist
+  // mode). Idempotent — if the marker already exists, leave it alone.
+  // Headless parity with the slash path; closes the gap where docs claimed
+  // the marker landed automatically but only the slash workflow did it.
+  const cavemanRequested = (state.answers.cavemanSubset || profile.caveman_subset) !== 'none';
+  if (cavemanRequested && !opts.dryRun) {
+    const markerPath = join(cwd, '.caveman-enable');
+    if (!existsSync(markerPath)) {
+      try { writeFileSync(markerPath, ''); } catch {
+        // Non-fatal — the install still works; user can `touch .caveman-enable` manually.
+      }
+    }
+  }
+
   // 5. MCP registration. Resolved from profile.mcps; idempotent per mcp.js.
   const mcpIds = Array.isArray(profile.mcps) ? profile.mcps : [];
   const mcpDefs = mcpModule.resolveMcps(catalog, mcpIds);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhd-ghaith-abtah/flow",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.3",
   "description": "Token-light per-story workflow for Claude Code. Delegates to BMad + ECC.",
   "license": "MIT",
   "type": "module",