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

package/docs/quickstart.md

@@ -0,0 +1,82 @@
+# Quickstart
+
+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)
+- Git repo, with `origin` set if you want PRs
+
+## Install
+
+Inside Claude Code, in your project root:
+
+```
+/flow-init
+```
+
+This launches an interactive installer. It will:
+
+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
+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.
+
+## First story
+
+```
+/flow-sprint add "Wire up Stripe webhook handler" --epic E1 --tags payments,auth
+/flow-sprint next
+/flow-story
+```
+
+`/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:**
+
+| 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). |
+| `--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. |
+| `--no-e2e` | Skip the E2E adapter. |
+| `--strict-plan` | Block on plan CONFIRM even with `--auto`. |
+| `--skip-plan` | Treat the story as pre-planned. |
+| `--advise-only` | Print phase + suggested next action; don't execute. |
+
+## 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:
+
+```
+/flow-sprint done E1-001
+```
+
+## End-of-sprint
+
+```
+/flow-sprint retro
+```
+
+Generates `docs/flow/retros/<date>.md` from your last sprint's stories: what shipped, what got deferred, review-finding rollup, verify failure rate.
+
+## Health check
+
+```
+/flow-doctor
+```
+
+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).
+
+## 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

package/lib/catalog.js

@@ -0,0 +1,164 @@
+// lib/catalog.js — load and resolve flow's catalog.yaml.
+//
+// Minimal v0.7 implementation: parse YAML, resolve profile inheritance, expose
+// helpers for `flow plan` and `flow init`. JSON-schema validation lands when
+// schemas/catalog.schema.json is finalized (tracked in task #9).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import Ajv from 'ajv';
+
+/**
+ * @typedef {Object} Profile
+ * @property {string} description
+ * @property {string[]} flow_components
+ * @property {string[]} adapters
+ * @property {string[]} mcps
+ * @property {string} bmad_subset
+ * @property {string} ecc_subset
+ * @property {string} caveman_subset
+ * @property {Object} [features]
+ */
+
+/**
+ * @typedef {Object} Catalog
+ * @property {number} version
+ * @property {string} flow_version_compat
+ * @property {Array<Object>} flow_components
+ * @property {Array<Object>} adapters
+ * @property {Object} [mcps]
+ * @property {Object} [upstreams]
+ * @property {Record<string, RawProfile>} profiles
+ */
+
+/**
+ * @typedef {Object} RawProfile
+ * @property {string} description
+ * @property {string} [extends]
+ * @property {string[]} [flow_components]
+ * @property {string[]} [adapters]
+ * @property {string[]} [mcps]
+ * @property {string} [bmad_subset]
+ * @property {string} [ecc_subset]
+ * @property {string} [caveman_subset]
+ * @property {Object} [features]
+ */
+
+/**
+ * Load and parse catalog.yaml from the given repo root. Validates against
+ * schemas/catalog.schema.json if present (issue #11).
+ * @param {string} repoRoot
+ * @param {Object} [opts]
+ * @param {boolean} [opts.validate=true] - run ajv validation if schema present
+ * @returns {Catalog}
+ */
+export function loadCatalog(repoRoot, opts = {}) {
+  const { validate = true } = opts;
+  const catalogPath = resolve(repoRoot, 'catalog.yaml');
+  const raw = readFileSync(catalogPath, 'utf-8');
+  const catalog = parseYaml(raw);
+
+  if (!catalog || typeof catalog !== 'object') {
+    throw new Error(`catalog.yaml at ${catalogPath} did not parse to an object`);
+  }
+  if (!catalog.profiles || typeof catalog.profiles !== 'object') {
+    throw new Error(`catalog.yaml has no 'profiles' section`);
+  }
+
+  if (validate) {
+    const schemaPath = resolve(repoRoot, 'schemas', 'catalog.schema.json');
+    if (existsSync(schemaPath)) {
+      const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+      const ajv = new Ajv({ allErrors: true, strict: false });
+      const check = ajv.compile(schema);
+      if (!check(catalog)) {
+        const errs = (check.errors || []).map(e => `  ${e.instancePath || '/'}: ${e.message}`).join('\n');
+        throw new Error(`catalog.yaml failed schema validation:\n${errs}`);
+      }
+    }
+  }
+
+  return catalog;
+}
+
+/**
+ * Resolve a profile name to its fully-merged spec (walks `extends:` chain).
+ * Adapter lists override family-by-family (later profile wins per family).
+ * @param {Catalog} catalog
+ * @param {string} profileName
+ * @returns {Profile}
+ */
+export function resolveProfile(catalog, profileName) {
+  const seen = new Set();
+  const chain = [];
+  let cursor = profileName;
+  while (cursor) {
+    if (seen.has(cursor)) {
+      throw new Error(`Profile inheritance cycle detected at '${cursor}'`);
+    }
+    seen.add(cursor);
+    const profile = catalog.profiles[cursor];
+    if (!profile) {
+      throw new Error(`Profile '${cursor}' not found in catalog. Available: ${Object.keys(catalog.profiles).join(', ')}`);
+    }
+    chain.unshift(profile);
+    cursor = profile.extends;
+  }
+
+  // Merge: later entries in the chain override earlier ones. For adapters,
+  // override by family (one adapter per family — later wins).
+  const merged = {
+    description: '',
+    flow_components: [],
+    adapters: [],
+    mcps: [],
+    bmad_subset: 'none',
+    ecc_subset: 'none',
+    caveman_subset: 'full',
+    features: {}
+  };
+
+  for (const layer of chain) {
+    if (layer.description) merged.description = layer.description;
+    if (layer.flow_components) merged.flow_components = uniq([...merged.flow_components, ...layer.flow_components]);
+    if (layer.adapters) merged.adapters = mergeAdapters(merged.adapters, layer.adapters, catalog);
+    if (layer.mcps) merged.mcps = uniq([...merged.mcps, ...layer.mcps]);
+    if (layer.bmad_subset) merged.bmad_subset = layer.bmad_subset;
+    if (layer.ecc_subset) merged.ecc_subset = layer.ecc_subset;
+    if (layer.caveman_subset) merged.caveman_subset = layer.caveman_subset;
+    if (layer.features) merged.features = { ...merged.features, ...layer.features };
+  }
+  return merged;
+}
+
+/**
+ * Adapters are keyed by family — replacing one adapter for a family overrides
+ * any previously-merged adapter for the same family.
+ * @param {string[]} current
+ * @param {string[]} incoming
+ * @param {Catalog} catalog
+ * @returns {string[]}
+ */
+function mergeAdapters(current, incoming, catalog) {
+  const byFamily = new Map();
+  for (const id of [...current, ...incoming]) {
+    const adapter = catalog.adapters.find(a => a.id === id);
+    const family = adapter ? adapter.family : id.split(':')[1]?.split('-')[0] ?? id;
+    byFamily.set(family, id);
+  }
+  return [...byFamily.values()];
+}
+
+function uniq(arr) {
+  return [...new Set(arr)];
+}
+
+/**
+ * List all available profile names.
+ * @param {Catalog} catalog
+ * @returns {string[]}
+ */
+export function listProfiles(catalog) {
+  return Object.keys(catalog.profiles);
+}

