/flow-next-map

name: flow-next-map
description: Wrap `clawpatch map` to produce a semantic feature index of the repo (~20 languages, persisted at `.clawpatch/features/*.json`). Detects install, runs `clawpatch init` when `.clawpatch/` absent, invokes provider-free `clawpatch map --source heuristic` by default; `--source auto|agent` flows through as passthrough. Opt-in enrichment — scouts and prime read the resulting index, but flowctl never depends on clawpatch.
user-invocable: false
allowed-tools: Read, Bash, Grep, Glob, Write, Edit

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

**Read [workflow.md](workflow.md) for full phase-by-phase execution.**

Wrap the upstream [`clawpatch`](https://github.com/openclaw/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 — Phase 5 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 (rp / codex / copilot / 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 Phase 0 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. Workflow Phase 1 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.

Ralph-block (R13) — runs first, before everything else

`/flow-next:map` requires a user at the terminal for the install-prompt and init-prompt branches. Autonomous loops cannot install global npm packages or accept interactive consent. Decline-to-run when Ralph signals are set.

if [[ -n "${REVIEW_RECEIPT_PATH:-}" || "${FLOW_RALPH:-}" == "1" ]]; then
  if [[ -n "${REVIEW_RECEIPT_PATH:-}" ]]; then
    TRIGGER="REVIEW_RECEIPT_PATH"
  else
    TRIGGER="FLOW_RALPH"
  fi
  echo "Error: /flow-next:map declines under Ralph ($TRIGGER set); rerun interactively." >&2
  exit 2
fi

**Decline-to-run only — nothing is written to `$REVIEW_RECEIPT_PATH`.** That file belongs to the upstream review caller; a run that leaves any byte there under Ralph has corrupted an unrelated receipt and broken this. The skill exits at line 1 of the workflow under Ralph; install/init paths are unreachable.

No env-var opt-in. Ralph never installs global tools or accepts interactive consent.

Workflow

Execute the phases in [workflow.md](workflow.md) in order:

0. **Pre-flight + config-state echo (R12)** — one four-line block: clawpatch version + `--source`, `CLAWPATCH_PROVIDER` env (or `"none"`), flow-next review backend (informational only), `.clawpatch/` last-mapped timestamp (or `"absent"`). 1. **Install detection (R1, R11)** — `command -v clawpatch` + `clawpatch --version`. Missing → print `pnpm add -g clawpatch` install instructions verbatim and exit 1. When `pnpm bin -g` exits 0 but `command -v clawpatch` still empty, also print the PNPM_HOME `bin/` hint (run `pnpm setup`, re-source shell rc). **No auto-install.** 2. **Version-range guard (R10)** — parse `clawpatch --version` with `(\d+\.\d+\.\d+)`; compare against `SUPPORTED_CLAWPATCH`. Outside range → one-line stderr warning naming expected vs found and continue (degrade — never block). 3.