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

package/catalog.yaml

@@ -0,0 +1,364 @@
+# Flow catalog — the single source of truth for what can be installed.
+# Validated against schemas/catalog.schema.json on every install + in CI.
+#
+# Structure:
+#   flow_components: Flow's own files (skills, adapters, templates)
+#   adapters:        Per-category adapter list (issue-tracker, pr, e2e, verify, notification)
+#   mcps:            MCP server definitions used by adapters
+#   upstreams:       BMad + ECC delegation config (Flow does not own these — calls upstream installers)
+#   profiles:        Named bundles users pick from (mini, standard, team, full)
+
+version: 1
+flow_version_compat: ">=0.0.1 <0.2.0"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# FLOW COMPONENTS — Flow's own files installed via copy-file operations
+# ─────────────────────────────────────────────────────────────────────────────
+flow_components:
+
+  - id: core:flow-skills
+    family: core
+    description: "The four Flow skills (flow-init, flow-sprint, flow-story, flow-doctor)"
+    required: true
+    operations:
+      - copy: { from: "skills/flow-init",   to: "$HOME/.claude/skills/flow-init"   }
+      - copy: { from: "skills/flow-sprint", to: "$HOME/.claude/skills/flow-sprint" }
+      - copy: { from: "skills/flow-story",  to: "$HOME/.claude/skills/flow-story"  }
+      - copy: { from: "skills/flow-doctor", to: "$HOME/.claude/skills/flow-doctor" }
+
+  - id: core:flow-templates
+    family: core
+    description: "Project-level templates: story.md, sprint.yaml, retro.md, flow.config.yaml, pr.md"
+    required: true
+    operations:
+      - copy: { from: "templates", to: "$HOME/.claude/skills/flow-init/templates" }
+
+  - id: core:flow-state-store
+    family: core
+    description: "Install-state machinery — initializes $HOME/.claude/flow/install-state.json"
+    required: true
+    operations:
+      - ensure_dir: "$HOME/.claude/flow"
+      - touch:      "$HOME/.claude/flow/install-state.json"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ADAPTERS — pluggable integrations selected per project in flow.config.yaml
+# ─────────────────────────────────────────────────────────────────────────────
+adapters:
+
+  # Issue tracker ────────────────────────────────────────────────────────────
+  - id: adapter:issue-tracker-linear
+    family: issue-tracker
+    description: "Linear issues via MCP — create, transition, close"
+    needs_mcp: [linear]
+    config_keys:
+      - { name: integrations.issue_tracker.team_key, example: "PLA", required: true }
+    operations:
+      - copy: { from: "adapters/issue-tracker/linear.md", to: "$HOME/.claude/skills/flow-story/adapters/issue-tracker/linear.md" }
+
+  - id: adapter:issue-tracker-github-issues
+    family: issue-tracker
+    description: "GitHub Issues via gh CLI"
+    needs_cli: [gh]
+    config_keys:
+      - { name: integrations.issue_tracker.repo, example: "ghaith/focal", auto_detect: "gh repo view --json nameWithOwner -q .nameWithOwner" }
+    operations:
+      - copy: { from: "adapters/issue-tracker/github-issues.md", to: "$HOME/.claude/skills/flow-story/adapters/issue-tracker/github-issues.md" }
+
+  - id: adapter:issue-tracker-none
+    family: issue-tracker
+    description: "No external issue tracker — sprint.yaml is the source of truth"
+    operations:
+      - copy: { from: "adapters/issue-tracker/none.md", to: "$HOME/.claude/skills/flow-story/adapters/issue-tracker/none.md" }
+
+  # PR platform ──────────────────────────────────────────────────────────────
+  - id: adapter:pr-github
+    family: pr
+    description: "GitHub PRs via gh CLI"
+    needs_cli: [gh]
+    operations:
+      - copy: { from: "adapters/pr/github.md", to: "$HOME/.claude/skills/flow-story/adapters/pr/github.md" }
+
+  - id: adapter:pr-none
+    family: pr
+    description: "No PR platform — commits go straight to main"
+    operations:
+      - copy: { from: "adapters/pr/none.md", to: "$HOME/.claude/skills/flow-story/adapters/pr/none.md" }
+
+  # E2E ──────────────────────────────────────────────────────────────────────
+  - id: adapter:e2e-playwright-mcp
+    family: e2e
+    description: "Headless browser journey via Playwright MCP"
+    needs_mcp: [playwright]
+    config_keys:
+      - { name: integrations.e2e.base_url, example: "http://localhost:3000" }
+      - { name: integrations.e2e.journeys_dir, default: "docs/flow/journeys" }
+    runtime_deps:
+      - { pkg_manager: "auto", install_cmd: "add -D @playwright/test", post_install: "npx playwright install chromium" }
+    operations:
+      - copy: { from: "adapters/e2e/playwright-mcp.md", to: "$HOME/.claude/skills/flow-story/adapters/e2e/playwright-mcp.md" }
+
+  - id: adapter:e2e-none
+    family: e2e
+    description: "No E2E adapter — Flow skips the E2E phase"
+    operations:
+      - copy: { from: "adapters/e2e/none.md", to: "$HOME/.claude/skills/flow-story/adapters/e2e/none.md" }
+
+  # Verify ───────────────────────────────────────────────────────────────────
+  - id: adapter:verify-make
+    family: verify
+    description: "Runs `make verify` as the project verification gate"
+    needs_cli: [make]
+    detect: "test -f Makefile && grep -q '^verify:' Makefile"
+    operations:
+      - copy: { from: "adapters/verify/make.md", to: "$HOME/.claude/skills/flow-story/adapters/verify/make.md" }
+
+  - id: adapter:verify-pnpm
+    family: verify
+    description: "Runs `pnpm verify` (or another script) as the verification gate"
+    needs_cli: [pnpm]
+    config_keys:
+      - { name: integrations.verify.script, default: "verify" }
+    operations:
+      - copy: { from: "adapters/verify/pnpm.md", to: "$HOME/.claude/skills/flow-story/adapters/verify/pnpm.md" }
+
+  - id: adapter:verify-custom
+    family: verify
+    description: "User-defined shell command as the verification gate"
+    config_keys:
+      - { name: integrations.verify.command, example: "cargo check && cargo test", required: true }
+    operations:
+      - copy: { from: "adapters/verify/custom.md", to: "$HOME/.claude/skills/flow-story/adapters/verify/custom.md" }
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MCP SERVERS
+# ─────────────────────────────────────────────────────────────────────────────
+mcps:
+
+  - id: context7
+    name: "Context7"
+    description: "Up-to-date library/API docs lookup"
+    package: "@upstash/context7-mcp"
+    install_cmd: "claude mcp add context7 npx @upstash/context7-mcp"
+    detect_cmd:  "claude mcp list 2>/dev/null | grep -q '^context7'"
+    scope_default: home
+    auth: none
+
+  - id: playwright
+    name: "Playwright MCP"
+    description: "Headless browser for E2E + UI verification"
+    package: "@playwright/mcp"
+    install_cmd: "claude mcp add playwright npx @playwright/mcp@latest"
+    detect_cmd:  "claude mcp list 2>/dev/null | grep -q '^playwright'"
+    scope_default: project
+    auth: none
+
+  - id: linear
+    name: "Linear MCP"
+    description: "Linear issues — create, transition, query"
+    package: "@tacticlaunch/mcp-linear"
+    install_cmd: "claude mcp add linear npx @tacticlaunch/mcp-linear"
+    detect_cmd:  "claude mcp list 2>/dev/null | grep -q '^linear'"
+    scope_default: home
+    auth: oauth_browser
+    auth_instructions: |
+      After install, restart Claude Code, then run /mcp.
+      Click "linear" → "Authenticate" → grant access in the browser tab.
+
+  - id: github-mcp
+    name: "GitHub MCP (optional)"
+    description: "GitHub repo/PR/issue access via MCP. Optional — gh CLI usually sufficient."
+    package: "@modelcontextprotocol/server-github"
+    install_cmd: "claude mcp add github npx @modelcontextprotocol/server-github"
+    detect_cmd:  "claude mcp list 2>/dev/null | grep -q '^github'"
+    scope_default: home
+    auth: api_token
+    env:
+      - { name: GITHUB_PERSONAL_ACCESS_TOKEN, secret: true, prompt: "GitHub PAT (scopes: repo, read:org):" }
+    optional: true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# UPSTREAMS — delegation config for BMad + ECC
+# ─────────────────────────────────────────────────────────────────────────────
+upstreams:
+
+  bmad:
+    name: "BMad Method"
+    repo: "https://github.com/bmad-code-org/BMAD-METHOD"
+    homepage: "https://bmad-code-org.github.io/BMAD-METHOD/"
+    detect:
+      check_cmd: "test -d _bmad || test -d ~/.claude/bmad"
+      version_path_candidates:
+        - "_bmad/_config/manifest.yaml"
+        - "_bmad/install-manifest.yaml"
+    installer:
+      cmd: "npx bmad-method install"
+      base_args: "--tools claude-code --yes"
+      module_arg: "--modules"
+      config_arg: "--set"
+      directory_arg: "--directory"
+    available_modules: [bmm, cis, bmb, tea, core]
+    curated_subsets:
+      none:
+        description: "Skip BMad entirely"
+        modules: []
+      planning-only:
+        description: "PRD + architecture + epics (no per-story BMad)"
+        modules: [bmm]
+        config: { bmm.skill_set: "planning" }
+      planning-plus-research:
+        description: "Planning + market/domain/technical research"
+        modules: [bmm]
+        config: { bmm.skill_set: "planning-research" }
+      creative-thinking:
+        description: "CIS module — brainstorming, design thinking, storytelling"
+        modules: [cis]
+      test-architecture:
+        description: "TEA module — test design, ATDD, NFR"
+        modules: [tea]
+      full:
+        description: "All BMad modules"
+        modules: [bmm, cis, bmb, tea]
+      passthrough:
+        description: "Run BMad's own interactive installer — Flow doesn't choose"
+        modules: null
+
+  ecc:
+    name: "Everything Claude Code"
+    repo: "https://github.com/affaan-m/everything-claude-code"
+    detect:
+      check_cmd: "test -d ~/.claude/rules/common"
+      version_path: "~/.claude/rules/VERSION"
+      installer_path_candidates:
+        - "~/dev-tools/everything-claude-code/install.sh"
+        - "/usr/local/lib/node_modules/@everything-claude-code/ecc/install.sh"
+    installer:
+      cmd: "{installer_path}"
+      cmd_fallback: "npx @everything-claude-code/ecc install"
+      base_args: "--target claude"
+      profile_arg: "--profile"
+      with_arg: "--with"
+      without_arg: "--without"
+      dry_run_arg: "--dry-run"
+      json_arg: "--json"
+    available_profiles: [minimal, core, developer, security, research, full]
+    curated_subsets:
+      none:
+        description: "Skip ECC — assume already installed or not needed"
+        profile: null
+      flow-essentials:
+        description: "Just what Flow needs: plan + code-review + prp-*"
+        profile: core
+        without: [baseline:hooks]
+      flow-essentials-plus-tdd:
+        description: "Essentials + TDD + test-coverage + E2E"
+        profile: developer
+        without: [baseline:hooks, capability:research]
+      security-heavy:
+        description: "Adds security-reviewer agent + security framework guidance"
+        profile: security
+        without: [baseline:hooks]
+      research-heavy:
+        description: "Adds research APIs + business/voice skills"
+        profile: research
+      use-ecc-default:
+        description: "ECC's own default developer profile, unmodified"
+        profile: developer
+      passthrough:
+        description: "Run ECC's installer with no overrides — ECC chooses"
+        profile: null
+
+  caveman:
+    name: "Caveman"
+    repo: "https://github.com/JuliusBrussee/caveman"
+    description: "Output-compression layer for Claude Code (~46% input, ~75% output token savings). Flow expects Caveman to be active so its outputs stay tight."
+    detect:
+      # Current Caveman installer routes via Claude Code's plugin marketplace —
+      # files land under ~/.claude/plugins/cache/caveman/, NOT the legacy
+      # ~/.claude/skills/caveman/ path. Detection probes both layouts so future
+      # installer changes don't break Flow.
+      check_cmd: "find $HOME/.claude/plugins -path '*caveman*SKILL.md' -print -quit 2>/dev/null | grep -q . || test -f $HOME/.claude/skills/caveman/SKILL.md || test -f $HOME/.claude/hooks/caveman-config.js"
+      hooks_cmd: "ls $HOME/.claude/hooks/caveman-* 2>/dev/null"
+    installer:
+      cmd: "curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash"
+      # Mirror of detect.check_cmd — succeeds for either the plugin-marketplace
+      # layout (current) or the legacy ~/.claude/skills/caveman/ layout (older
+      # installer releases). Verifies "the install landed somewhere we can find".
+      verify_after_cmd: "find $HOME/.claude/plugins -path '*caveman*SKILL.md' -print -quit 2>/dev/null | grep -q . || test -f $HOME/.claude/skills/caveman/SKILL.md || test -f $HOME/.claude/hooks/caveman-config.js"
+      security_note: "Caveman ships only via curl-pipe-bash. Flow will surface this and ask for confirmation unless --yes is passed. To inspect the script before running, set $FLOW_INSPECT_INSTALL_SCRIPTS=1 — Flow will download to /tmp first, pause for review, then execute."
+    available_modes: [lite, full, ultra, wenyan]
+    curated_subsets:
+      none:
+        description: "Skip Caveman — only choose this if you have a specific reason (e.g. you already use a different compression layer)"
+        mode: null
+      lite:
+        description: "Light compression. Most readable. Lower savings (~20%)."
+        mode: lite
+      full:
+        description: "Recommended Flow default. ~46% input / ~75% output savings."
+        mode: full
+      ultra:
+        description: "Maximum compression. Some readability loss in long-form responses."
+        mode: ultra
+      wenyan:
+        description: "Classical Chinese-style ultra-compressed mode. Experimental."
+        mode: wenyan
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PROFILES — named bundles users pick during /flow-init
+# ─────────────────────────────────────────────────────────────────────────────
+profiles:
+
+  minimal:
+    description: "Bare Flow — no upstreams except Caveman compression, no adapters, just sprint.yaml + story files"
+    flow_components:
+      - core:flow-skills
+      - core:flow-templates
+      - core:flow-state-store
+    adapters:
+      - adapter:issue-tracker-none
+      - adapter:pr-none
+      - adapter:e2e-none
+      - adapter:verify-custom
+    mcps: []
+    bmad_subset: none
+    ecc_subset: none
+    caveman_subset: full   # Flow expects Caveman compression — installed by default in every profile
+
+  mini:
+    description: "Solo dev, single repo, GitHub, light review"
+    extends: minimal
+    adapters:
+      - adapter:issue-tracker-github-issues
+      - adapter:pr-github
+      - adapter:verify-make
+    mcps: [context7]
+    bmad_subset: none
+    ecc_subset: flow-essentials
+    caveman_subset: full
+
+  standard:
+    description: "Solo or small team, formal review + PRs, Playwright"
+    extends: mini
+    adapters:
+      - adapter:e2e-playwright-mcp
+    mcps: [context7, playwright]
+    bmad_subset: planning-only
+    ecc_subset: flow-essentials-plus-tdd
+    caveman_subset: full
+
+  team:
+    description: "Small team, Linear-driven sprints, separate-model code review for fresh perspective"
+    extends: standard
+    adapters:
+      - adapter:issue-tracker-linear  # overrides github-issues from mini
+    mcps: [context7, playwright, linear]
+    bmad_subset: full
+    ecc_subset: flow-essentials-plus-tdd
+    caveman_subset: full
+    # Note: review.use_separate_model is set to true in the generated
+    # flow.config.yaml for this profile (spawns one reviewer with a different
+    # model for fresh perspective). The previous `features` block here
+    # advertised multi_repo + audit_log + multi_llm_review — multi_repo and
+    # audit_log had zero implementation (E5-007 strip 2026-05-19), and
+    # multi_llm_review was a renamed duplicate of use_separate_model.

