Flow Next Map

/flow-next:map — wrap clawpatch map for a semantic feature index

Read workflow.md for the bundled-script invocation and summary.

Wrap the upstream clawpatch CLI's map subcommand. Default invocation is provider-free (--source heuristic) — zero LLM calls, zero API spend, deterministic mapper. Output lands at .clawpatch/features/*.json (Zod-validated upstream, schemaVersion: 1). Scout enrichment and the /flow-next:prime DE7 nudge read the resulting index; this skill is the install/init/invoke surface.

Role: thin shell-out wrapper. flowctl never imports or requires clawpatch; the skill is the only flow-next surface that touches it.

Preamble

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in workflow.md) use $FLOWCTL:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Inline skill (no context: fork) — the map skill is fully non-interactive: install detection, version-range guard, clawpatch init, .clawpatch/.gitignore skeleton, and clawpatch map invocation all proceed without prompting the user. No blocking-question tool is required or used.

Input

Arguments: $ARGUMENTS

Format: [--source <heuristic|auto|agent>] [-- <extra clawpatch args>]

• Default (no args) → clawpatch map --source heuristic (provider-free, deterministic). Heuristic targets conventional app/framework layouts; unconventional repos (CLI tools, plugins, markdown/docs-heavy, non-standard monorepos) may map to 0 features — The summary surfaces a --source=auto|agent suggestion when that happens.
• --source auto|agent → passthrough to clawpatch; user must have CLAWPATCH_PROVIDER configured for these paths (clawpatch's own concern, not ours).
• -- → terminator; tokens after flow to clawpatch map (e.g. --since-ref origin/main, --paths src/).

Passthrough boundary. The slash-command host delivers $ARGUMENTS as a single string; the skill word-splits on whitespace. Passthrough is therefore token-level (whitespace-separated), not full shell-verbatim — tokens containing literal spaces or shell metacharacters that require shell quoting will not survive. Globs (*, ?) are protected from expansion (set -f before the parse) so they reach clawpatch untouched. Users needing complex quoting should run clawpatch map directly.

flow-next's review backend config (codex / copilot / cursor / claude / host / none) stays out of clawpatch. clawpatch's provider matrix (codex / acpx / claude / cursor / grok / opencode / pi) is orthogonal — a run that sets CLAWPATCH_PROVIDER from the flow-next backend has broken this. The script echo reports the backend as informational only.

Version pin

SUPPORTED_CLAWPATCH=">=0.4.0 <0.5.0"

Single source of truth for the supported clawpatch range. The bundled script parses clawpatch --version with a tolerant (\d+\.\d+\.\d+) regex and compares against this range. Outside-range → warn one line to stderr and degrade (continue). Never block. Re-verify on each clawpatch minor release.

clawpatch is pre-1.0 (v0.4.0, 2026-05-22; weekly minor releases). The README forecasts breaking changes between minor releases — tolerant parsing matters.

Workflow

Invoke the bundled script as workflow.md directs. It handles install detection, the version warning, init, ignore skeleton, streaming map and mechanical counts. The host explains the result and optional next steps.