flow-repair ยท diff
git:20260719.bb3a3d6 to git:20260811.dcb91e8
96 added, 5 removed. Audit A to A.
---
name: "flow-repair"
- description: "Install the flow helper family into ~/.claude/scripts/ (fixes exit-127 on marketplace-only installs)"
+ description: "Install the flow helper family into ~/.claude/scripts/"
---
<!-- GENERATED by claude-power-pack - scripts/codex-skill-sync.py; edit .claude/commands/flow/repair.md instead -->
## Codex harness adaptations
Generated from a Claude Code command. Where the procedure references these Claude-only surfaces, adapt as follows:
- - Claude `/plugin` install references: install the codex-power-pack equivalent plugin/skill instead.
- 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
- Install the flow helper family into ~/.claude/scripts/ (fixes exit-127 on marketplace-only installs)
+ Put the flow helper scripts at the stable `~/.claude/scripts/` path the flow
+ commands invoke and the permission allowlist matches.
- ## Full procedure
+ ## Why this exists (issue #590)
- Read `reference.md` in this skill directory for the complete, authoritative procedure before acting on this skill.
+ 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.
+ ```
+
+ ## Notes
+
+ - 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 `scripts/*.sh`. Running it anyway is harmless and idempotent.