flow-repair · diff

git:20260811.4072310 to git:20260915.a02bfed

3 added, 96 removed. Audit A to A.

---

name: "flow-repair"

description: "Install the flow helper family into ~/.claude/scripts/"

---

## Codex harness adaptations

Generated from a Claude Code command. Where the procedure references these Claude-only surfaces, adapt as follows:

- Helper scripts referenced as `scripts/<name>` are bundled under `scripts/` in this skill directory (byte-identical copies from the claude-power-pack checkout); some expect sibling repo resources, so prefer a full checkout when one is available.

# Flow: Repair - Install the Helper Family

- Put the flow helper scripts at the stable `~/.claude/scripts/` path the flow

- commands invoke and the permission allowlist matches.

- ## Why this exists (issue #590)

- The flow commands are only half the product: Step 1 of `/flow-start` and

- `/flow-auto` runs `~/.claude/scripts/flow-start-resolve.sh`, `/flow-merge` runs

- `gh-pr-merge.sh`, and so on. Historically only the repo-local `/cpp:init` /

- `/cpp:update` installer put those there. The retired marketplace lane could

- leave commands without those host helpers, producing exit 127 (#590, #662).

- Legacy caches may still bundle the helper family at

- `${CLAUDE_PLUGIN_ROOT}/scripts/` until they are uninstalled. This command copies

- or links helpers to `~/.claude/scripts/`. That stable path matters:

- the #581 allowlist rules in `templates/claude-settings-permissions.json` match

- `Bash(~/.claude/scripts/flow-start-resolve.sh:*)` and friends, and a versioned

- plugin-cache path would never match them - running the helpers in place would

- trade exit-127 breakage for a permission prompt on every call.

- Run this after cloning CPP. It is idempotent and remains able to repair a legacy

- cache while the #662 migration is in progress.

- ## Instructions

- When the user invokes `/flow-repair`, resolve the installer through this chain

- and run the FIRST one that exists. Invoke it bare, with no arguments (the #581

- invocation discipline: a compound invocation defeats the allowlist prefix rule).

- **1. Already installed** - the normal case for a repeat run:

- ```bash

- ~/.claude/scripts/flow-helpers-install.sh

- ```

- **2. Retired plugin cache** (exit 127 above). This compatibility fallback stays

- until #663 migrates hosts; the plugin root exists only for a cached command:

- ```bash

- ${CLAUDE_PLUGIN_ROOT}/scripts/flow-helpers-install.sh

- ```

- **3. CPP checkout** (exit 127 above - running from the repo itself, where

- `CLAUDE_PLUGIN_ROOT` is unset):

- ```bash

- scripts/flow-helpers-install.sh

- ```

- If all three exit 127, no CPP checkout or usable legacy cache is present. Report

- that a CPP checkout is required; the canonical symlink surface returns in #663.

- The installer prints one line per helper and a verdict:

- - `FLOW_HELPERS: installed` - helpers were placed (or refreshed). Report which.

- - `FLOW_HELPERS: ok` - everything was already current; nothing changed.

- - `FLOW_HELPERS: error` - report the message and stop.

- It picks its own delivery: **symlink** when the source is a CPP checkout, so the

- helpers follow `git pull`; **copy** for a legacy plugin cache, because a symlink

- into a version-stamped cache can dangle when that cache is uninstalled.

- ### Then: check the allowlist

- Installing the helpers fixes exit 127. The zero-prompt lane additionally needs

- the flow allowlist merged into `~/.claude/settings.json`. Report its state:

- ```bash

- jq '.permissions.allow | map(select(startswith("Bash(~/.claude/scripts/"))) | length' ~/.claude/settings.json

- ```

- If the count is 0 (or the file is missing), tell the user the helpers will now

- run but will prompt on each call, and that `/cpp:init` / `/cpp:update` merges the

- rules - or they can copy them from

- `templates/claude-settings-permissions.json` (bundled documentation:

- `templates/claude-settings-permissions.md`).

- ## Report

- ```

- Flow Repair

- Source: retired plugin cache (/home/user/.claude/plugins/cache/cpp/flow/1.0.0) | CPP checkout (~/Projects/claude-power-pack)

- Delivery: copy | symlink

- Installed: 9 helpers to ~/.claude/scripts/ | already current

- Allowlist: 6 rules present | not merged (flow will prompt on each helper call)

- Verify with /flow-doctor.

- ```

+ Install the flow helper family into ~/.claude/scripts/

- ## Notes

+ ## Full procedure

- - Read-only alternative: `/flow-doctor` reports the same helper state without

- changing anything (it calls `flow-helpers-install.sh --check`).

- - This is the only flow command that writes outside the repo. It touches exactly

- `~/.claude/scripts/`, and only the helper family listed in the installer.

- - Clone users do not need this - `/cpp:init` Tier 2 and `/cpp:update` Step 5b

- already link every executable helper in `scripts/` (issue #669). Running it

- anyway is harmless and idempotent.

+ Read `reference.md` in this skill directory for the complete, authoritative procedure before acting on this skill.