package/docs/adapters.md

@@ -0,0 +1,99 @@
+# Adapters
+
+Flow's per-category adapter system lets you swap integrations without changing any skill code. There are four adapter families today; more land in v0.2.
+
+## Families + v0.1 options
+
+| Family | Picks | What it does |
+|---|---|---|
+| `issue-tracker` | `linear`, `github-issues`, `none` | External issue mirror — create, transition, close issues from `/flow-story` |
+| `pr` | `github`, `none` | Pull-request platform — open + monitor + auto-merge PRs |
+| `e2e` | `playwright-mcp`, `none` | End-to-end test driver — run journeys, capture artifacts |
+| `verify` | `make`, `pnpm`, `custom` | Verify command — typecheck + lint + unit tests in one |
+
+Coming in v0.2: `jira`, `notion`, `plain` (issue-tracker); `gitlab`, `bitbucket` (pr); `cypress` (e2e); `slack`, `discord` (notification — new family).
+
+## Picking adapters
+
+`/flow-init` asks during install. You can also pre-pick via the CLI:
+
+```
+flow init --profile standard \
+  --with adapter:issue-tracker-linear \
+  --without adapter:issue-tracker-github-issues \
+  --yes
+```
+
+Each family allows exactly one active adapter at a time. The catalog enforces this — picking a second adapter for the same family overrides the first.
+
+## Where adapters live
+
+```
+adapters/
+├── issue-tracker/
+│   ├── _interface.md       # the contract every issue-tracker adapter implements
+│   ├── linear.md
+│   ├── github-issues.md
+│   └── none.md
+├── pr/
+│   ├── _interface.md
+│   ├── github.md
+│   └── none.md
+├── e2e/
+│   ├── _interface.md
+│   ├── playwright-mcp.md
+│   └── none.md
+└── verify/
+    ├── _interface.md
+    ├── make.md
+    ├── pnpm.md
+    └── custom.md
+```
+
+Each adapter is a markdown file with sections for each operation in the family's `_interface.md`. `/flow-story` reads the active adapter at each phase and follows its instructions.
+
+## Swapping after install
+
+```
+flow adapter swap pr github-issues   # not yet implemented in v0.7
+```
+
+Or hand-edit `flow.config.yaml`:
+
+```yaml
+adapters:
+  issue_tracker: linear
+  pr: github
+  e2e: playwright-mcp
+  verify: make
+```
+
+Then re-run `/flow-doctor` to verify the new adapter file is symlinked and any new MCPs / CLIs needed are installed.
+
+## Writing a custom adapter
+
+1. Read `adapters/<family>/_interface.md` — that's the contract.
+2. Copy the closest existing adapter (e.g., `pr/github.md`) to `pr/my-platform.md`.
+3. Replace each operation block with your platform's equivalent. Operations are markdown — they describe what `/flow-story` should do, not literal code.
+4. Add a `mcps:` and `requires_cli:` block at the top if your adapter needs external infra.
+5. Register the adapter in `catalog.yaml` under the right family.
+6. Add the catalog entry to your active profile via `--with adapter:pr-my-platform`.
+
+## The `none` adapter
+
+Every family has a `none` adapter. It's not a no-op — it tells `/flow-story` to **not** invoke that phase at all. E.g., `pr-none` means commit the story directly to the current branch without opening a PR. Useful for solo work or for stories that just update docs.
+
+## Adapter inventory
+
+| Adapter | Requires | MCPs | Notes |
+|---|---|---|---|
+| `issue-tracker-linear` | — | `linear` | Needs `LINEAR_API_KEY` in `~/.claude/.env.flow` |
+| `issue-tracker-github-issues` | `gh` CLI | — | Uses `gh issue` commands |
+| `issue-tracker-none` | — | — | Stories live only in `sprint.yaml` |
+| `pr-github` | `gh` CLI | — | Uses `gh pr create / merge --auto` |
+| `pr-none` | — | — | Commits directly to current branch |
+| `e2e-playwright-mcp` | — | `playwright` | Reads `## E2E Journey` blocks from stories |
+| `e2e-none` | — | — | E2E phase is skipped |
+| `verify-make` | `make` | — | Runs `make verify` (you define the target) |
+| `verify-pnpm` | `pnpm` | — | Runs configured script (default `verify`) |
+| `verify-custom` | — | — | Runs the literal command from `integrations.verify.command` |

