@mhd-ghaith-abtah/flow 0.7.2-beta.0

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to Flow are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.2-beta.0] — 2026-05-19
+
+### Changed
+- `package.json` `files` block tightened for first npm publish: exclude `*.test.js` (internal unit tests, not user examples) and `docs/flow/` (Flow's internal dogfood backlog — sprint.yaml, scope-reviews, deferred ledger). Tarball drops from 61 → 53 files, 91.2 kB → 80.8 kB packed. User-runnable utilities (`tools/lint-changelog.js`, `tools/fix-caveman-shrink.sh`) added to the allowlist.
+
+## [0.7.1] — 2026-05-19
+
+### Added
+- `/flow-init` now drops a `.caveman-enable` zero-byte marker in the project root. Pairs with the upstream Caveman PR ([JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407)) that adds project-scope gating via `.caveman-enable` / `.caveman-disable` markers + env var + config allow/deny lists. Flow's own repo carries the marker so contributors keep Caveman active here even with global default flipped to off. Fully closes #9 + #25 once the upstream PR merges.
+- `docs/flow/scope-reviews/2026-05-19.md` — first scope-review dogfood run on Flow's own backlog. Spawned background general-purpose agent against `docs/flow/sprint.yaml` + reference docs + git log. Output: 3 merges + 3 drops + 3 splits + 7 adds + 3 epic-reconsiderations proposed; all 3 merges / drops / splits and all 7 adds applied; light epic change (E5 renamed CLI + release-hardening; full re-cut deferred to v0.8). `sprint.yaml` grew 32 → 46 stories with retroactive attribution for hidden CHANGELOG work. Honest postmortem flagged E5 as scope creep and E3-007 docs story as too coarse. Closes #14.
+
+### Fixed
+- Upstream Caveman PR #407 hot-fix: project-scope check now precedes the global `off` branch so `.caveman-enable` actually activates caveman when the user has flipped global default to `off` (allowlist mode). Original logic order silently broke the canonical workflow. Pushed as commit `5602309` to the PR branch with 2 new test cases. Local install also patched. `~/.config/caveman/config.json` now set to `{"defaultMode":"off"}` so non-Flow projects stay silent; Flow projects activate via `.caveman-enable` marker that `/flow-init` drops.
+- E5-009 — stripped the false `/flow-sprint scope-review --apply-from <path>` promise from the workflow. Text now points at same-day re-run for resumed interactive apply.
+
+### Added
+- `flow doctor --repair-upstream <bmad|ecc|caveman>` — prints the exact commands to reinstall an upstream at its pinned version after drift. Does NOT auto-run (upstream installers touch user-scope state and curl-pipe-bash should never be implicit). Closes E5-005.
+- `tools/lint-changelog.js` + `changelog-format` CI job — enforces CONTRIBUTING.md's "one-line entries" rule. Flags wrapped CHANGELOG entries with line numbers. Honors fenced code blocks and indented continuation. Closes E5-006.
+- `lib/commands/doctor.test.js`, `install.test.js`, `add.test.js`, `remove.test.js`, `tools/lint-changelog.test.js` — coverage for the previously-untested CLI command modules plus the new linter. Suite now 51/51 (was 18 before this batch).
+
+### Changed
+- README refreshed for v0.7.0: install status block now states the truth (clone + dev-link works; npm publish pending as E1-002), "three skills" → four (flow-doctor added), install bullets mention Caveman installer + SHA-256 inspection + `.caveman-enable` marker + BMad migration backup. The Caveman scope FAQ entry now links to [JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407) and documents the `{"defaultMode": "off"}` + allowlist mode you can apply today.
+- E5-007 — stripped the team-profile `features` block (`multi_repo: true`, `multi_llm_review: true`, `audit_log: true`) from catalog.yaml. All three had zero implementation; `multi_llm_review` was a renamed duplicate of `review.use_separate_model` which is real. README + `docs/profiles.md` team-profile descriptions rewritten to ship-as-stated. Read-only multi-repo awareness tracked as deferred E5-010 (build on real demand, not speculatively).
+- `flow.config.yaml` + `docs/flow/sprint.yaml` + `docs/flow/deferred.md` — Flow now dogfoods Flow. Sprint state maps the 28-issue v0.6.1 review backlog to 5 epics. `/flow-sprint scope-review` can now be run on Flow's own backlog (closes prep for #14).
+- `lib/commands/doctor.js` — `flow doctor` headless health check. Probes catalog parse + schema, install-state at each scope, flow.config.yaml shape, adapter file presence + symlink kind (mixed-state warning), required CLIs in $PATH, upstream pin status. Exit code 0/1/2 for ok/warn/fail. JSON output via `--json`. LLM-dependent probes (MCP responsiveness, severity-label scan) remain in `/flow-doctor` skill.
+- `lib/commands/install.js` — `flow install` headless install path. Runs catalog operations (copy components, ensure dirs, touch state) but intentionally does NOT invoke BMad/ECC/Caveman/MCP installers (those need interactive auth + curl-pipe-bash confirmations). Surfaces clear "next steps" hand-off to `/flow-init` for the remainder.
+- `lib/commands/add.js` + `lib/commands/remove.js` — single-adapter swap via CLI. `flow add adapter:e2e-playwright-mcp --yes` copies adapter files AND updates `flow.config.yaml.adapters.<family>`. `flow remove` flips the family back to its `none` variant (Flow expects SOME adapter per family) without deleting adapter files from disk.
+- `lib/commands/plan.test.js` + `lib/commands/uninstall.test.js` — coverage for the CLI command modules. Suite now 18 tests, all green.
+
+## [0.7.0] — 2026-05-19
+
+### Added
+- `flow-doctor` skill — health check for catalog / state / adapters / MCPs / CLIs / upstreams + probes for known bugs (caveman-shrink standalone vs wrapper, stripped severity labels, loose `## Plan` markers, upstream version drift, Caveman global scope, adapter symlink drift). Supports `--fix` for safe auto-repairs. Closes #7.
+- `lib/catalog.js` + `lib/repo-root.js` + `lib/commands/plan.js` + `lib/commands/init.js` + `lib/commands/uninstall.js` — first real implementation of the `flow` CLI commands (replaces stub dispatch). `flow plan` resolves profiles with `extends:` inheritance and adapter family-override; `--json` emits machine-readable plan. `flow uninstall` defaults to `--scope project` (safe), dry-runs by default, requires `--execute --yes` to actually remove. Does NOT touch BMad / ECC / Caveman. Closes #1 (code path), #8.
+- `lib/catalog.test.js` — first test file. 7 tests pass under `npm test` (`node --test`). Closes second half of #3.
+- `.github/workflows/ci.yml` — GitHub Actions CI on push + PR. Matrix Node 20 + 22. Runs `npm test`, smoke-tests all four profiles, shellchecks `tools/`, enforces the CHANGELOG-touched rule from CONTRIBUTING.md. Closes second half of #3.
+- `.github/PULL_REQUEST_TEMPLATE.md` — PR checklist matching CONTRIBUTING.md.
+- `schemas/catalog.schema.json`, `schemas/install-state.schema.json`, `schemas/flow-config.schema.json` — JSON Schema (draft-07) for the three hand-editable surfaces. `loadCatalog` runs ajv validation when the schema is present; throws with grouped error messages on violation. New test asserts the shipped `catalog.yaml` passes its own schema. Closes #11.
+- `tools/fix-caveman-shrink.sh` — print-only repair for the caveman-shrink standalone-vs-wrapper MCP registration bug. Does NOT auto-run `claude mcp` (modifying MCP registration affects every session). Closes #5.
+- `tools/release.sh` — release-cutting script. Sanity-checks (clean tree, on main, up to date), runs tests + smoke, moves `[Unreleased]` to dated heading, bumps `package.json`, commits + tags + pushes. Supports `patch | minor | major | <explicit-version>` + `--dry-run` + `--no-push`. Closes #22.
+- `CONTRIBUTING.md` — setup, branch conventions, CHANGELOG-on-every-PR rule, versioning + release flow, PR checklist. Closes #23.
+- `docs/quickstart.md`, `docs/profiles.md`, `docs/adapters.md`, `docs/migrate-from-bmad.md` — first real documentation pass. Covers 10-min path to first shipped story, profile selection rationale, adapter contract + inventory, BMad → Flow migration including rollback. Closes #17.
+- README FAQ section (8 questions: BMad/ECC/Flow split, profile selection, Caveman, GitHub-free workflows, upgrade, uninstall, config-commit safety, bug reports) + "When to use which command" precedence table (BMad / Flow / ECC mapping per lifecycle phase). Closes #20 + #27.
+- Curl-pipe-bash inspection (when `FLOW_INSPECT_INSTALL_SCRIPTS=1`) now prints the downloaded script's SHA-256 alongside path + line count. Closes #21.
+
+### Changed
+- README: stripped premature `npx @mhd-ghaith-abtah/flow-init` claim; documented current state as slash-command only until v0.7 npm publish lands.
+- `flow.config.yaml` is now explicitly committed (team-share); per-developer overrides go in `flow.config.local.yaml` (gitignored). `flow-story` deep-merges local on top of base. Template comment + `flow-init` gitignore additions cover the new convention.
+- `caveman-commit` now receives raw inputs (story.id, title, tags, changed_files, severity counts, verify command, e2e status) instead of the caveman-compressed `## Review Notes` block — eliminates double-compression that was degrading commit-message quality.
+- `--auto-merge` no longer polls 30s × 15min (≈30 `gh pr view` calls eating main-context). Single 90s wait, then either continue to merge-done (fast-CI case) or end turn with a handoff. Next `/flow-story` invocation re-checks. Configurable via `config.pr.auto_merge_wait_seconds`.
+- `flow-story` review barrier: 15-min wall-clock timeout (configurable via `config.review.barrier_timeout_seconds`). Timed-out reviewers no longer deadlock the commit phase — they halt with explicit options instead of waiting forever.
+- `flow-story` severity gate: hardened against caveman-review label stripping. Raw severity counts (from un-compressed reviewer output) are now the single source of truth; compressed `## Review Notes` get a `Findings: X critical · Y high · …` header prepended if all severity tokens are stripped.
+
+### Fixed
+- Cycle-detection in profile inheritance (`resolveProfile` throws on cycles instead of stack-overflowing).
+- `flow-story` plan phase decision tree restructured. Six lettered paths (A–F) collapsed into four numbered branches, ordered from most-specific (flag-driven) to default. Comments now explicitly state when each branch fires (e.g., "Caveman not installed AND --auto"). Resolves the "unreachable paths E + F when Caveman installed" confusion. Closes #15.
+- `/flow-init --migrate-bmad` now stages backups (`*.flow-backup-<timestamp>`) of `sprint-status.yaml`, `deferred-work.md`, and any pre-existing `docs/flow/sprint.yaml` BEFORE any migration write. Validates produced `sprint.yaml` after write; if parse fails or story count drops to zero, restores from backups and halts with the parse error. Backup paths recorded in `install-state.json.migrations.bmad.backups`. Documented in `docs/migrate-from-bmad.md` was previously aspirational — now implemented. Closes #19.
+- `/flow-init` now records the installed version of every upstream (BMad / ECC / Caveman) at install time in `install-state.json.upstreams.<name>.version`. `flow-doctor` adds a version-drift probe that warns when the currently-installed version differs from the pinned version — catches silent BMad/ECC/Caveman interface changes. Closes #12.
+- `/flow-sprint add` story-id detection now supports `tracker-style` (e.g. `PLA-42`, `ENG-100`), `kebab` (e.g. `setup-auth`), and `custom` formats alongside `bmad` and `flow-native`. Free-form formats prompt for the next id instead of HALTing on "unrecognized format". Closes #26.
+- `/flow-doctor` adapter probe now distinguishes `symlink → <target>`, `regular_file` (mixed-state drift warning), and `missing` for each adapter file. Resolves the previously-undefined behavior when a project mixes real adapter files with Flow's symlinks. Closes #28.
+- Anchored `## Plan` / `## Review Notes` / `## Verified` / `## E2E` marker detection in `flow-story` phase decision. Previous loose match (`grep -c '^## Plan'`) false-matched `## Plan B` or `## Planning`. Now requires exact heading.
+- `flow-doctor` caveman-shrink probe corrected: caveman-shrink is an MCP proxy (not a skill). Probe now reads `claude mcp get caveman-shrink` and flags standalone registrations that cause `-32000` errors. `tools/fix-caveman-shrink.sh` prints the exact remove + re-add commands (does NOT auto-run — MCP registration affects every Claude Code session).
+
+
+## [0.0.1] — 2026-05-18
+
+### Added
+- Initial scaffold: `flow-init`, `flow-sprint`, `flow-story` skills
+- Catalog (`catalog.yaml`) with profiles `mini`, `standard`, `team`
+- Adapter interfaces for `issue-tracker`, `pr`, `e2e`, `verify`
+- v0.1 adapters: `linear`, `github-issues`, `none` (issue-tracker);
+  `github`, `none` (pr); `playwright-mcp`, `none` (e2e); `make`, `pnpm`, `custom` (verify)
+- BMad delegation: invokes `npx bmad-method install --modules <curated>`
+- ECC delegation: invokes `./install.sh --profile <curated> --with --without`
+- MCP integration: `context7`, `playwright`, `linear`, `github-mcp` (optional)
+- Node CLI binary (`bin/flow.js`) with subcommands `install`, `plan`, `status`, `doctor`, `add`, `remove`, `uninstall`
+- Slash command parity inside Claude Code
+- Migration from BMad `sprint-status.yaml`
+- State store at `~/.claude/flow/install-state.json` and `<project>/.claude/flow/install-state.json`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mhd Ghaith Al Abtah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# Flow
+
+> Token-light per-story workflow for Claude Code. Delegates to BMad + ECC + Caveman instead of duplicating them.
+
+Flow is a thin orchestration layer. It owns three things:
+- Per-story state (`sprint.yaml` + tiny story files)
+- Pluggable adapters (issue tracker, PR platform, E2E, verify)
+- An installer that **invokes BMad, ECC, and Caveman's own installers** so you choose exactly which upstream pieces land in your project
+
+Everything else is delegated:
+- `/plan`, `/prp-implement`, `/code-review`, `/update-docs` etc. come from [ECC](https://github.com/affaan-m/everything-claude-code)
+- PRD + architecture + epics + retros come from [BMad](https://github.com/bmad-code-org/BMAD-METHOD) when you want them
+- Response-token compression comes from [Caveman](https://github.com/JuliusBrussee/caveman) (default `full` mode, ~46% input / ~75% output savings, auto-installed by `/flow-init`)
+
+Flow stitches them together.
+
+## Why
+
+Existing per-story workflows are token-heavy. BMad's create-story re-reads epics + architecture + UX + previous story + git log every iteration. GSD spawns parallel 200k-context subagents. spec-kit ships 8 artifact files per feature. A ~30-line story stub plus delegation to ECC's existing primitives lands at **~20k tokens per story in mini mode** vs **~95k in BMad full**.
+
+## Install
+
+> **Status (v0.7.0):** the `npx` install path is not yet published to npm. The headless CLI (`node bin/flow.js plan / install / doctor / add / remove / uninstall`) is fully working from a clone. Slash commands are the recommended primary path. `npx @mhd-ghaith-abtah/flow init` lands once the package is published; tracked as E1-002 in `docs/flow/sprint.yaml`.
+
+```bash
+# Inside Claude Code (recommended)
+/flow-init
+
+# Headless (works today against a clone — npm publish pending)
+git clone https://github.com/mhd-ghaith-abtah/flow.git
+cd flow && npm install && tools/dev-link.sh
+flow plan --profile standard
+```
+
+The slash-command path runs the same interactive installer. It detects your project shape, asks ~8 questions, then:
+- Installs Flow's four skills (`flow-init`, `flow-sprint`, `flow-story`, `flow-doctor`)
+- Optionally invokes `npx bmad-method install` with a curated module list
+- Optionally invokes ECC's `install.sh` with a curated profile
+- Optionally invokes Caveman's installer (curl-pipe-bash, with SHA-256 inspection support via `FLOW_INSPECT_INSTALL_SCRIPTS=1`)
+- Sets up MCP servers needed by your selected adapters (`context7`, `playwright`, `linear`, …)
+- Writes `flow.config.yaml` + scaffolds `docs/flow/`
+- Drops a `.caveman-enable` marker so Caveman activates here even if the user's global default is `off` (see Caveman FAQ entry below)
+- Optionally migrates an existing BMad `sprint-status.yaml` (with backup + rollback)
+
+## Quickstart
+
+```bash
+$ /flow-init                                              # one time per project
+$ /flow-sprint add "First story" --epic E1 --tags ui      # add a story
+$ /flow-sprint next                                       # start work
+$ /flow-story                                             # implement → review → verify → commit → PR
+$ /flow-sprint done E1-001                                # close out
+```
+
+## Profiles
+
+| Profile | When | Tokens/story |
+|---|---|---|
+| `mini` | Solo, single repo, light review | ~20k |
+| `standard` | Solo or small team, formal review, PRs | ~40k |
+| `team` | Small team, Linear sprints, separate-model review | ~60k |
+
+All three are mode flags on the same skills, not different code paths.
+
+## Adapters
+
+Pick one per category in `flow.config.yaml`:
+
+| Category | v0.1 adapters |
+|---|---|
+| Issue tracker | `linear`, `github-issues`, `none` |
+| PR platform | `github`, `none` |
+| E2E | `playwright-mcp`, `none` |
+| Verify | `make`, `pnpm`, `custom` |
+
+More coming in v0.2: `jira`, `notion`, `plain`, `gitlab`, `bitbucket`, `cypress`, `slack`, `discord`.
+
+## Architecture
+
+```
+flow install
+├── Phase A: detect (BMad? ECC? which MCPs? which CLIs?)
+├── 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>
+├── Phase D: install MCP servers (context7, playwright, linear, …)
+├── Phase E: scaffold flow.config.yaml + docs/flow/
+└── Phase F: smoke test (flow doctor)
+```
+
+Flow does not re-implement BMad or ECC. It calls them with the right flags and records what it did in `~/.claude/flow/install-state.json`.
+
+## When to use which command
+
+After `/flow-init` you'll have slash commands from all three projects active. Use this table when you're not sure which to invoke:
+
+| 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 |
+| 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) |
+| Just write code with a plan gate | `/plan` then `/prp-implement` | ECC |
+| 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 |
+
+**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.
+
+## FAQ
+
+**Why not just use BMad on its own?**
+BMad re-reads epics + architecture + UX + previous story + git log every iteration. That lands at ~95k tokens per story in full mode. Flow keeps the planning artifacts but skips the re-reads on every cycle — a story stub plus delegation to ECC's `/prp-implement` lands at ~20k in mini mode.
+
+**Why not just use ECC?**
+ECC owns the per-story primitives (`/plan`, `/prp-implement`, `/code-review`, `/update-docs`). What it doesn't own is the *between-stories* state: which story is next, which is in review, which is deferred, which adapter handles PRs in this repo. Flow's `sprint.yaml` + `flow-story` skill is that thin layer.
+
+**Do I need Caveman?**
+Yes for now — Flow expects it. Caveman compresses Claude's responses ~75% in `full` mode, which is what makes mini-profile's 20k-tokens-per-story claim realistic. `/flow-init` installs it automatically with the right registration (see `tools/fix-caveman-shrink.sh` if the MCP proxy gets mis-registered).
+
+**Caveman is now active in every Claude Code session, even my non-Flow projects. Can I scope it?**
+Caveman's `SessionStart` hook activates globally by default. Native project-scope gating is shipping upstream via [JuliusBrussee/caveman#407](https://github.com/JuliusBrussee/caveman/pull/407) (filed and reviewed by Flow's maintainer; awaiting upstream merge). The PR adds `.caveman-enable` / `.caveman-disable` marker files, a `CAVEMAN_PROJECT_SCOPE` env var, and config-driven `projectScope.allow[]` / `deny[]` lists. To opt into allowlist mode today, set `~/.config/caveman/config.json` to `{"defaultMode": "off"}` — Caveman stays silent everywhere except projects with `.caveman-enable` in their root. Flow's `/flow-init` drops that marker automatically, so Flow-managed projects keep working. `/flow-doctor` surfaces a probe for "Caveman active outside a Flow project" until the PR merges.
+
+**Which profile should I pick?**
+- `mini` — solo, single repo, light review, no formal PR process → ~20k/story
+- `standard` — solo or small team, formal review, GitHub PRs, Playwright E2E → ~40k/story
+- `team` — small team, issue tracker (Linear default), separate-model code review (spawns one reviewer with a different model for fresh perspective) → ~60k/story
+
+You can swap profiles with `/flow-init --update --profile <name>` — it's just a different bundle, not a different codepath.
+
+**What if I don't use GitHub?**
+Pick `adapter:pr-none` during `/flow-init` and configure `verify` + `e2e` to whatever you do use. GitLab + Bitbucket adapters are planned for v0.2.
+
+**How do I upgrade Flow?**
+`/flow-init --update` is idempotent. It re-detects project shape, diffs against `install-state.json`, and applies only the deltas. Upstream installers (BMad / ECC / Caveman) are re-invoked only when their pinned subset changes.
+
+**What happens if I uninstall?**
+`/flow uninstall` removes Flow's own skills and adapters. It does NOT remove BMad, ECC, or Caveman — those were installed by their own installers and Flow recorded that, not owned it. Your `sprint.yaml` + stories stay on disk.
+
+**Is my `flow.config.yaml` safe to commit?**
+Yes — it's intentionally team-shared (adapter choices, review policy, verify command). Secrets live in `~/.claude/.env.flow` (chmod 600, never committed). Per-developer overrides go in `flow.config.local.yaml` (gitignored) which Flow merges over the base config.
+
+**Where do I report bugs?**
+[github.com/mhd-ghaith-abtah/flow/issues](https://github.com/mhd-ghaith-abtah/flow/issues). Run `/flow-doctor` first — it surfaces known-bug patterns automatically.
+
+## Credits
+
+Flow stands on:
+- **[BMad-Method](https://github.com/bmad-code-org/BMAD-METHOD)** by bmad-code-org — planning workflow (PRD, architecture, epics)
+- **[Everything Claude Code (ECC)](https://github.com/affaan-m/everything-claude-code)** by affaan-m — per-story primitives (`/plan`, `/prp-*`, `/code-review`, `/update-docs`)
+- **[Get Shit Done (GSD)](https://github.com/gsd-build/get-shit-done)** by TÂCHES — concept inspiration
+- **[spec-kit](https://github.com/github/spec-kit)** by GitHub — spec-driven development pattern
+- **[AI Dev Tasks](https://github.com/snarktank/ai-dev-tasks)** by snarktank — lean PRD + tasks pattern
+
+## License
+
+MIT

package/adapters/e2e/_interface.md

@@ -0,0 +1,42 @@
+# E2E Adapter Interface
+
+E2E adapters run the user-journey block from a story file against a live app.
+
+## Required operations
+
+### `run_journey(story_file, base_url) → { passed, failed, artifacts }`
+
+1. Parse the `## E2E Journey` block from the story file.
+2. Execute each step in order.
+3. Collect artifacts (screenshots, traces, logs) at `docs/flow/artifacts/<story_id>/`.
+4. Return:
+   - `passed` — array of step names that passed
+   - `failed` — array of `{ step, error, artifact_path }` for failures
+   - `artifacts` — list of generated file paths
+
+### `smoke_test(base_url) → ok | { error, artifact_path }`
+
+Quick sanity check: load base_url, verify no console errors, no 5xx. Returns `ok` if reachable.
+
+## Optional operations
+
+### `screenshot_diff(baseline_path, current_path) → { diff_pct, diff_image_path }`
+
+Visual regression — optional but recommended for UI-heavy stories.
+
+## Journey block format
+
+```markdown
+## E2E Journey
+
+- navigate /
+- assert visible "Welcome"
+- click "Get started"
+- assert url ends with /signup
+- fill input[name=email] = "test@example.com"
+- click "Continue"
+- assert visible "Check your inbox"
+- screenshot success
+```
+
+Each line is one step. Verbs supported per adapter — see each adapter's docstring. Indentation tolerant. Comments start with `#`.

package/adapters/e2e/none.md

@@ -0,0 +1,15 @@
+# No E2E adapter
+
+E2E phase is skipped entirely. Stories may still have `## E2E Journey` blocks for documentation, but Flow does not execute them.
+
+## run_journey(story_file, base_url)
+
+Returns `{ passed: [], failed: [], artifacts: [], skipped: true }`.
+
+## smoke_test(base_url)
+
+Returns `ok`.
+
+## screenshot_diff(baseline_path, current_path)
+
+Returns `{ skipped: true }`.

package/adapters/e2e/playwright-mcp.md

@@ -0,0 +1,86 @@
+# Playwright MCP adapter
+
+Uses the Playwright MCP server. Runs an interactive browser session, executes journey steps, captures artifacts.
+
+**MCP namespace:** `mcp__playwright__*` (exact prefix depends on how the MCP is registered — `mcp__plugin_playwright__*` if installed as a plugin).
+
+**Dependencies:**
+- Playwright MCP server installed (`claude mcp list | grep playwright`)
+- `@playwright/test` runtime in the project (`pnpm add -D @playwright/test`)
+- A browser binary installed (`npx playwright install chromium`)
+
+**Config keys** (`flow.config.yaml > integrations.e2e`):
+- `base_url` — required, e.g. `http://localhost:4321`
+- `journeys_dir` — default `docs/flow/journeys` (for reusable journeys outside stories)
+- `viewport` — optional `{ width, height }`, defaults `{ 1280, 720 }`
+- `start_server_cmd` — optional, e.g. `pnpm dev`. If set, Flow starts the server before journey and stops after.
+
+---
+
+## run_journey(story_file, base_url)
+
+1. **Pre-flight:**
+   - If `start_server_cmd` is set, spawn it in background, wait for `base_url` to respond 200, max 30s.
+   - Parse `## E2E Journey` block from `story_file` into ordered step list.
+
+2. **Browser setup:**
+   - `mcp__playwright__browser_navigate({ url: base_url })`
+   - `mcp__playwright__browser_resize({ width, height })` if viewport configured.
+
+3. **Step execution** — for each step:
+
+   | Step verb | MCP tool |
+   |---|---|
+   | `navigate <path>` | `browser_navigate({ url: base_url + path })` |
+   | `assert visible "<text>"` | `browser_snapshot()` then check accessibility tree for text |
+   | `assert url ends with <path>` | `browser_evaluate({ function: "() => location.pathname" })` |
+   | `click "<text>"` or `click <selector>` | `browser_click({ ref })` (resolve ref from snapshot first) |
+   | `fill <selector> = "<value>"` | `browser_type({ ref, text })` |
+   | `wait <selector>` | `browser_wait_for({ ref })` |
+   | `screenshot <name>` | `browser_take_screenshot({ filename: "<story_id>/<name>.png" })` |
+   | `assert no console errors` | `browser_console_messages()` → filter level=error → assert empty |
+   | `# <comment>` | no-op (just a step label) |
+
+4. **On failure:**
+   - Capture a screenshot of the failure state: `browser_take_screenshot({ filename: "<story_id>/FAIL-<step_name>.png" })`
+   - Record `{ step, error, artifact_path }` in `failed[]`.
+   - Continue running remaining steps unless `--stop-on-failure` flag was set.
+
+5. **Cleanup:**
+   - If `start_server_cmd` was used, kill the spawned process.
+   - `browser_close()`.
+
+6. **Save artifacts:**
+   - All screenshots already saved by MCP under the path passed.
+   - Write a summary at `docs/flow/artifacts/<story_id>/journey-result.json`:
+     ```json
+     {
+       "story_id": "...",
+       "ran_at": "...",
+       "base_url": "...",
+       "passed": [...],
+       "failed": [...],
+       "duration_ms": ...
+     }
+     ```
+
+7. **Return** `{ passed, failed, artifacts }`.
+
+## smoke_test(base_url)
+
+1. `browser_navigate({ url: base_url })`
+2. `browser_console_messages()` → assert no `level: error`
+3. `browser_snapshot()` → assert any visible content (page is not blank)
+4. `browser_close()`
+5. Return `ok` or `{ error, artifact_path }`.
+
+## screenshot_diff(baseline_path, current_path)
+
+Optional — v0.1 returns `{ diff_pct: null, note: "not implemented" }`. v0.2 will use `pixelmatch` or `odiff`.
+
+## Failure handling
+
+- MCP unreachable: halt with `claude mcp list` output and "Run `/flow-init --repair` or `claude mcp add playwright ...`".
+- Server start fails: halt with the start command output.
+- Journey block missing: prompt user to add it, or fall back to `smoke_test`.
+- Step verb unrecognized: halt with the offending line and the supported verbs list above.

package/adapters/issue-tracker/_interface.md

@@ -0,0 +1,46 @@
+# Issue Tracker Adapter Interface
+
+Every issue-tracker adapter MUST implement these operations. flow-story and flow-sprint invoke them by name.
+
+## Required operations
+
+### `create_issue(title, body, labels) → { issue_id, url } | { skipped: true }`
+
+Called by `/flow-sprint add` when a new story is created. Return:
+- `issue_id` — string used as `story.issue` in sprint.yaml
+- `url` — string for user reference
+
+If the adapter is `none`, return `{ skipped: true }` and Flow uses an internal id (`local-001`).
+
+### `transition_to_doing(issue_id) → ok | { error }`
+
+Called by `/flow-sprint next`. Mark the external issue as "in progress" / "started" / whichever the platform calls it.
+
+### `transition_to_review(issue_id, pr_url) → ok | { error }`
+
+Called by `/flow-story` after `/prp-pr` opens a PR. Link the PR to the issue and move to "in review".
+
+### `transition_to_done(issue_id) → ok | { error }`
+
+Called by `/flow-sprint done`. Close the issue.
+
+### `get_state(issue_id) → state_string`
+
+Read-only. Used by `flow doctor` and parity checks. Returns the external platform's state name.
+
+## Optional operations
+
+### `verify_merged(issue_id) → boolean`
+
+Called before `transition_to_done`. Confirm the linked PR is actually merged so we don't close prematurely.
+
+## Config keys
+
+Adapters declare the keys they need in `flow.config.yaml > integrations.issue_tracker.*`. The Flow installer prompts for these at first install or when the adapter is swapped in via `flow adapter swap`.
+
+## Failure handling
+
+If any operation fails:
+- Log the error to `docs/flow/audit-log.md` (if `mode: team`) or to stderr.
+- Do NOT silently swallow — Flow halts and surfaces the error so the user can decide.
+- The adapter SHOULD be retryable: re-running the same op should be idempotent.

package/adapters/issue-tracker/github-issues.md

@@ -0,0 +1,103 @@
+# GitHub Issues adapter
+
+Uses the `gh` CLI (already authenticated via `gh auth login`). No MCP required.
+
+**Config keys** (from `flow.config.yaml > integrations.issue_tracker`):
+- `repo` — `owner/name` (auto-detected by `gh repo view --json nameWithOwner -q .nameWithOwner`)
+- `label_prefix` — optional, defaults to `flow`
+- `default_labels` — optional list, defaults to `["flow"]`
+
+**Dependencies:**
+- `gh` CLI authenticated (`gh auth status` must pass)
+- `git remote get-url origin` resolves to a GitHub repo
+
+---
+
+## create_issue(title, body, labels)
+
+1. Compose label list: `{{config.default_labels}} + labels + ["flow:backlog"]`.
+2. Run:
+   ```bash
+   gh issue create \
+     --repo {{config.repo}} \
+     --title "{{title}}" \
+     --body "{{body}}" \
+     {{ for each label: --label "<label>" }}
+   ```
+3. Parse stdout — last line is the issue URL: `https://github.com/{{repo}}/issues/<N>`.
+4. Extract `N` from the URL → `issue_id` = `#<N>`.
+5. Return `{ issue_id, url }`.
+
+## transition_to_doing(issue_id)
+
+```bash
+gh issue edit {{issue_id_number}} \
+  --repo {{config.repo}} \
+  --remove-label "flow:backlog" \
+  --add-label "flow:in-progress"
+```
+
+## transition_to_review(issue_id, pr_url)
+
+1. Update labels:
+   ```bash
+   gh issue edit {{issue_id_number}} \
+     --remove-label "flow:in-progress" \
+     --add-label "flow:in-review"
+   ```
+2. Post a linking comment:
+   ```bash
+   gh issue comment {{issue_id_number}} \
+     --body "PR opened: {{pr_url}}"
+   ```
+3. Note: GitHub auto-links issues mentioned in PR bodies via `Fixes #N` or `Closes #N`. The PR template in Flow ensures this is included.
+
+## transition_to_done(issue_id)
+
+```bash
+gh issue close {{issue_id_number}} \
+  --repo {{config.repo}} \
+  --reason completed
+```
+
+## verify_merged(issue_id)
+
+1. Find PR linked to this issue:
+   ```bash
+   gh pr list \
+     --search "linked:issue:{{issue_id_number}} is:merged" \
+     --json number,mergedAt \
+     --jq '.[0]'
+   ```
+2. Return truthy if `mergedAt` is not null.
+
+## get_state(issue_id)
+
+```bash
+gh issue view {{issue_id_number}} \
+  --json state,labels \
+  --jq '{state: .state, labels: [.labels[].name]}'
+```
+
+Map labels → Flow state:
+- `flow:backlog`     → `backlog`
+- `flow:in-progress` → `doing`
+- `flow:in-review`   → `review`
+- `state: CLOSED`    → `done` (if `flow` label present)
+
+## Failure handling
+
+- If `gh` is unauthenticated, halt with: "Run `gh auth login` and retry."
+- If repo not detected, prompt user for `repo` config key.
+- `gh issue` operations are idempotent — re-running is safe.
+- Network failures: retry once, then halt.
+
+## Label setup (one-time)
+
+On first use in a repo, Flow creates the label set:
+```bash
+gh label create "flow"            --color "0E8A16" || true
+gh label create "flow:backlog"    --color "BFD4F2" || true
+gh label create "flow:in-progress" --color "FBCA04" || true
+gh label create "flow:in-review"  --color "5319E7" || true
+```

package/adapters/issue-tracker/linear.md

@@ -0,0 +1,65 @@
+# Linear adapter
+
+Uses the Linear MCP server (`@tacticlaunch/mcp-linear`). Requires OAuth auth (browser flow).
+
+**Config keys:**
+- `team_key` — Linear team prefix, e.g. `PLA` (issues become `PLA-42`)
+- `state_map` — optional override for state name → Flow status mapping (defaults below)
+
+**Dependencies:**
+- Linear MCP server installed (`claude mcp list | grep linear`)
+- OAuth completed (`mcp__plugin_linear_linear__list_teams` returns successfully)
+
+---
+
+## create_issue(title, body, labels)
+
+1. Resolve team id:
+   - `mcp__plugin_linear_linear__list_teams` → find team where `key == config.team_key`
+2. Create:
+   - `mcp__plugin_linear_linear__create_issue` with `{ teamId, title, description: body }`
+3. Apply labels:
+   - For each label string, `mcp__plugin_linear_linear__list_issue_labels` and find matching name. If missing, create it. Then add to issue.
+4. Return `{ issue_id: response.identifier, url: response.url }`.
+
+## transition_to_doing(issue_id)
+
+1. `mcp__plugin_linear_linear__list_issue_statuses` for the team
+2. Find state where `type == "started"` AND `name in ["In Progress", "Doing", "Started"]`
+3. `mcp__plugin_linear_linear__update_issue` with `{ id: issue_id, stateId }`
+
+## transition_to_review(issue_id, pr_url)
+
+1. Find state where `name in ["In Review", "Review", "Code Review"]`
+2. `update_issue` with `stateId`
+3. Add comment: `mcp__plugin_linear_linear__create_comment` with `{ issueId, body: "PR opened: " + pr_url }`
+
+## transition_to_done(issue_id)
+
+1. Find state where `type == "completed"` AND `name in ["Done", "Completed", "Closed"]`
+2. `update_issue` with `stateId`
+
+## verify_merged(issue_id)
+
+1. Read issue: `mcp__plugin_linear_linear__get_issue({ id: issue_id })`
+2. Look for attached PR (Linear auto-detects PRs linked via `Fixes` keywords or branch naming `<team_key>-<n>-...`).
+3. Check the PR's merged state via gh CLI: `gh pr view <number> --json mergedAt -q .mergedAt`.
+4. Return truthy if non-null.
+
+## get_state(issue_id)
+
+`mcp__plugin_linear_linear__get_issue` → `.state.name` and `.state.type`.
+
+Map:
+- type `backlog` or `unstarted` → `backlog`
+- type `started` → `doing`
+- type `started` AND name matches "review" → `review`
+- type `completed` → `done`
+- type `canceled` → `cancelled`
+
+## Failure handling
+
+- If MCP unavailable, halt with: "Linear MCP not reachable — run `claude mcp list` to debug, or `/flow-init --repair`."
+- If auth not completed, halt with: "Linear OAuth not done — open Claude Code Settings → MCP → linear → Authenticate."
+- Rate limit: Linear MCP returns 429 — retry with exponential backoff up to 3 times.
+- If team_key not found, halt with the list of available team keys.