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

package/CHANGELOG.md

@@ -6,6 +6,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **`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

package/README.md

@@ -23,25 +23,26 @@ Existing per-story workflows are token-heavy. BMad's create-story re-reads epics
 > **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 for first install — interactive)
-/flow-init
-
-# Headless install via npm — beta channel (no Claude Code required)
+# 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/
+
+# 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
 
-# One-shot via npx — no install
-npx -y @mhd-ghaith-abtah/flow@beta init --profile mini --yes
-
-# Or from a clone (development / contributing)
+# 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
 ```
 
-Two paths, same end state. `/flow-init` is interactive — Claude Code drives the Q&A, error recovery, and multi-step ceremony. `flow init --yes` is headless — pre-populates every answer from the profile defaults so it runs end-to-end without prompts (override individual knobs via `--ecc-scope`, `--bmad-subset`, `--ecc-subset`). Both invoke the same upstream installers and scaffold the same files.
+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`)
@@ -55,6 +56,8 @@ The installer detects your project shape, then:
 
 ## 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
@@ -94,7 +97,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)
@@ -108,8 +112,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) |
@@ -117,11 +121,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/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
@@ -68,7 +69,7 @@ Version ${PKG.version} · ${chalk.dim(PKG.homepage)}
 `;
 
 const COMMANDS = [
-  'init', 'install', 'plan', 'status', 'doctor', 'add', 'remove', 'uninstall',
+  'init', 'install', 'install-skills', 'plan', 'status', 'doctor', 'add', 'remove', 'uninstall',
   'list-profiles', 'list-components', 'list-mcps', 'mcp', 'sprint', 'help', 'version', '--version'
 ];
 

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,41 @@ 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
+npm install -g @mhd-ghaith-abtah/flow@beta
+flow --version                                # → 0.8.0-beta.1 (or newer)
 
+# 2. Bootstrap Claude Code's slash command discovery
+flow install-skills                           # symlinks 4 skills into ~/.claude/skills/
+
+# 3. Pick a path per project:
+flow init --profile mini --yes                # headless (no Claude Code needed)
+# OR, inside Claude Code:
+/flow-init                                    # interactive Q&A
 ```
-/flow-init
-```
 
-This launches an interactive installer. It will:
+`flow install-skills` is the bridge — npm puts Flow in `~/.npm-global/lib/node_modules/...` but Claude Code only scans `~/.claude/skills/<name>/`. Without that step, `/flow-init` won't resolve. Re-run after every Flow upgrade to refresh the symlinks (idempotent).
+
+## 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 +50,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 +66,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) |