package/docs/migrate-from-bmad.md

@@ -0,0 +1,95 @@
+# Migrating from BMad
+
+Flow doesn't replace BMad — it sits on top of it and adds a lightweight per-story state layer. If you already have a BMad project with `sprint-status.yaml` and stories under `docs/_bmad-output/`, here's how to move to Flow without losing work.
+
+## What stays the same
+
+- 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
+- `_bmad/_config/manifest.yaml` — Flow records the BMad version for repair
+
+## What changes
+
+- A new `docs/flow/` directory with:
+  - `sprint.yaml` — replaces `sprint-status.yaml`
+  - `stories/` — new per-story stubs (~30 lines each) that link back to the BMad story file as a reference
+  - `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
+
+## Migration
+
+```
+/flow-init --migrate-bmad
+```
+
+This runs `/flow-init` in migration mode. In addition to the normal install flow, it:
+
+1. **Parses `sprint-status.yaml`** — extracts epic IDs, story IDs, status, tags
+2. **Maps statuses** — BMad `draft|approved|in-progress|done` → Flow `backlog|todo|doing|done`
+3. **Writes `docs/flow/sprint.yaml`** — single sprint with the migrated stories
+4. **Generates Flow story stubs** — one per BMad story, with a `references:` pointer to the original BMad markdown
+
+After migration, `/flow-sprint status` should show your full backlog. Run `/flow-story <id>` on the first migrated story and Flow will auto-detect its phase from the existing git/PR state.
+
+## Manual migration
+
+If `--migrate-bmad` fails (usually: malformed `sprint-status.yaml` or non-standard epic IDs), it falls back to "no migration" mode and prints the parse error. Fix the YAML, then re-run:
+
+```
+/flow-init --update --migrate-bmad
+```
+
+Or do it manually:
+
+```yaml
+# docs/flow/sprint.yaml
+version: 1
+sprint:
+  id: S1
+  started: 2026-05-19
+  goal: <copy from BMad PRD>
+epics:
+  - id: E1
+    title: <copy from BMad epic>
+stories:
+  - id: E1-001
+    title: <copy from BMad story>
+    epic: E1
+    status: todo
+    tags: [<copy>]
+    references:
+      - docs/_bmad-output/stories/E1-001-<slug>.md
+```
+
+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:
+
+```
+/bmad-create-story        # writes docs/_bmad-output/stories/E1-002-<slug>.md
+/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.
+
+## Rollback
+
+`docs/flow/` is fully additive. To roll back:
+
+```
+rm -rf docs/flow/ flow.config.yaml
+git checkout sprint-status.yaml   # if Flow wrote a backup
+```
+
+Flow stages a backup at `sprint-status.yaml.flow-backup-<timestamp>` before any migration write, so you can always restore.
+
+## Known gotchas
+
+- **Non-standard epic IDs:** BMad allows `E3-S9b` (sub-stories). Flow's `import-bmad` parser handles this, but other forms (`E1.a`, `Epic-1-Story-1`) need a `--epic-id-pattern` override.
+- **Deferred stories:** BMad's `status: deferred` maps to Flow's `deferred.md` file, not `sprint.yaml`. The migration moves them automatically.
+- **Story branches:** BMad uses `feature/<story-id>`; Flow uses `flow/<story-id>-<slug>`. The migration leaves existing branches alone — only NEW stories under `/flow-story` get the new naming.

