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

package/adapters/issue-tracker/none.md

@@ -0,0 +1,26 @@
+# No issue tracker adapter
+
+All issue-tracker operations are no-ops. sprint.yaml is the source of truth.
+
+Story ids use the internal scheme `E<epic>-<NNN>` (e.g. `E1-001`).
+
+## create_issue(title, body, labels)
+
+Returns `{ skipped: true, issue_id: null, url: null }`. Flow uses the internal story id.
+
+## transition_to_doing(issue_id)
+Returns `ok`.
+
+## transition_to_review(issue_id, pr_url)
+Returns `ok`.
+
+## transition_to_done(issue_id)
+Returns `ok`.
+
+## verify_merged(issue_id)
+
+Returns `true` (no external check). User is responsible for confirming PR is merged before `/flow-sprint done`.
+
+## get_state(issue_id)
+
+Returns the `status` field from sprint.yaml for the matching story.

package/adapters/pr/_interface.md

@@ -0,0 +1,29 @@
+# PR Platform Adapter Interface
+
+Every pr adapter MUST implement these operations.
+
+## Required operations
+
+### `open_pr(title, body, base, head) → { pr_id, pr_number, url }`
+
+Called by `/flow-story` at the commit-pr phase. Open a PR from `head` (current branch) to `base` (default `main`).
+
+### `get_pr_state(pr_id) → { state, mergedAt, reviewDecision }`
+
+- `state` ∈ `{open, closed, merged}`
+- `mergedAt` ISO timestamp or null
+- `reviewDecision` ∈ `{approved, changes_requested, review_required, null}`
+
+### `merge_pr(pr_id, method) → ok | { error }`
+
+Method ∈ `{squash, merge, rebase}`. flow-sprint done uses `squash` by default.
+
+## Optional operations
+
+### `branch_name(story_id, slug) → string`
+
+Convention for branch naming. Default: `flow/<story_id>-<slug>`. Adapters can override (e.g., Linear-style `PLA-42-feature-name`).
+
+### `pr_template(story) → string`
+
+Return the body template for a new PR. Default reads `templates/pr.md.tmpl`. Adapters can substitute platform-specific tokens.

package/adapters/pr/github.md

@@ -0,0 +1,61 @@
+# GitHub PR adapter
+
+Uses `gh` CLI. Same auth as the github-issues adapter.
+
+**Dependencies:** `gh` authenticated; remote `origin` is a GitHub repo.
+
+---
+
+## open_pr(title, body, base, head)
+
+1. Push branch if not pushed: `git push -u origin {{head}}`.
+2. Run:
+   ```bash
+   gh pr create \
+     --title "{{title}}" \
+     --body "$(cat <<'EOF'
+   {{body}}
+   EOF
+   )" \
+     --base "{{base}}" \
+     --head "{{head}}"
+   ```
+3. Parse stdout — last non-empty line is the PR URL.
+4. Extract `pr_number` from URL.
+5. Return `{ pr_id: pr_number, pr_number, url }`.
+
+## get_pr_state(pr_id)
+
+```bash
+gh pr view {{pr_id}} --json state,mergedAt,reviewDecision
+```
+
+Map:
+- `state` from GitHub: `OPEN` → `open`, `CLOSED` (no merge) → `closed`, `MERGED` → `merged`
+- `reviewDecision`: `APPROVED` / `CHANGES_REQUESTED` / `REVIEW_REQUIRED` lowercased
+
+## merge_pr(pr_id, method)
+
+```bash
+gh pr merge {{pr_id}} \
+  --{{method}}                       # --squash | --merge | --rebase
+  --delete-branch \
+  --auto                              # waits for required checks if needed
+```
+
+If `--auto` is rejected (no required checks configured), retry without `--auto`.
+
+## branch_name(story_id, slug)
+
+`flow/{{story_id}}-{{slug}}` (e.g. `flow/E1-001-tokens-base-layout`).
+
+If the active issue-tracker is `linear`, override to `{{issue_id}}-{{story_id}}-{{slug}}` so Linear's auto-link recognition works (`PLA-42-...`).
+
+## pr_template(story)
+
+Reads `{repo_root}/templates/pr.md.tmpl`. Substitutes:
+- `{{story.title}}`
+- `{{story.id}}`
+- `{{issue_ref}}` — `Fixes #N` (github-issues) or `Closes PLA-42` (linear) or empty
+- `{{summary}}` — first sentence of story's `Why`
+- `{{test_plan}}` — rendered from story's ACs (each AC becomes a `- [ ]` line)

