# Map

Source: https://flow-next.dev/skills/map/

Wrap clawpatch map for a semantic feature index of the repo - opt-in convenience consumed by scouts.

`/flow-next:map` wraps [openclaw/clawpatch](https://github.com/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`) 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:

```bash
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

```bash
/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`:

```bash
/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.

## Sharing contract: local-only by design

**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
*
!.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).

### Want to share the index across the team?

Edit `.clawpatch/.gitignore` to commit selectively:

```gitignore
# 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` calls `flowctl repo-map list --json` as Step 0 when `.clawpatch/` is present. It 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.

## Worked example

```plaintext
/flow-next:map
```

```text
clawpatch 0.x detected on PATH (version in supported range)
Mapping repository... 18 feature slices indexed
Written: .clawpatch/features/*.json (+ .clawpatch/.gitignore, local-only by default)
Scouts will now anchor R-IDs and Investigation targets to feature slices.
```

The map is an accelerant, not a dependency - every consumer falls back to grep/glob when it is absent.

* Re-run after large refactors; each feature slice carries a `last_mapped` timestamp and downstream skills flag staleness rather than trusting old anchors.
* Keep the index local (the default `.gitignore` skeleton) - committing it buys merge conflicts, not value.
* If `clawpatch` is missing or on Node 20, the skill degrades loudly and nothing else in flow-next breaks - install is always your call.

## Dynamic usage

Recipes that compose with map in the [cookbook](https://flow-next.dev/guides/cookbook/):

* [Integration tricks](https://flow-next.dev/guides/cookbook/#integration-tricks) - the feature index sharpens `repo-scout` output during planning.
* [Skip & lighten](https://flow-next.dev/guides/cookbook/#skip--lighten) - a mapped repo makes light plans safer: scouts find the right anchors even without deep research.

## Next step

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

```bash
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.