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

package/schemas/flow-config.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/mhd-ghaith-abtah/flow/schemas/flow-config.schema.json",
+  "title": "Flow project config",
+  "description": "Per-project configuration written by /flow-init. Intended to be committed (team-share). Per-developer overrides go in flow.config.local.yaml (gitignored, deep-merged on top).",
+  "type": "object",
+  "required": ["version", "mode", "adapters"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "generated": { "type": "string" },
+    "flow_version": { "type": "string" },
+    "mode": { "type": "string", "enum": ["minimal", "mini", "standard", "team"] },
+
+    "sprint_file": { "type": "string" },
+    "stories_dir": { "type": "string" },
+    "journeys_dir": { "type": "string" },
+    "retros_dir": { "type": "string" },
+    "archive_dir": { "type": "string" },
+    "deferred_file": { "type": "string" },
+    "artifacts_dir": { "type": "string" },
+
+    "adapters": {
+      "type": "object",
+      "required": ["issue_tracker", "pr", "e2e", "verify"],
+      "properties": {
+        "issue_tracker": { "type": "string" },
+        "pr": { "type": "string" },
+        "e2e": { "type": "string" },
+        "verify": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "integrations": {
+      "type": "object",
+      "additionalProperties": true
+    },
+
+    "review": {
+      "type": "object",
+      "properties": {
+        "use_separate_model": { "type": "boolean" },
+        "auto_hard_review_tags": { "type": "array", "items": { "type": "string" } },
+        "language_reviewer": { "type": ["string", "null"] },
+        "barrier_timeout_seconds": { "type": "integer", "minimum": 60, "maximum": 7200 }
+      },
+      "additionalProperties": false
+    },
+
+    "implement": {
+      "type": "object",
+      "properties": {
+        "default": { "type": "string" },
+        "use_tdd": { "type": "boolean" },
+        "e2e_auto_trigger_tags": { "type": "array", "items": { "type": "string" } },
+        "docs_auto_trigger": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+
+    "pr": {
+      "type": "object",
+      "properties": {
+        "auto_merge_wait_seconds": { "type": "integer", "minimum": 5, "maximum": 600 }
+      },
+      "additionalProperties": true
+    },
+
+    "secrets": {
+      "type": "object",
+      "properties": {
+        "store": { "type": "string", "enum": ["env_file", "shell", "onepassword"] }
+      },
+      "additionalProperties": true
+    },
+
+    "reference_docs": { "type": "array", "items": { "type": "string" } },
+
+    "upstreams": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/install-state.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/mhd-ghaith-abtah/flow/schemas/install-state.schema.json",
+  "title": "Flow install state",
+  "description": "Records what Flow installed at a given scope (home or project). Used for diffing on /flow-init --update and for /flow-doctor checks.",
+  "type": "object",
+  "required": ["schema_version"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^flow\\.install\\.v[0-9]+$"
+    },
+    "scope": { "type": "string", "enum": ["home", "project"] },
+    "installed_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "flow_version": { "type": "string" },
+    "profile": { "type": "string" },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" },
+          "installed_at": { "type": "string", "format": "date-time" },
+          "paths": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": true
+      }
+    },
+    "adapters": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "installed_at": { "type": "string", "format": "date-time" }
+        }
+      }
+    },
+    "mcps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" },
+          "registered_at": { "type": "string", "format": "date-time" },
+          "scope": { "type": "string", "enum": ["home", "project"] },
+          "auth_pending": { "type": "boolean" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "upstreams": {
+      "type": "object",
+      "properties": {
+        "bmad": { "$ref": "#/definitions/upstream_record" },
+        "ecc":  { "$ref": "#/definitions/upstream_record" },
+        "caveman": { "$ref": "#/definitions/upstream_record" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true,
+
+  "definitions": {
+    "upstream_record": {
+      "type": "object",
+      "properties": {
+        "installed": { "type": "boolean" },
+        "subset": { "type": "string" },
+        "version": { "type": "string" },
+        "installed_at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/skills/flow-doctor/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: flow-doctor
+description: 'Health check for a Flow installation. Verifies catalog, install-state, flow.config.yaml, adapters, MCPs, required CLIs, upstream installers (BMad / ECC / Caveman), and known-bug probes (e.g., caveman-shrink standalone-vs-wrapper). Use when the user runs `/flow-doctor` or `flow doctor`. Read-only by default. With `--fix`, attempts safe auto-repairs (re-register caveman-shrink wrapper, regenerate adapter symlinks, recreate missing state files).'
+argument-hint: '[--mcp <id>] [--fix] [--json] [--verbose]'
+version: 0.0.1
+---
+
+Follow the instructions in ./workflow.md.
+
+Resolves `{repo-root}` the same way `flow-init` does (`$FLOW_REPO_ROOT` env, then walk up from `~/.claude/skills/flow-doctor/`, then CWD). Runs the doctor checklist from `flow-init` step 13 as a standalone, plus extra probes for known bugs (e.g., caveman-shrink mis-registered as standalone instead of wrapping context7).
+
+Exit codes (when invoked from `bin/flow.js doctor`):
+- `0` — all checks pass or only ℹ findings
+- `1` — at least one ⚠ warning
+- `2` — at least one ✗ failure

package/skills/flow-doctor/workflow.md

@@ -0,0 +1,157 @@
+# flow-doctor — health check
+
+<workflow>
+
+<step n="1" goal="Locate the catalog and existing state">
+  <action>Resolve `{{repo_root}}`:
+    - If env `FLOW_REPO_ROOT` is set, use it.
+    - Else if running from `~/.claude/skills/flow-doctor/`, walk up to find a directory containing `catalog.yaml`.
+    - Else if the CWD contains `catalog.yaml`, use the CWD (dev mode).
+    - Else record `catalog: ✗ not found` and continue with reduced checks.
+  </action>
+
+  <action>Read `{{home_state}}` from `$HOME/.claude/flow/install-state.json` if it exists.</action>
+  <action>Read `{{project_state}}` from `$CWD/.claude/flow/install-state.json` if it exists.</action>
+  <action>Read `{{flow_config}}` from `$CWD/flow.config.yaml` if it exists.</action>
+  <action>Parse `--fix`, `--mcp <id>`, `--json`, `--verbose` from args.</action>
+</step>
+
+<step n="2" goal="Catalog + schema integrity">
+  <action>Probe:
+    - `{{repo_root}}/catalog.yaml` exists and parses as YAML → `catalog.parse`
+    - `{{repo_root}}/schemas/catalog.schema.json` exists → `catalog.schema_present`
+    - If schema present, validate catalog against it → `catalog.schema_valid`
+  </action>
+</step>
+
+<step n="3" goal="State integrity">
+  <action>Probe:
+    - `home_state` JSON parses, schema version starts with `flow.install.v` → `state.home_parse`
+    - `project_state` JSON parses, schema version starts with `flow.install.v` → `state.project_parse`
+    - `flow.config.yaml` parses, has at least `profile` + `adapters` keys → `state.config_parse`
+  </action>
+</step>
+
+<step n="4" goal="Adapter wiring">
+  <action>For each adapter referenced in `flow.config.yaml.adapters` (one per family: issue-tracker, pr, e2e, verify):
+    - Verify the adapter file exists at `{{repo_root}}/adapters/<family>/<adapter-id>.md` → `adapter.<family>.file`
+    - Probe `.claude/flow/adapters/<family>.md` or `.claude/flow/adapters/<family>/<adapter-id>.md` (depending on layout):
+      - If it's a symlink → resolve target. Record `adapter.<family>.kind: symlink → <target>`. If target doesn't exist, record `⚠ broken symlink`.
+      - If it's a regular file → record `adapter.<family>.kind: regular_file`. Issue #28: this is the **mixed state** — Flow expects symlinks (so updating the upstream `adapters/<family>/*.md` propagates automatically), but a regular file means someone edited the project-side copy directly. Record `bug.adapter_symlink_drift: ⚠ <family> is a regular file, will not pick up upstream adapter updates` and suggest `flow adapter swap <family> <id>` (forces re-symlink) or accept the divergence intentionally.
+      - If neither exists → record `⚠ adapter file missing` (suggest `flow-init --repair`).
+  </action>
+</step>
+
+<step n="5" goal="MCP reachability">
+  <action>Run `claude mcp list` (capture output; if `claude` CLI missing, record `mcp.cli_present: ✗` and skip).</action>
+  <action>For each MCP recorded in `home_state.mcps` (or `project_state.mcps`), verify it appears in `claude mcp list` output → `mcp.<id>.registered`.</action>
+  <action>If `--mcp <id>` passed, deep-probe only that MCP (attempt a no-op tool call) → `mcp.<id>.responding`.</action>
+</step>
+
+<step n="6" goal="Required CLIs">
+  <action>For each adapter, check its declared CLI deps (from `catalog.yaml.adapters.<family>.<id>.requires_cli`):
+    - `which <cli>` → record presence
+    - If missing, record `cli.<name>: ✗ not in $PATH`
+  </action>
+</step>
+
+<step n="7" goal="Upstream installers">
+  <action>Probe each declared upstream:
+    - **BMad:** `test -d _bmad` OR `test -d docs/_bmad-output` → `upstream.bmad.present`. If present, parse `_bmad/_config/manifest.yaml` for version.
+    - **ECC:** check for `~/.claude/rules/common/` and `~/.claude/skills/<known-ecc-skill>` presence → `upstream.ecc.present`. Read recorded ECC profile from `home_state.upstreams.ecc.profile`.
+    - **Caveman:** check `~/.claude/skills/caveman/` and `~/.claude/skills/caveman-shrink/` → `upstream.caveman.present`.
+  </action>
+</step>
+
+<step n="8" goal="Known-bug probes">
+  <action>**caveman-shrink standalone-vs-wrapper probe** (issue #5): caveman-shrink is an MCP **proxy** — it must be invoked with an upstream command to wrap (e.g., `npx caveman-shrink npx @upstash/context7-mcp@latest`). Registering it standalone (no upstream args) crashes immediately with `-32000` because `index.js` exits at "missing upstream command".
+    - Run `claude mcp get caveman-shrink 2>/dev/null` to fetch the registration. If absent, record `caveman_shrink.registered: ℹ not registered` and skip.
+    - Parse the command line. A correctly-wrapped registration has at least 3 tokens **after** the `caveman-shrink` invocation (e.g., `npx caveman-shrink npx <pkg>` → 2+ tokens after `caveman-shrink`).
+    - A standalone (broken) registration has 0 tokens after `caveman-shrink` and will return `-32000` on first call. Record `bug.caveman_shrink_standalone: ⚠ caveman-shrink registered without upstream — will fail with -32000`.
+    - With `--fix`, re-register by running `{{repo_root}}/tools/fix-caveman-shrink.sh <upstream-name>` (default upstream: `context7`). Script prints the exact `claude mcp remove` + `claude mcp add` commands; user runs them.
+  </action>
+
+  <action>**Severity-label preservation probe** (issue #6):
+    - If `caveman:caveman-review` skill is installed, check whether the most-recent `## Review Notes` blocks in `docs/flow/stories/*.md` retain `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` literal labels.
+    - If recent compressed review notes are missing any severity label, record `bug.severity_labels_stripped: ⚠`.
+  </action>
+
+  <action>**Plan/Verified/Review-Notes loose-match probe** (issue #10):
+    - For each story in `docs/flow/stories/*.md`, run `grep -c '^## Plan$'` (anchored, exact). Compare to `grep -c '^## Plan'` (loose). If counts differ, record `bug.plan_marker_loose: ⚠ <story-id>`.
+  </action>
+
+  <action>**Upstream version-drift probe** (issue #12):
+    - For each upstream (bmad, ecc, caveman): read recorded `version` from `home_state.upstreams.<name>.version`. If absent, record `drift.<name>: ℹ not pinned (install pre-dates pinning)`.
+    - Read currently-installed version (same resolution chain as `/flow-init`: BMad → `_bmad/_config/manifest.yaml`; ECC → `~/.claude/rules/VERSION`; Caveman → `~/.claude/plugins/cache/caveman/caveman/*/package.json`).
+    - If recorded ≠ current AND neither is `unknown@*`, record `drift.<name>: ⚠ pinned <recorded>, installed <current>`. Suggest: `flow-init --update --pin-upstream <name>` to re-pin, or `flow-init --repair --upstream <name>` to reinstall the pinned version.
+  </action>
+
+  <action>**Caveman global-scope probe** (issue #9 + #25):
+    - Caveman's `SessionStart` hook (`~/.claude/hooks/caveman-activate.js`) runs in every Claude Code session, including non-Flow projects. This is by design upstream but can surprise users who only wanted Caveman in Flow projects.
+    - Probe: detect whether the current CWD has `flow.config.yaml`. If NOT (we're outside a Flow project) AND `test -f ~/.claude/.caveman-active` (Caveman is active here), record `info.caveman_global_scope: ℹ Caveman active outside a Flow project (this is upstream default)`.
+    - Suggest in the report: to gate Caveman per-project, either (a) set Caveman's default mode to `off` via `~/.claude/.caveman-mode = off`, then add a per-project `~/.claude/hooks/caveman-config.local.js` that flips it to `full` when `flow.config.yaml` is detected, or (b) file an upstream request with the Caveman project for native project-scope detection. Don't auto-fix — modifying Caveman's hooks affects every session.
+  </action>
+</step>
+
+<step n="9" goal="Render report">
+  <output>━━━ flow doctor ━━━
+
+  Catalog:    {{catalog.parse ? ✓ : ✗}}  ({{catalog.path}})
+  Schemas:    {{catalog.schema_valid ? ✓ : (catalog.schema_present ? ⚠ invalid : ℹ not present)}}
+
+  State:
+    Home:     {{state.home_parse ? ✓ : ✗}}  ({{home_state.path}})
+    Project:  {{state.project_parse ? ✓ : ✗}}  ({{project_state.path}})
+    Config:   {{state.config_parse ? ✓ : ✗}}
+
+  Adapters:
+    {{ for each family: "<family>: <adapter-id> <✓|⚠|✗>" }}
+
+  MCPs:
+    {{ for each mcp: "<id>: <✓ registered|⚠ not responding|✗ missing>" }}
+
+  CLIs:
+    {{ for each cli: "<name>: <✓|✗ not in $PATH>" }}
+
+  Upstreams:
+    BMad:     {{upstream.bmad.present ? ✓ : ℹ not installed}}  {{version}}
+    ECC:      {{upstream.ecc.present ? ✓ : ℹ not installed}}   {{profile}}
+    Caveman:  {{upstream.caveman.present ? ✓ : ℹ not installed}}
+
+  Known-bug probes:
+    {{ for each probe: "<name>: <✓ clean|⚠ flagged: <fix-hint>>" }}
+
+  Summary: {{n_ok}} ✓ · {{n_warn}} ⚠ · {{n_fail}} ✗
+  </output>
+</step>
+
+<step n="10" goal="Auto-repair (only if --fix)">
+  <check if="--fix AND bug.caveman_shrink_standalone == ⚠">
+    <output>🔧 Re-registering caveman-shrink as a wrapper…</output>
+    <action>Invoke `{{repo_root}}/tools/fix-caveman-shrink.sh ${args.shrink_upstream || 'context7'}`. Script prints the `claude mcp remove caveman-shrink` and `claude mcp add ...` commands. Print the exact commands; do NOT auto-run them (modifying MCP registration without user consent is a side-effect on every Claude Code session).</action>
+  </check>
+
+  <check if="--fix AND any adapter.<family>.symlink == ✗">
+    <action>Re-create the missing symlink(s) from `{{repo_root}}/adapters/<family>/<id>.md` → `$CWD/.claude/flow/adapters/<family>.md`.</action>
+  </check>
+
+  <check if="--fix AND state.home_parse == ✗ AND home_state file exists but invalid">
+    <action>Move the broken file to `<path>.broken.<timestamp>`, write a fresh empty state with current schema version, print "Re-run /flow-init to re-populate."</action>
+  </check>
+</step>
+
+</workflow>
+
+---
+
+## Handling failures
+
+- **catalog.yaml missing entirely:** Doctor still runs reduced checks (state + config + MCPs + CLIs) and prints `Run /flow-init` at the bottom.
+- **`claude` CLI missing:** All MCP checks skip with `mcp.cli_present: ✗`. Doctor itself still completes.
+- **`--fix` makes things worse:** Every fix logs to `~/.claude/flow/doctor.log` with a timestamp + before/after. The user can restore the pre-fix state manually from `<path>.broken.<timestamp>` snapshots.
+
+## Exit codes (when invoked via `bin/flow.js doctor`)
+
+- `0` — all ✓ or only ℹ
+- `1` — at least one ⚠
+- `2` — at least one ✗

package/skills/flow-init/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: flow-init
+description: 'Interactive first-time installer for Flow. Detects project shape, asks for profile + adapters + upstream choices, delegates to BMad / ECC installers, configures MCP servers, scaffolds docs/flow/, and writes install-state.json. Use when the user runs `/flow-init`. Idempotent — safe to re-run with --update.'
+argument-hint: '[--profile mini|standard|team] [--update] [--repair] [--dry-run] [--yes] [--catalog-source <path|url>]'
+version: 0.0.1
+---
+
+Follow the instructions in ./workflow.md.
+
+Loads the catalog from `{repo-root}/catalog.yaml` (resolved via `$FLOW_REPO_ROOT` env or by walking up from `~/.claude/skills/flow-init/`). When invoked with `--update` or `--repair`, reads the existing install-state.json and runs in delta mode. Otherwise runs the full first-install flow.