package/adapters/pr/none.md

@@ -0,0 +1,32 @@
+# No PR platform adapter
+
+All PR operations are no-ops. Commits go straight to `main` (or whatever the default branch is). Flow uses local branches per story but `flow-sprint done` merges via `git merge --ff-only` instead of opening a PR.
+
+Use when:
+- Solo project with no review needed
+- Internal scripts / experiments
+- Pre-publish prototypes
+
+## open_pr(title, body, base, head)
+
+1. Switch to base: `git checkout {{base}}`.
+2. Merge feature branch fast-forward: `git merge --ff-only {{head}}`.
+3. Push: `git push origin {{base}}`.
+4. Delete local branch: `git branch -d {{head}}`.
+5. Return `{ pr_id: "local-merge", pr_number: null, url: null }`.
+
+## get_pr_state(pr_id)
+
+Returns `{ state: "merged", mergedAt: <ISO timestamp of local merge>, reviewDecision: null }`.
+
+## merge_pr(pr_id, method)
+
+No-op — merge happened at `open_pr` time. Returns `ok`.
+
+## branch_name(story_id, slug)
+
+`flow/{{story_id}}-{{slug}}`. Same as github.
+
+## pr_template(story)
+
+Returns empty string (no body needed).

package/adapters/verify/_interface.md

@@ -0,0 +1,26 @@
+# Verify Adapter Interface
+
+Runs the project's build + test gate. Returns a single pass/fail signal plus the raw output for triage.
+
+## Required operations
+
+### `verify_cmd → string`
+
+Return the shell command Flow should execute as the verification gate. Examples:
+- make adapter: `make verify`
+- pnpm adapter: `pnpm verify` (or whatever script name was configured)
+- custom adapter: user-defined command from config
+
+### `run() → { passed, duration_ms, exit_code, stdout, stderr }`
+
+Execute `verify_cmd`. Capture exit code + output. Stream to terminal so user sees progress.
+
+## Optional operations
+
+### `on_failure(exit_code, stderr) → string`
+
+Return a one-line suggestion for the user (e.g., "Run `/build-fix` to triage the type error").
+
+### `precheck() → ok | { error }`
+
+Sanity check before running verify (e.g., for make adapter: confirm Makefile exists and has a `verify` target).

package/adapters/verify/custom.md

@@ -0,0 +1,27 @@
+# Custom verify adapter
+
+User-defined shell command. Use for non-JS stacks or when verify is a one-off compound command.
+
+**Config:** `integrations.verify.command` — required, free-form shell string. Examples:
+- Go: `go vet ./... && go test ./... && go build ./...`
+- Rust: `cargo check && cargo clippy --all-targets && cargo test`
+- Python: `ruff check . && pytest && mypy .`
+- Mixed monorepo: `make -C web verify && pytest api/`
+
+---
+
+## verify_cmd
+
+`{{config.integrations.verify.command}}`
+
+## precheck
+
+`test -n "{{config.integrations.verify.command}}"` → if empty, halt: "Set `integrations.verify.command` in `flow.config.yaml`."
+
+## run
+
+Execute via Bash. Stream output. Return `{ passed, duration_ms, exit_code, stdout, stderr }`.
+
+## on_failure(exit_code, stderr)
+
+Generic: "Verify command failed. Run directly to see full output: `{{verify_cmd}}`."

package/adapters/verify/make.md