package/docs/profiles.md

@@ -0,0 +1,81 @@
+# Profiles
+
+Profiles are named bundles that pick the right adapters + upstream subsets + MCPs for your situation. All three are mode flags on the same skills — there is no different codepath per profile.
+
+## At a glance
+
+| Profile | Best for | Tokens/story | Review | E2E | PR | Issue tracker |
+|---|---|---:|---|---|---|---|
+| `mini` | Solo, one repo, light review | ~20k | `code-review` only | none | GitHub | GitHub Issues |
+| `standard` | Solo/small team, formal review | ~40k | `code-review` + language reviewer + security on risk tags | Playwright MCP | GitHub | GitHub Issues |
+| `team` | Multi-repo, multi-LLM review | ~60k | + adversarial + edge-case + separate-model reviewer | Playwright MCP | GitHub (sibling PRs) | Linear |
+| `minimal` | Bare Flow, no upstreams | <10k | none | none | none | none |
+
+## What each profile changes
+
+### `minimal`
+
+- **Adapters:** `issue-tracker-none`, `pr-none`, `e2e-none`, `verify-custom`
+- **MCPs:** none
+- **BMad subset:** `none`
+- **ECC subset:** `none`
+- **Caveman:** `full`
+
+Just `sprint.yaml` + story files. No upstream integration. Useful when you want Flow's state model without any of the per-story machinery.
+
+### `mini`
+
+Extends `minimal`. Adds:
+
+- **Adapters:** `issue-tracker-github-issues`, `pr-github`, `verify-make`
+- **MCPs:** `context7`
+- **ECC subset:** `flow-essentials` (just `/plan`, `/prp-implement`, `/code-review`, `/update-docs`)
+
+What you get: full per-story orchestration through `/flow-story` with the lightest possible review. No E2E, no language-specific reviewers, no adversarial reviewers.
+
+### `standard`
+
+Extends `mini`. Adds:
+
+- **Adapters:** `e2e-playwright-mcp`
+- **MCPs:** + `playwright`
+- **BMad subset:** `planning-only` (PRD, architecture, epic generation; no per-story BMad re-reads)
+- **ECC subset:** `flow-essentials-plus-tdd` (adds `/tdd` and TDD harness)
+
+What you get: full orchestration + E2E coverage for tagged stories + BMad planning artifacts on demand.
+
+### `team`
+
+Extends `standard`. Adds:
+
+- **Adapters:** overrides `issue-tracker-github-issues` → `issue-tracker-linear`
+- **MCPs:** + `linear`
+- **BMad subset:** `full`
+- **Review:** `use_separate_model: true` — spawns one reviewer with a different model (e.g., Sonnet alongside Opus) for cross-model perspective on tagged-risky stories
+
+What you get: full orchestration + Linear-driven sprint sync + cross-model code review on high-risk stories.
+
+> **What you don't get (despite earlier docs promising it):** multi-repo coordinated sibling PRs and per-adapter-call audit logs. Those were aspirational features in the team-profile description through v0.7.0 with zero implementation behind them. Stripped on 2026-05-19 (sprint story E5-007). Read-only multi-repo awareness (story-id touches N repos → aggregate PR status) is tracked as a deferred backlog item; surface a real use case and we'll design it properly.
+
+## Swapping profiles
+
+```
+/flow-init --update --profile <name>
+```
+
+The installer diffs your current state against the new profile and applies only the deltas: removes obsolete adapter files, installs new ones, updates `flow.config.yaml`, re-registers MCPs.
+
+## Custom adjustments
+
+You don't have to pick a stock profile. Use `--with` / `--without` to layer on top:
+
+```
+flow init --profile mini --with adapter:e2e-playwright-mcp --yes
+flow plan --profile team --without adapter:issue-tracker-linear --json
+```
+
+`flow plan` prints the resolved bundle without executing — useful for previewing what `/flow-init` will install.
+
+## Inheritance
+
+Profiles inherit via the `extends:` key in `catalog.yaml`. The merge rule for adapters is **family override** — `team` says `adapter:issue-tracker-linear`, and that replaces `mini`'s `adapter:issue-tracker-github-issues` because both belong to the `issue-tracker` family. Other lists (MCPs, components) union.