specs

# Codebase feature map: /flow-next:map skill + scout enrichment + prime nudge

## Conversation Evidence

> user (turn — 3-part decomposition): "so this would be a 3 parter perhaps, 1. wrap clawpatch map including the install etc. in a new flow-next:map skill 2. scouts can use the map as additional help for context gathering? agents.md/claude.md perhaps too a short mention of the map 3. prime could suggest using it if a similar map doesn't exist?"

> user (turn — capture command): "capture as fn-50 off main then get back to fn-49"

> earlier in session (paraphrased from clawpatch deep-dive in `~/work/agent-scripts/autoreview-analysis.md` §6.5): clawpatch is openclaw's flagship review-and-patch CLI (669⭐, 99 forks at plan time; v0.4.0 2026-05-22). `clawpatch map` walks the repo via `src/detect.ts` (~61 KB) to produce semantic feature slices across ~20 languages/frameworks. Output persists at `.clawpatch/features/*.json` (Zod-validated, `schemaVersion: 1`). Standalone Node 22+ CLI, MIT, installable via `pnpm add -g clawpatch`.

## Overview

Wrap openclaw/clawpatch's `clawpatch map` CLI in a new `/flow-next:map` skill, enrich `repo-scout` + `context-scout` to read the resulting feature index, and add one soft sub-criterion to `/flow-next:prime` surfacing the map as a discoverability nudge. Opt-in convenience throughout — `flowctl` core never imports or requires clawpatch; scouts remain useful without `.clawpatch/`.

## Goal & Context

flow-next's scouts (`repo-scout`, `context-scout`) currently derive "what's in this codebase" via ad-hoc grep + glob during `/flow-next:plan` and `/flow-next:capture`. When a richer pre-computed feature index exists, scouts can anchor R-IDs and decision-context references to concrete semantic boundaries rather than re-deriving them from raw text.

openclaw/clawpatch already does this work in a battle-tested 20-language mapper. Wrapping it (not porting it) gives flow-next that signal cheaply via a new skill that calls clawpatch CLI through a thin shell-out.

The key constraint: this must remain an **opt-in convenience**, not a flow-next core dependency. Users who don't install clawpatch see no change in behavior; users who do install it get scout enrichment for free.

## Architecture & Data Models

Three independent surfaces, sequenced so Part 1 unlocks Parts 2 and 3:

**Part 1 — `/flow-next:map` skill (foundational):**
- New skill at `plugins/flow-next/skills/flow-next-map/`. Wraps the `clawpatch` CLI via shell-out — mirrors the `/flow-next:resolve-pr`-wraps-`gh` precedent.
- Install detection: `command -v clawpatch` + `clawpatch --version`. When missing, print upstream-canonical install instructions (`pnpm add -g clawpatch`) verbatim and exit cleanly. **No auto-install.** When pnpm is present but `command -v clawpatch` returns empty after install, print PNPM_HOME `bin/` hint (#1 install failure mode per pnpm v11 changes).
- Version-range guard: skill prose carries a single-source `SUPPORTED_CLAWPATCH` range (initial: `>=0.4.0 <0.5.0`). Outside-range invocations emit one-line stderr warning naming expected vs found, degrade to fallback (still parse `features/*.json`, skip CLI-flag-specific paths), never block.
- Init handling: when `.clawpatch/` is absent, run `clawpatch init` first. Write `.clawpatch/.gitignore` skeleton (self-contained — directory-local file so a full deletion of `.clawpatch/` removes both data and ignore rules in one step).
- **Default `clawpatch map` invocation is provider-free** — `--source heuristic` deterministic mapper, zero LLM calls. `--source auto|agent` is passthrough; the skill MUST NOT require a clawpatch provider configured for default invocation. Skill does NOT proxy flow-next's review backend config (rp/codex/copilot/none) — clawpatch's provider matrix is orthogonal.
- Config-state echo: skill prints active `--source` + `CLAWPATCH_PROVIDER` (if set, else "none/heuristic") + flow-next review backend (informational) on entry header.
- Ralph-block: skill exits cleanly under `FLOW_RALPH=1` or `REVIEW_RECEIPT_PATH` — install/init interactive prompts make Ralph compat impossible.

**Part 1b — `flowctl repo-map` reader subcommands:**
- New `flowctl repo-map list / show / since-ref` parse `.clawpatch/features/*.json` and return text + `--json`. State location is native `.clawpatch/`; no duplication into `.flow/`.
- These readers BYPASS the `ensure_flow_exists()` guard — they gate on `.clawpatch/` presence instead, returning `count: 0` cleanly when absent so prime's detection check works without special-casing.
- `schemaVersion: 1` enforced; unknown versions emit one-line stderr diagnostic + skip with clean exit; never abort `list`.

**Part 2 — Scout enrichment + agents.md/CLAUDE.md mention:**
- `repo-scout.md` and `context-scout.md` (under `plugins/flow-next/agents/`) gain a `.clawpatch/features/` read step (via `flowctl repo-map list --json` — centralizes schema check). When `.clawpatch/` absent, fall back to current grep/glob flow. **Scouts must remain useful without the map** — fallback contract is load-bearing.
- Scout output schema gains an optional `features_anchored: [...]` field. **Scouts emit the field; downstream skills (`/flow-next:plan`, `/flow-next:capture`) consume scout output as-is in fn-50.** Explicit downstream field handling is future work, tracked separately — not part of this spec.
- Root `CLAUDE.md` AND `plugins/flow-next/skills/flow-next-setup/templates/{claude-md-snippet,agents-md-snippet}.md` gain a one-paragraph optional-add under "Where to look" describing `/flow-next:map` as a discoverability aid. Setup-template changes propagate to existing user repos via the fn-45.3 byte-compare gate — author with tight byte discipline (gate is byte-for-byte including whitespace).

**Part 3 — Prime sub-criterion (discoverability nudge):**
- `/flow-next:prime` (`plugins/flow-next/skills/flow-next-prime/pillars.md`) adds one sub-criterion under **Pillar 5 (Dev Environment)** as criterion ID **`DE7`**: *"Codebase feature map