@@ -0,0 +1,30 @@
+# Make verify adapter
+
+Runs `make verify` (or another target). Standard for repos that wrap their build/test/lint in a Makefile.
+
+**Config:** none required. Optional override: `integrations.verify.target` (default `verify`).
+
+**Dependencies:** `make` CLI in `$PATH`; `Makefile` at repo root with the configured target.
+
+---
+
+## verify_cmd
+
+`make {{config.integrations.verify.target || "verify"}}`
+
+## precheck
+
+1. `test -f Makefile` → if false, halt: "No Makefile at repo root. Either create one with a `{{target}}:` target or switch to `flow adapter swap verify pnpm` / `custom`."
+2. `grep -q '^{{target}}:' Makefile` → if false, halt: "Makefile is present but has no `{{target}}:` target."
+
+## run
+
+1. Execute `make {{target}}` via Bash, capturing exit code + streaming output.
+2. Record `duration_ms` from start to finish.
+3. Return `{ passed: exit_code == 0, duration_ms, exit_code, stdout, stderr }`.
+
+## on_failure(exit_code, stderr)
+
+- If stderr contains `error TS` or `Type error`, suggest: "TypeScript errors — try `/build-fix` or run `make typecheck` directly."
+- If stderr contains `eslint`, suggest: "Lint errors — run `make lint --fix` or `pnpm lint --fix`."
+- Otherwise generic: "Verify failed — run `make {{target}}` directly to see full output."

package/adapters/verify/pnpm.md

@@ -0,0 +1,27 @@
+# pnpm verify adapter
+
+Runs a pnpm script (default `verify`). Use when the project doesn't have a Makefile but exposes a verification chain via package.json scripts.
+
+**Config:** `integrations.verify.script` (default `verify`).
+
+**Dependencies:** `pnpm` in `$PATH`; `package.json > scripts > {{script}}` defined.
+
+---
+
+## verify_cmd
+
+`pnpm {{config.integrations.verify.script || "verify"}}`
+
+## precheck
+
+1. `test -f package.json` → if false, halt.
+2. `jq -e '.scripts["{{script}}"]' package.json` → if missing, halt: "No `{{script}}` script in package.json. Add one (typical: `\"verify\": \"pnpm typecheck && pnpm lint && pnpm test\"`) or switch verify adapter."
+
+## run
+
+Execute `pnpm {{script}}` via Bash, stream output, return `{ passed, duration_ms, exit_code, stdout, stderr }`.
+
+## on_failure(exit_code, stderr)
+
+Same suggestion logic as make.md adapter. Plus:
+- If stderr contains `pnpm: command not found`, halt: "Install pnpm: https://pnpm.io/installation."

