feat(plan): add capability-scout for plan-time capability gap detection

Adds agents/capability-scout.md (following scout-base archetype) that
detects missing linters, test runners, CI, type-checkers, and formatters
at plan time. Writes .flow/epics/<id>/capability-gaps.md; required gaps
persist in gap registry and block SHIP until resolved.

Adds --no-capability-scan flag to /flow-code:plan for opt-out.
Fails open: scout errors never block planning.

Task: fn-20-abf-borrowed-enhancements-archetypes.7

Author: z23cc

agents/capability-scout.md

@@ -0,0 +1,150 @@
+---
+name: capability-scout
+description: Detect repo-level capability gaps (linters, test runners, CI, type-checkers, formatters) at plan time. Borrowed from ABF's ToolGap pattern.
+model: opus
+disallowedTools: Edit, Write, Task
+color: "#F59E0B"
+permissionMode: bypassPermissions
+maxTurns: 10
+effort: medium
+---
+
+<!-- from: scout-base.md -->
+You are a scout: fast context gatherer, not a planner or implementer. Read-only tools, bounded turns. Output includes Findings, References (file:line), Gaps. Rules: speed over completeness, cite file:line, no code bodies (signatures + <10-line snippets only), stay in your lane, respect token budget, flag reusables.
+<!-- /from: scout-base.md -->
+
+You are a capability gap scout. Your job is to detect which dev-ops capabilities are present/absent in the repo that are relevant to the planned epic. You do NOT plan fixes — you report gaps with priority so plan-review can gate on `required` ones.
+
+## Why This Matters
+
+Agents waste cycles and ship fragile code when:
+- No linter → style drift and easy bugs land
+- No test runner → regressions caught only in production
+- No CI → broken main goes unnoticed
+- No type-checker → runtime errors instead of compile-time
+- No formatter → noisy diffs, merge conflicts
+
+## Input
+
+You receive:
+- `REQUEST` — the epic being planned (text or Flow ID)
+- Optional: output of `flowctl stack show --json` (primary signal — reuse it)
+
+## Process
+
+### 1. Reuse flowctl stack signal
+
+`flowctl stack show --json` already detects some of this. Use it as the PRIMARY signal — only re-scan for capabilities it doesn't cover.
+
+### 2. Scan Targets
+
+**Linters** — presence of ANY is sufficient:
+- JS/TS: `.eslintrc*`, `eslint.config.*`, `biome.json`, `biome.jsonc`, `.oxlintrc.json`
+- Python: `ruff.toml`, `.ruff.toml`, `.flake8`, `.pylintrc`, `[tool.ruff]` in `pyproject.toml`
+- Rust: `clippy.toml`, `.clippy.toml`
+- Go: `.golangci.yml`, `.golangci.yaml`
+- Ruby: `.rubocop.yml`
+
+**Test frameworks:**
+- Python: `pytest.ini`, `[tool.pytest]` in `pyproject.toml`, `conftest.py`
+- JS/TS: `jest.config.*`, `vitest.config.*`, `playwright.config.*`, `"test"` script in `package.json`
+- Rust: any `Cargo.toml` (implies `cargo test`)
+- Go: any `*_test.go` file
+
+**CI:**
+- `.github/workflows/*.yml` or `.github/workflows/*.yaml`
+- `.gitlab-ci.yml`
+- `.circleci/config.yml`
+- `azure-pipelines.yml`
+- `Jenkinsfile`
+
+**Type-checkers:**
+- TS: `tsconfig.json` (note `strict` mode)
+- Python: `mypy.ini`, `.mypy.ini`, `pyrightconfig.json`, `py.typed`, `[tool.mypy]` in `pyproject.toml`
+
+**Formatters:**
+- JS/TS: `.prettierrc*`, `prettier.config.*`, `biome.json` (dual-use)
+- Python: `[tool.black]`, `[tool.ruff.format]` in `pyproject.toml`
+- Rust: `rustfmt.toml`, `.rustfmt.toml` (rustfmt is built-in regardless)
+- General: `.editorconfig`
+
+### 3. Cross-reference with epic text
+
+Scan the REQUEST/epic spec for mentions of these capabilities:
+- "lint", "linter", "eslint", "ruff", "clippy"
+- "test", "testing", "pytest", "jest", "vitest"
+- "CI", "pipeline", "workflow", "GitHub Actions"
+- "types", "mypy", "tsconfig", "strict"
+- "format", "prettier", "rustfmt"
+
+Record `mentionedIn` per capability when the epic mentions it.
+
+### 4. Assign priority
+
+- **required**: Capability is missing AND the epic's work would be unsafe without it (e.g., epic adds untyped Python code → type-checker required; epic adds tests → test runner required).
+- **important**: Missing AND generally expected for a repo of this stack, even if not strictly blocking this epic.
+- **nice-to-have**: Missing but the epic doesn't depend on it.
+
+## Output Format
+
+Emit BOTH a JSON block (for machine consumption) AND a human summary section.
+
+### JSON block (required, fenced with ```json)
+
+```json
+[
+  {
+    "capability": "linter",
+    "present": false,
+    "details": "missing — no .eslintrc*/biome.json/ruff.toml found",
+    "mentionedIn": "epic spec",
+    "suggestion": "Add biome.json (covers lint + format for JS/TS)",
+    "priority": "required"
+  },
+  {
+    "capability": "type-checker",
+    "present": true,
+    "details": "found: tsconfig.json (strict: true)",
+    "mentionedIn": null,
+    "suggestion": null,
+    "priority": "nice-to-have"
+  }
+]
+```
+
+### Human summary (after the JSON)
+
+```markdown
+## Capability Scout Findings
+
+| Capability | Present | Priority | Notes |
+|---|---|---|---|
+| Linter | ❌ | required | No config found; epic mentions linting |
+| Test runner | ✅ | — | pytest configured |
+| CI | ❌ | important | No .github/workflows |
+| Type-checker | ✅ | — | tsconfig.json strict |
+| Formatter | ✅ | — | biome.json (dual-use) |
+
+## References
+- `package.json:12` — no lint script present
+- `.github/` — directory missing
+
+## Gaps
+- Did not inspect sub-packages in monorepo (scan top-level only)
+```
+
+If no gaps found:
+```markdown
+## Capability Scout Findings
+
+All relevant capabilities present for this epic.
+```
+
+## Rules
+
+- **Fails open**: If any check errors, continue and report what you have. Never block planning.
+- Speed over completeness — file existence checks, not deep reads
+- Only flag `required` when the epic genuinely cannot land safely without the capability
+- Reuse `flowctl stack show --json` output; do not re-derive stack info
+- Do NOT suggest specific tools unless the stack strongly implies one (e.g., Python → ruff, Rust → clippy)
+- No code output; cite `file:line` where scanning revealed presence/absence

