Map

/flow-next:map wraps openclaw/clawpatch’s clawpatch map CLI to produce a semantic feature index (~20 languages, persisted at .clawpatch/features/*.json, Zod-validated schemaVersion: 1).

Opt-in convenience throughout. flowctl core never imports or requires clawpatch; scouts read the index when it exists and fall back to grep/glob when .clawpatch/ is absent. Removing /flow-next:map is one command: rm -rf .clawpatch/ removes both the index and the self-contained .gitignore skeleton — the repo .gitignore is never touched.

When to use it

When you want scouts (repo-scout, context-scout) and /flow-next:prime to anchor R-IDs, Investigation targets, and Decision Context references to concrete codebase regions instead of re-deriving them from raw text. Helpful on larger repos where a pre-computed feature index sharpens the grounding step in /flow-next:plan and /flow-next:capture.

Install prerequisite

clawpatch is a standalone Node 22+ CLI distributed via pnpm:

pnpm add -g clawpatch

The skill detects install via command -v clawpatch. When missing, it prints the install instructions verbatim and exits cleanly — no auto-install (global package installs are user-consent territory). If you’ve installed clawpatch but it isn’t on PATH, the skill prints the PNPM_HOME hint: pnpm stores global binaries under $PNPM_HOME and needs a one-time pnpm setup to wire PATH (then re-source your shell rc).

The skill carries the tested clawpatch version range (SUPPORTED_CLAWPATCH) in its prose; see plugins/flow-next/skills/flow-next-map/SKILL.md for the current pin. Outside-range invocations emit a one-line stderr warning naming expected vs found and continue — degrade, never block.

Default invocation is provider-free

/flow-next:map
# → clawpatch map --source heuristic  (deterministic; zero LLM calls)

The deterministic mapper is the default. --source auto|agent flows through as passthrough for users who have CLAWPATCH_PROVIDER configured — clawpatch’s provider matrix (codex / acpx / claude / cursor / grok / opencode / pi) is orthogonal to Flow-Next’s review backend, and the skill does not proxy between them.

The provider-free heuristic mapper targets conventional layouts — npm bins, Next.js routes, Python packages, Rails / Laravel / Django, Go / Rust services, JVM, .NET, SwiftPM, Phoenix. Repos that don’t match those detectors — CLI tools, plugins, markdown/docs-heavy projects, non-standard monorepos — may map to zero features on the heuristic path, and clawpatch flags the coverage as “weak.” When that happens, /flow-next:map surfaces a note suggesting --source=auto (heuristic first, provider only if weak) or --source=agent (always provider-backed). Those paths need a CLAWPATCH_PROVIDER and spend provider tokens. (Flow-Next’s own repo is one such case: the heuristic mapper finds 0 features; --source=agent via codex produces ~9 well-scoped ones.)

Passthrough flags

After a -- terminator, tokens flow directly to clawpatch map:

/flow-next:map -- --since-ref origin/main
/flow-next:map -- --paths src/
/flow-next:map --source auto -- --since-ref HEAD~5

Word-splitting happens on whitespace before clawpatch sees the tokens. Globs (*, ?) are protected from shell expansion (set -f before parsing) so they reach clawpatch untouched. Complex shell quoting that requires escaping spaces inside a single token is not supported — run clawpatch map directly for those cases.

The feature index is local-per-developer, not committed. When .clawpatch/ is absent on first run, the skill calls clawpatch init and writes a .clawpatch/.gitignore skeleton with:

*
!.gitignore

Everything under .clawpatch/ (project.json, config.json, features/*.json, .cache/, *.log) is git-ignored; only the .gitignore file itself is tracked. Each developer runs /flow-next:map locally; the map is regenerated, never shared via git.

Why local-only by design:

Trade-off	Local-only (default)	Shareable (custom)
PR review noise	None — no map churn in diffs	Every feature-shape change shows up in PRs
Merge conflicts	Zero	Likely on `features/*.json` when two PRs map at different SHAs
Onboarding latency	Map regenerates locally (cheap; `--source heuristic` is filesystem-walk fast)	Scouts get features immediately
Schema-bump churn	Absorbed locally per dev	Bumps land as repo-wide diffs on `clawpatch upgrade`
Couples PR review to mapper drift	No	Yes (small but real, pre-1.0 risk)

clawpatch is pre-1.0 with weekly minor releases; the persisted schema may flip between versions. Local-only insulates the team from that churn. The repo’s own .gitignore is intentionally not modified — rm -rf .clawpatch/ removes both the index and the ignore rules in one step (uninstall promise preserved).

Edit .clawpatch/.gitignore to commit selectively:

# Track the feature index; ignore caches/logs/tmp
.cache/
*.log
*.tmp
patches/*.tmp
!.gitignore

This is not the supported default — flow-next-map won’t regenerate to this shape on next run (the write is idempotent and only fires when the file is absent). Be prepared for merge conflicts and PR-review noise on every clawpatch map re-run. Document the choice in your team’s CLAUDE.md / AGENTS.md so contributors know the map ships in-repo.

Re-run cadence

The feature index ages with the code. Scouts emit a features_anchored.last_mapped timestamp and warn (informational, not blocking) when it looks stale. Re-running /flow-next:map is cheap with --source heuristic. Worth re-running:

After a sizable refactor that moves directory boundaries
After adding a new framework / language to the repo
Periodically (e.g. weekly) on actively-evolving repos

How scouts consume it

repo-scout and context-scout call flowctl repo-map list --json as Step 0 when .clawpatch/ is present. Each emits an optional features_anchored: [...] field carrying the matched feature slices plus last_mapped for staleness awareness. When .clawpatch/ is absent, the field is omitted and scouts use the existing grep/glob path — the fallback contract is load-bearing.

Downstream skills (/flow-next:plan, /flow-next:capture) consume scout output as-is. The field is purely additive scout-level enrichment in this release.

`/flow-next:prime` nudge

/flow-next:prime surfaces /flow-next:map as a discoverability suggestion under Pillar 5 (Dev Environment) via the DE7 sub-criterion. The criterion is informational (mirrors DC7): not scored, not a blocker — repos without a feature map are still agent-ready by every other criterion. When the index is missing, prime adds /flow-next:map to Top Recommendations.

Ralph compatibility

The skill declines to run under autonomous loops (FLOW_RALPH=1 or REVIEW_RECEIPT_PATH set) with exit 2 and a one-line stderr diagnostic naming the trigger variable. The install / init prompt paths require a user at the terminal; Ralph never installs global tools or accepts interactive consent.

Next step

Once the index exists, scouts pick it up automatically. To verify:

flowctl repo-map list --json   # parsed features
flowctl repo-map show --feature <id> --json
flowctl repo-map since-ref origin/main --json

When the index is absent, the same commands return count: 0 cleanly — they bypass the standard .flow/ guard so /flow-next:prime and the scouts can probe for the index without special-casing.

Map