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

package/CHANGELOG.md

@@ -6,6 +6,14 @@ 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

package/README.md

@@ -97,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)
@@ -111,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) |
@@ -120,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/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) |

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)
 
 ---
 
@@ -191,6 +192,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 +947,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 +1018,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/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.2",
   "description": "Token-light per-story workflow for Claude Code. Delegates to BMad + ECC.",
   "license": "MIT",
   "type": "module",