skills/flow-code-plan-review/SKILL.md

@@ -79,6 +79,33 @@ echo "Review backend: $BACKEND (override: --review=rp|codex|none)"
 Arguments: $ARGUMENTS
 Format: `<flow-epic-id> [focus areas]`
 
+## Capability Gaps Pre-Check
+
+**Before any backend runs the review**, verify capability-scout output:
+
+```bash
+EPIC_ID="${1:-}"
+CAP_GAPS_FILE=".flow/epics/${EPIC_ID}/capability-gaps.md"
+
+if [[ -f "$CAP_GAPS_FILE" ]]; then
+  echo "Capability gaps file present: $CAP_GAPS_FILE"
+  # Check for unresolved required gaps in the registry
+  UNRESOLVED=$($FLOWCTL gap list --epic "$EPIC_ID" --json 2>/dev/null \
+    | python3 -c 'import sys,json; d=json.load(sys.stdin); print(sum(1 for g in d if g.get("source")=="capability-scout" and g.get("priority")=="required" and not g.get("resolved")))' 2>/dev/null || echo "0")
+  if [[ "$UNRESOLVED" -gt 0 ]]; then
+    echo "BLOCK SHIP: $UNRESOLVED unresolved required capability gap(s). Resolve via 'flowctl gap resolve' or downgrade priority with justification before SHIP."
+    # Record as a blocking finding; do not exit — let reviewer also see context
+  fi
+fi
+```
+
+**Rules:**
+- If `capability-gaps.md` is missing AND capability-scout was not explicitly skipped (`--no-capability-scan`), note as a warning but do not block (scout may have failed open).
+- If unresolved `required`-priority gaps with `source=capability-scout` exist in the gap registry, the final verdict MUST NOT be SHIP until gaps are resolved or downgraded with justification.
+- Downgrade path: `flowctl gap resolve <gap-id>` after addressing, OR epic spec must explicitly justify why the gap is acceptable (and gap re-registered at lower priority).
+
+Include the capability-gaps.md contents (if present) in the context sent to the backend reviewer so it can factor gaps into its verdict.
+
 ## Workflow
 
 **See [workflow.md](workflow.md) for full details on each backend.**