package/lib/commands/add.js

@@ -0,0 +1,147 @@
+// lib/commands/add.js — `flow add <component-id>` adds a single component.
+//
+// Most useful for adapter swaps: `flow add adapter:e2e-playwright-mcp` to
+// install the Playwright E2E adapter alongside the existing setup. Updates
+// flow.config.yaml's adapters block too — picking the new adapter as active
+// for its family (replacing the previous one for that family).
+//
+// Refuses without --yes. Refuses if catalog has no such component.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, statSync, readdirSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import chalk from 'chalk';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { loadCatalog } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+
+export default async function add(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  const catalog = loadCatalog(repoRoot);
+  const yes = Boolean(args.yes);
+  const dryRun = Boolean(args['dry-run']);
+
+  // The component id is the first positional. bin/flow.js strips `add` from
+  // argv before passing to yargs-parser, so args._[0] is the component id.
+  const componentId = args._?.[0];
+  if (!componentId) {
+    console.error(chalk.red('✗ Missing component id. Example: flow add adapter:e2e-playwright-mcp'));
+    return 1;
+  }
+
+  // Find it in the catalog. Could be in flow_components or adapters.
+  const adapter = catalog.adapters?.find((a) => a.id === componentId);
+  const component = catalog.flow_components?.find((c) => c.id === componentId);
+  const item = adapter || component;
+  if (!item) {
+    console.error(chalk.red(`✗ Unknown component: ${componentId}`));
+    console.error(`  Available adapters: ${catalog.adapters?.map((a) => a.id).join(', ') || '(none)'}`);
+    return 1;
+  }
+
+  const homeRoot = ctx.home || process.env.HOME;
+  const home = (p) => resolve(p.replace(/\$HOME/g, homeRoot));
+
+  console.log(chalk.bold(`━━━ flow add ${componentId} ━━━`));
+  console.log();
+  console.log(`Description: ${item.description}`);
+  if (adapter) {
+    console.log(`Family:      ${adapter.family}`);
+    if (adapter.needs_mcp?.length) console.log(`Needs MCPs:  ${adapter.needs_mcp.join(', ')}`);
+    if (adapter.needs_cli?.length) console.log(`Needs CLIs:  ${adapter.needs_cli.join(', ')}`);
+  }
+  console.log();
+
+  const operations = [];
+  for (const op of item.operations || []) {
+    if (op.copy) {
+      operations.push({
+        kind: 'copy',
+        from: join(repoRoot, op.copy.from),
+        to: home(op.copy.to),
+      });
+    }
+  }
+
+  console.log(chalk.bold('Operations:'));
+  for (const op of operations) {
+    console.log(`  ${chalk.green('+')} ${op.kind}  ${chalk.dim(`${op.from} → ${op.to}`)}`);
+  }
+  console.log();
+
+  if (dryRun) {
+    console.log(chalk.dim('--dry-run: stopping before execution.'));
+    return 0;
+  }
+
+  if (!yes) {
+    console.log(chalk.yellow('?'), 'Re-run with --yes to execute.');
+    return 0;
+  }
+
+  // Execute file ops.
+  let executed = 0;
+  for (const op of operations) {
+    try {
+      if (!existsSync(op.from)) {
+        throw new Error(`source missing: ${op.from}`);
+      }
+      const isDir = statSync(op.from).isDirectory();
+      if (isDir) {
+        copyDirRecursive(op.from, op.to);
+      } else {
+        mkdirSync(dirname(op.to), { recursive: true });
+        copyFileSync(op.from, op.to);
+      }
+      console.log(`  ${chalk.green('✓')} copy  ${op.to}`);
+      executed++;
+    } catch (err) {
+      console.error(`  ${chalk.red('✗')} ${op.kind} failed: ${err.message}`);
+      return 2;
+    }
+  }
+
+  // If it's an adapter, update flow.config.yaml's adapters block.
+  if (adapter) {
+    const configPath = join(ctx.cwd, 'flow.config.yaml');
+    if (existsSync(configPath)) {
+      const config = parseYaml(readFileSync(configPath, 'utf-8')) || {};
+      config.adapters = config.adapters || {};
+      // The family in catalog is hyphenated (e.g. "issue-tracker"); the config
+      // key is snake_case (e.g. "issue_tracker"). Normalize.
+      const configKey = adapter.family.replace(/-/g, '_');
+      // Strip "adapter:" prefix and the family prefix to get the short id.
+      // e.g. "adapter:issue-tracker-linear" → "linear"
+      const shortId = adapter.id.replace(`adapter:${adapter.family}-`, '');
+      const previous = config.adapters[configKey];
+      config.adapters[configKey] = shortId;
+      writeFileSync(configPath, stringifyYaml(config));
+      console.log();
+      if (previous && previous !== shortId) {
+        console.log(`  ${chalk.cyan('↻')} flow.config.yaml: adapters.${configKey} ${previous} → ${shortId}`);
+      } else {
+        console.log(`  ${chalk.cyan('+')} flow.config.yaml: adapters.${configKey} = ${shortId}`);
+      }
+    } else {
+      console.log();
+      console.log(chalk.yellow('⚠'), `No flow.config.yaml in ${ctx.cwd}. Add this manually:`);
+      console.log(`    adapters.${adapter.family.replace(/-/g, '_')}: ${adapter.id.replace(`adapter:${adapter.family}-`, '')}`);
+    }
+  }
+
+  console.log();
+  console.log(chalk.bold(`Done: ${executed} operations executed.`));
+  return 0;
+}
+
+function copyDirRecursive(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}