package/bin/flow.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Flow CLI entry — dispatches to lib/commands/<cmd>.js
+//
+// Detects whether we're running inside a Claude Code session (CLAUDECODE=1 env)
+// or from a terminal. The slash-command path uses the same lib/ functions; this
+// binary is the headless / scriptable / CI path.
+
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import yargsParser from 'yargs-parser';
+import chalk from 'chalk';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+
+const PKG = JSON.parse(readFileSync(resolve(REPO_ROOT, 'package.json'), 'utf-8'));
+
+const USAGE = `${chalk.bold('flow')} — ${PKG.description}
+
+${chalk.bold('Usage:')}
+  flow <command> [options]
+
+${chalk.bold('Commands:')}
+  init                          Interactive first-time setup (same as /flow-init in Claude Code)
+  install                       Non-interactive install with flags
+  plan                          Dry-run: show the resolved install plan
+  status                        What's installed where
+  doctor [--mcp <id>]           Health check
+  add <component-id>            Add a single component
+  remove <component-id>         Remove a single component
+  uninstall                     Remove Flow from this project (or --scope home for global)
+  list-profiles                 List available profiles
+  list-components [--family X]  List available components
+  list-mcps                     List MCP servers Flow tracks
+  mcp <add|remove|reauth> ...   Manage MCP servers
+  adapter <swap|list> ...       Manage active adapters
+  help [command]                Show help
+
+${chalk.bold('Common flags:')}
+  --profile <name>              mini | standard | team | minimal | full
+  --bmad-subset <name>          none | planning-only | planning-plus-research | creative-thinking | test-architecture | full | passthrough
+  --ecc-subset <name>           none | flow-essentials | flow-essentials-plus-tdd | security-heavy | research-heavy | use-ecc-default | passthrough
+  --with <component>            Add a component on top of the profile
+  --without <component>         Remove a component from the profile
+  --scope home|project|both     Install scope (default: both)
+  --dry-run                     Print the plan, don't execute
+  --json                        Machine-readable output
+  --yes                         Skip prompts (for CI)
+  --catalog-source <url|path>   Use an alternate catalog (advanced)
+
+${chalk.bold('Examples:')}
+  flow init                                        # interactive
+  flow install --profile standard --yes            # scripted
+  flow install --profile mini --with adapter:e2e-playwright-mcp --yes
+  flow plan --profile team --json
+  flow status
+  flow doctor
+  flow uninstall --scope project
+
+${chalk.bold('Inside Claude Code (slash commands — hyphenated):')}
+  /flow-init                                  first-time setup (interactive)
+  /flow-sprint <subcommand> [args]            add | next | status | done | retro | ...
+  /flow-story [story-id]                      advance the active story
+
+Version ${PKG.version} · ${chalk.dim(PKG.homepage)}
+`;
+
+const COMMANDS = [
+  'init', 'install', 'plan', 'status', 'doctor', 'add', 'remove', 'uninstall',
+  'list-profiles', 'list-components', 'list-mcps', 'mcp', 'adapter', 'help', 'version', '--version'
+];
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || argv[0] === 'help' || argv[0] === '--help' || argv[0] === '-h') {
+    console.log(USAGE);
+    return 0;
+  }
+
+  if (argv[0] === 'version' || argv[0] === '--version' || argv[0] === '-v') {
+    console.log(PKG.version);
+    return 0;
+  }
+
+  const cmd = argv[0];
+  if (!COMMANDS.includes(cmd)) {
+    console.error(chalk.red(`Unknown command: ${cmd}`));
+    console.error(`Run ${chalk.bold('flow help')} for usage.`);
+    return 1;
+  }
+
+  // Parse remaining args. Note: no global `scope` default — each command sets
+  // its own (install: both; uninstall: project, for safety).
+  const args = yargsParser(argv.slice(1), {
+    string: ['profile', 'bmad-subset', 'ecc-subset', 'with', 'without', 'scope', 'catalog-source', 'mcp', 'family', 'repair-upstream'],
+    boolean: ['dry-run', 'json', 'yes', 'execute', 'remove-stories', 'remove-backups', 'archive-unused', 'migrate-bmad', 'verbose'],
+    array: ['with', 'without'],
+    alias: { y: 'yes' }
+  });
+
+  // Dispatch — each command module exports a default async function(args, ctx)
+  const modulePath = resolve(__dirname, '..', 'lib', 'commands', `${cmd}.js`);
+  if (!existsSync(modulePath)) {
+    console.error(chalk.yellow(`⚠  Command ${chalk.bold(cmd)} not implemented yet (v0.0.1 scaffold).`));
+    console.error(`   File ${chalk.dim(modulePath)} is missing.`);
+    console.error(`   Track progress: https://github.com/mhd-ghaith-abtah/flow/issues`);
+    return 2;
+  }
+
+  try {
+    const mod = await import(modulePath);
+    const ctx = {
+      repoRoot: REPO_ROOT,
+      pkg: PKG,
+      cwd: process.cwd(),
+      home: process.env.HOME,
+      insideClaudeCode: Boolean(process.env.CLAUDECODE || process.env.CLAUDE_CODE),
+    };
+    return await mod.default(args, ctx);
+  } catch (err) {
+    console.error(chalk.red(`✗ ${cmd} failed: ${err.message}`));
+    if (process.env.FLOW_DEBUG) console.error(err.stack);
+    return 1;
+  }
+}
+
+main().then(code => process.exit(code ?? 0));