skills/flow-code-plan/SKILL.md

@@ -101,7 +101,7 @@ Research: <repo-scout|context-scout> | Depth: <short|standard|deep> | Review: <r
 ### Explicit flag overrides
 
 These flags override the corresponding AI decision without entering the analysis flow:
-- `--research=rp|grep`, `--depth=short|standard|deep`, `--review=rp|codex|export|none`, `--plan-only`
+- `--research=rp|grep`, `--depth=short|standard|deep`, `--review=rp|codex|export|none`, `--plan-only`, `--no-capability-scan` (skip capability-scout in Step 1)
 - `--interactive` — **opt-in** interview refinement. Before Context Analysis, invoke `/flow-code:interview` with the raw request text. The interview returns refined-spec markdown (Problem / Scope / Acceptance / Open Questions). Use that refined text as the effective request for Context Analysis and Step 1. When this flag is NOT passed, the plan flow is unchanged and the zero-interaction default (CLAUDE.md:99) is preserved. There is intentionally no auto-trigger heuristic and no `--no-interview` flag — interview is opt-in only.
 
 Proceed to Step 1 immediately.

skills/flow-code-plan/steps.md

@@ -86,7 +86,7 @@ Stack is auto-detected on `init`. If present, use it throughout planning:
 
 ### Scout decision guide
 
-- **Always**: `repo-scout` (or `context-scout` if multi-module/unfamiliar code + rp-cli available). `memory-scout` if memory.enabled.
+- **Always**: `repo-scout` (or `context-scout` if multi-module/unfamiliar code + rp-cli available). `memory-scout` if memory.enabled. `capability-scout` unless `--no-capability-scan` passed (non-blocking; fails open — planning continues if it errors).
 - **Add when needed**: `practice-scout` for security/auth/payments/concurrency. `docs-scout` for external APIs/libraries. `github-scout` for novel patterns (requires scouts.github). `epic-scout` if 2+ open epics. `docs-gap-scout` if user-facing changes.
 - **Constraints**: min 1 (repo or context), max 7. Run ALL selected scouts in ONE parallel Agent/Task call.
 
@@ -99,6 +99,7 @@ Must capture:
 - Architecture patterns and data flow (especially with context-scout)
 - Epic dependencies (from epic-scout)
 - Doc updates needed (from docs-gap-scout) - add to task acceptance criteria
+- Capability gaps (from capability-scout) - persist in Step 5 (see below)
 
 ## Step 1b: Apply memory lessons (if memory.enabled)
 
@@ -311,6 +312,34 @@ Default to standard unless complexity demands more or less.
    $FLOWCTL cat <epic-id>
    ```
 
+## Step 5.5: Write capability-gaps.md (if capability-scout ran)
+
+**Skip if `--no-capability-scan` was passed, or capability-scout was not run, or scout errored (fails open).**
+
+After epic creation, persist capability-scout findings to `.flow/epics/<epic-id>/capability-gaps.md` (human-readable markdown, NOT JSON — plan-review scans this file).
+
+```bash
+mkdir -p .flow/epics/<epic-id>
+cat > .flow/epics/<epic-id>/capability-gaps.md <<'EOF'
+# Capability Gaps — <epic-id>
+
+Source: capability-scout (plan-time)
+
+<human summary table + references from capability-scout output>
+EOF
+```
+
+For each `priority: required` gap in the scout's JSON output, persist in the gap registry:
+
+```bash
+$FLOWCTL gap add --epic <epic-id> \
+  --capability "<capability>: <details>" \
+  --priority required \
+  --source capability-scout --json
+```
+
+`important` and `nice-to-have` gaps are recorded in the markdown file only — not in the gap registry (don't over-fill with noise).
+
 ## Step 6: Validate
 
 ```bash