flow-repair git:20260811.4072310A

Immutable. This exact content is served forever at /api/v1/blob/d1a03f2dca4f8593.

---
name: "flow-repair"
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:

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

## 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 executable helper in `scripts/` (issue #669). Running it
  anyway is harmless and idempotent.