benkruger/flow-prime

FLOW Prime — One-Time Project Setup

Usage

/flow:flow-prime
/flow:flow-prime --reprime

Run once after installing FLOW, and again after each FLOW upgrade. Configures workspace permissions, git excludes, installs the bin/* delegation stubs, and writes a version marker so /flow:flow-start knows the project is initialized.

--reprime skips all questions and reuses the existing .flow.json config. Use this for upgrades where you want the same autonomy — just new artifacts installed.

Announce

At the very start, output the following banner in your response (not via Bash) inside a fenced code block:

```text
──────────────────────────────────────────────────
  FLOW v2.6.1 — Prime — STARTING
──────────────────────────────────────────────────
```

Reprime Check

If --reprime was passed:

1. Use the Read tool to read .flow.json from the project root.
   • If the file does not exist, stop with: "No existing config to reprime from. Run /flow:flow-prime instead."
2. Extract skills and role from the JSON. The role field is optional — .flow.json files written before the role-selection step omit it, in which case treat it as unset and omit --role from the setup-script call.
3. Run claude plugin list to check plugin state (needed for Step 4).
4. Skip Steps 1–2 entirely. Jump to Step 3 with the extracted values.

Steps

Step 1 — Choose primary role

The user's primary role sets a default planning persona for future planning conversations. PM users get the Tech Lead voice by default, Tech Lead users get the PM voice, and founder/solo users wear multiple hats — /flow:flow-explore opens with the PM voice and /flow:flow-plan opens with the Tech Lead voice, with the ability to invite the other voice mid-conversation.

<HARD-GATE> You MUST ask the user with AskUserQuestion below and wait for an explicit selection before proceeding. Do NOT infer the answer from context, do NOT default to any option, and do NOT skip the prompt even when reprime appears to already carry a role. The role choice is a user decision per `.claude/rules/skill-authoring.md` "Decision Point Gates".

"What is your primary role? Sets a default planning persona."

• Tech Lead (Recommended) — Engineering lead role
• PM — Product / project management role
• Founder / Solo Dev — Wear multiple hats

</HARD-GATE>

Store the result as role_value:

• "Tech Lead" → "tech-lead"
• "PM" → "pm"
• "Founder / Solo Dev" → "founder-solo"

Step 2 — Choose autonomy level

FLOW has two independent axes for skills that support them:

• Commit — controls per-task review in phase skills (auto = skip review prompts, manual = require explicit approval before each commit).
• Continue — whether to auto-advance to the next phase or prompt first.

Phase skills that commit (code, review, learning) have both axes. Phase skills that don't commit (start) only have continue. Utility skills (complete, abort) have only the continue axis. Every skill's config is an object — {"commit": ..., "continue": ...} for the committing phases, {"continue": ...} for start, complete, and abort.

Ask the user how much autonomy FLOW should have using AskUserQuestion:

"How much autonomy should FLOW have?"

• Fully autonomous — "All skills auto for both commit and continue"
• Fully manual — "All skills manual for both commit and continue"
• Recommended — "Auto where safe, manual where judgment matters (default)"
• Customize — "Choose per skill and axis"

Fully autonomous — all auto:

{"flow-start": {"continue": "auto"}, "flow-code": {"commit": "auto", "continue": "auto"}, "flow-review": {"commit": "auto", "continue": "auto"}, "flow-learn": {"commit": "auto", "continue": "auto"}, "flow-complete": {"continue": "auto"}, "flow-abort": {"continue": "auto"}}

Fully manual — all manual:

{"flow-start": {"continue": "auto"}, "flow-code": {"commit": "manual", "continue": "manual"}, "flow-review": {"commit": "manual", "continue": "manual"}, "flow-learn": {"commit": "manual", "continue": "manual"}, "flow-complete": {"continue": "manual"}, "flow-abort": {"continue": "manual"}}

Recommended — safe defaults:

{"flow-start": {"continue": "auto"}, "flow-code": {"commit": "auto", "continue": "auto"}, "flow-review": {"commit": "auto", "continue": "auto"}, "flow-learn": {"commit": "auto", "continue": "auto"}, "flow-complete": {"continue": "manual"}, "flow-abort": {"continue": "manual"}}

Customize — ask per skill, in this order: code, review, learn, complete, abort.

Start is exempt from the Customize loop because every preset fixes its continue mode to auto — Start has no useful interaction to gate on, so prompting for it would only add friction. Before asking the per-skill questions below, seed skills_dict with {"flow-start": {"continue": "auto"}} so the resulting JSON carries Start's continue mode through to Step 3.

For each remaining skill, ask about only the applicable axes. List the recommended option first with "(Recommended)" in the label:

For code (commit and continue), ask two AskUserQuestions:

First question:

"Commit mode for /flow:flow-code? (controls per-task review before each commit)"

• Auto (Recommended) — "Skip approval prompts"
• Manual — "Require explicit approval"

Second question:

"Continue mode for /flow:flow-code? (controls phase advancement)"

• Auto (Recommended) — "Auto-advance to next phase"
• Manual — "Prompt before advancing"

For review (commit and continue), ask two AskUserQuestions:

First question:

"Commit mode for /flow:flow-review? (controls per-task review before each commit)"

• Auto (Recommended) — "Skip approval prompts"
• Manual — "Require explicit approval"

Second question:

"Continue mode for /flow:flow-review? (controls phase advancement)"

• Auto (Recommended) — "Auto-advance to next phase"
• Manual — "Prompt before advancing"

For learning (commit and continue), ask two AskUserQuestions:

First question:

"Commit mode for /flow:flow-learn? (controls per-task review before each commit)"

• Auto (Recommended) — "Skip approval prompts"
• Manual — "Require explicit approval"

Second question:

"Continue mode for /flow:flow-learn? (controls phase advancement)"

• Auto (Recommended) — "Auto-advance to next phase"
• Manual — "Prompt before advancing"

For complete and abort (continue axis only), ask one AskUserQuestion each:

"Continue mode for /flow:flow-<skill>?"

• Manual (Recommended) — "Require confirmation prompt"
• Auto — "Skip confirmation prompt"

Store each answer as {"continue": "<mode>"} — the same object shape the presets use — so flow-complete and flow-abort carry a continue axis in skills_dict.

Store the result as skills_dict for Step 3.

Step 3 — Run prime setup script

Serialize skills_dict from Step 2 as a JSON string for the --skills-json argument. Pass the concrete role_value from Step 1 via --role.

Do not pass the literal string <role_value> as the flag argument — the role-selection step yielded a concrete value (pm, tech-lead, founder-solo) that goes after --role.

${CLAUDE_PLUGIN_ROOT}/bin/flow prime-setup <project_root> --skills-json '<skills_dict_json>' --role <role_value> --plugin-root ${CLAUDE_PLUGIN_ROOT}

When the Reprime path carries forward a legacy .flow.json that has no role field (written before role selection existed), omit --role entirely:

${CLAUDE_PLUGIN_ROOT}/bin/flow prime-setup <project_root> --skills-json '<skills_dict_json>' --plugin-root ${CLAUDE_PLUGIN_ROOT}

The script handles everything in a single call:

• Reading or creating .claude/settings.json
• Merging FLOW universal permissions (additive only — preserves existing entries)
• Setting defaultMode to acceptEdits (overrides existing values — FLOW requires this for state file writes without prompts)
• Writing .flow.json with version marker, config hash, and skills config
• Adding .flow-states/, .worktrees/, .flow.json, .claude/cost/, .claude/scheduled_tasks.lock, test_adversarial_flow.*, adversarial_flow_test.go, adversarial_flow_test.rb, adversarial_flow_spec.rb, and AdversarialFlowTests.swift to .git/info/exclude
• Installing a pre-commit hook at .git/hooks/pre-commit that blocks direct git commit during active FLOW features and requires commits to go through /flow:flow-commit
• Installing a global flow launcher at ~/.local/bin/flow that delegates to the plugin cache, and warning if ~/.local/bin is not in PATH
• Installing the bin/* delegation stubs (bin/format, bin/lint, bin/build, bin/test) into <project_root>/bin/ from the FLOW asset templates. Pre-existing bin/* scripts are never overwritten — the stubs only fill in the gaps so bin/flow ci always has something to call.

Output JSON: {"status": "ok", "settings_merged": true, "exclude_updated": true, "version_marker": true, "hook_installed": true, "launcher_installed": true, "stubs_installed": ["format", "lint", "build", "test"]}

If the script returns an error, show the message and stop.

.flow.json stores two hashes: config_hash (permission structure) and setup_hash (entire prime_setup.rs file content), both 12-character hex digests. When the plugin version changes, /flow-start recomputes both hashes and compares against stored values. If both match, the version is auto-upgraded. If either mismatches, /flow-prime must be re-run.

After prime, the user is responsible for editing each bin/<tool> to point at their actual toolchain (cargo, pytest, go test, etc.). The default stubs exit 0 with a stderr reminder so a fresh prime never blocks CI.

All universal permissions written to .claude/settings.json for reference:

{
  "permissions": {
    "allow": [
      "Bash(git add *)",
      "Bash(git blame *)",
      "Bash(git branch *)",
      "Bash(git cat-file *)",
      "Bash(git -C *)",
      "Bash(git diff *)",
      "Bash(git fetch *)",
      "Bash(git for-each-ref *)",
      "Bash(git grep *)",
      "Bash(git log *)",
      "Bash(git ls-files *)",
      "Bash(git ls-tree *)",
      "Bash(git merge *)",
      "Bash(git pull *)",
      "Bash(git push)",
      "Bash(git push *)",
      "Bash(git remote *)",
      "Bash(git restore *)",
      "Bash(git rev-list *)",
      "Bash(git rev-parse *)",
      "Bash(git rm *)",
      "Bash(git show *)",
      "Bash(git status)",
      "Bash(git status *)",
      "Bash(git symbolic-ref *)",
      "Bash(git worktree *)",
      "Bash(cd *)",
      "Bash(pwd)",
      "Bash(chmod +x *)",
      "Bash(awk *)",
      "Bash(bash -n *)",
      "Bash(cat *)",
      "Bash(cmp *)",
      "Bash(command -v *)",
      "Bash(cut *)",
      "Bash(date)",
      "Bash(date *)",
      "Bash(diff *)",
      "Bash(file *)",
      "Bash(find *)",
      "Bash(grep *)",
      "Bash(head *)",
      "Bash(id)",
      "Bash(jq *)",
      "Bash(ls *)",
      "Bash(mkdir *)",
      "Bash(mktemp)",
      "Bash(mktemp *)",
      "Bash(psql *)",
      "Bash(rg *)",
      "Bash(sed *)",
      "Bash(shellcheck *)",
      "Bash(sort *)",
      "Bash(stat *)",
      "Bash(tail *)",
      "Bash(test -d *)",
      "Bash(touch *)",
      "Bash(tr *)",
      "Bash(uname *)",
      "Bash(uniq *)",
      "Bash(wc *)",
      "Bash(which *)",
      "Bash(whoami)",
      "Bash(gh pr create *)",
      "Bash(gh pr edit *)",
      "Bash(gh pr close *)",
      "Bash(gh pr list *)",
      "Bash(gh pr view *)",
      "Bash(gh pr merge *)",
      "Bash(gh pr comment *)",
      "Bash(gh pr diff *)",
      "Bash(gh pr ready *)",
      "Bash(gh pr reopen *)",
      "Bash(gh pr review *)",
      "Bash(gh pr status *)",
      "Bash(gh issue *)",
      "Bash(gh label *)",
      "Bash(gh browse *)",
      "Bash(gh search *)",
      "Bash(gh status)",
      "Bash(gh status *)",
      "Bash(gh repo view *)",
      "Bash(gh repo list *)",
      "Bash(gh run list *)",
      "Bash(gh run view *)",
      "Bash(gh run watch *)",
      "Bash(gh workflow list *)",
      "Bash(gh workflow view *)",
      "Bash(gh release list *)",
      "Bash(gh release view *)",
      "Bash(gh release create *)",
      "Bash(gh -C *)",
      "Bash(*bin/flow *)",
      "Bash(bin/test --adversarial-path)",
      "Bash(bin/dependencies)",
      "Bash(rm .flow-*)",
      "Bash(test -f *)",
      "Bash(claude plugin list)",
      "Bash(claude plugin marketplace add *)",
      "Bash(claude plugin install *)",
      "Bash(curl *)",
      "Read(~/.claude/rules/*)",
      "Read(~/.claude/projects/*/memory/*)",
      "Read(//tmp/*.txt)",
      "Read(//tmp/*.diff)",
      "Read(//tmp/*.patch)",
      "Read(//tmp/*.md)",
      "Read(//tmp/*.json)",
      "Read(//tmp/*.jsonl)",
      "Write(//tmp/*.txt)",
      "Write(//tmp/*.diff)",
      "Write(//tmp/*.patch)",
      "Write(//tmp/*.md)",
      "Write(//tmp/*.json)",
      "Write(//tmp/*.jsonl)",
      "Agent(flow:adversarial)",
      "Agent(flow:ci-fixer)",
      "Agent(flow:cto)",
      "Agent(flow:documentation)",
      "Agent(flow:learn-analyst)",
      "Agent(flow:pm)",
      "Agent(flow:pre-mortem)",
      "Agent(flow:reviewer)",
      "Agent(flow:tech-lead)",
      "Skill(decompose:decompose)",
      "Skill(flow:flow-code)",
      "Skill(flow:flow-commit)",
      "Skill(flow:flow-complete)",
      "Skill(flow:flow-config)",
      "Skill(flow:flow-doc-sync)",
      "Skill(flow:flow-explore)",
      "Skill(flow:flow-hygiene)",
      "Skill(flow:flow-issues)",
      "Skill(flow:flow-learn)",
      "Skill(flow:flow-note)",
      "Skill(flow:flow-orchestrate)",
      "Skill(flow:flow-plan)",
      "Skill(flow:flow-review)",
      "Skill(flow:flow-skills)",
      "Skill(flow:flow-start)",
      "Skill(flow:flow-triage-issue)"
    ],
    "deny": [
      "Bash(git rebase *)",
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(git reset *)",
      "Bash(git reset --hard *)",
      "Bash(git stash *)",
      "Bash(git checkout *)",
      "Bash(git clean *)",
      "Bash(git commit *)",
      "Bash(git config *)",
      "Bash(git branch -d *)",
      "Bash(git branch -D *)",
      "Bash(git symbolic-ref HEAD refs/*)",
      "Bash(git -C * checkout *)",
      "Bash(git -C * clean *)",
      "Bash(git -C * commit *)",
      "Bash(git -C * config *)",
      "Bash(git -C * push --force*)",
      "Bash(git -C * push -f*)",
      "Bash(git -C * rebase *)",
      "Bash(git -C * reset *)",
      "Bash(git -C * stash *)",
      "Bash(sed -i*)",
      "Bash(sed * -i*)",
      "Bash(gh pr merge * --admin*)",
      "Bash(gh pr merge --admin*)",
      "Bash(gh * --admin*)",
      "Bash(gh --admin*)",
      "Bash(gh auth login*)",
      "Bash(gh auth logout*)",
      "Bash(gh auth refresh*)",
      "Bash(gh auth setup-git*)",
      "Bash(gh auth switch*)",
      "Bash(gh auth token*)",
      "Bash(gh extension install *)",
      "Bash(gh issue delete *)",
      "Bash(gh issue lock *)",
      "Bash(gh issue transfer *)",
      "Bash(gh issue unlock *)",
      "Bash(gh label clone *)",
      "Bash(gh label delete *)",
      "Bash(gh release delete *)",
      "Bash(gh repo archive *)",
      "Bash(gh repo delete *)",
      "Bash(gh run cancel *)",
      "Bash(gh run delete *)",
      "Bash(gh secret *)",
      "Bash(gh ssh-key *)",
      "Bash(gh variable *)",
      "Bash(cargo *)",
      "Bash(rustc *)",
      "Bash(go *)",
      "Bash(bundle *)",
      "Bash(rubocop *)",
      "Bash(ruby *)",
      "Bash(rails *)",
      "Bash(xcodebuild *)",
      "Bash(xcrun *)",
      "Bash(swift *)",
      "Bash(swiftlint *)",
      "Bash(.venv/bin/*)",
      "Bash(python3 -m pytest *)",
      "Bash(pytest *)",
      "Bash(python *)",
      "Bash(python3 *)",
      "Bash(python3.10 *)",
      "Bash(python3.11 *)",
      "Bash(python3.12 *)",
      "Bash(python3.13 *)",
      "Bash(pip *)",
      "Bash(pip3 *)",
      "Bash(ruff *)",
      "Bash(pyenv *)",
      "Bash(poetry *)",
      "Bash(uv *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(yarn *)",
      "Bash(pnpm *)",
      "Bash(gradle *)",
      "Bash(gradlew *)",
      "Bash(./gradlew *)",
      "Bash(mvn *)",
      "Bash(./mvnw *)",
      "Bash(mix *)",
      "Bash(elixir *)",
      "Bash(dotnet *)",
      "Bash(* && *)",
      "Bash(* ; *)",
      "Bash(* | *)",
      "Bash(bash -c *)",
      "Bash(sh -c *)",
      "Bash(zsh -c *)",
      "Bash(eval *)",
      "Bash(xargs *)",
      "Bash(perl -e *)",
      "Bash(perl -E *)",
      "Bash(python -c *)",
      "Bash(python3 -c *)",
      "Bash(ruby -e *)",
      "Bash(node -e *)",
      "Bash(node -p *)",
      "Bash(nc *)",
      "Bash(tmux send-keys *)",
      "Bash(screen -X *)",
      "Bash(ssh *)",
      "Bash(rtk proxy *)"
    ]
  },
  "defaultMode": "acceptEdits"
}

Step 4 — Install plugins

Run claude plugin list to check the current plugin state.

Decompose plugin (DAG planning):

If the output does not contain decompose-marketplace, add the marketplace source:

claude plugin marketplace add matt-k-wong/mkw-DAG-architect

If the output does not contain decompose, install it:

claude plugin install decompose@decompose-marketplace

If all plugins are already present, skip silently.

Step 5 — Commit generated files

Check if the working tree has changes by running git status. If the output contains "working tree clean", skip to Done.

Otherwise, invoke /flow:flow-commit to commit and push the generated files (.claude/settings.json and any newly-installed bin/<tool> stubs).

Done — Complete

Output the following banner in your response (not via Bash) inside a fenced code block:

```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ FLOW v2.6.1 — Prime — COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Report:

• Settings written to .claude/settings.json
• Version marker written to .flow.json (git-excluded)
• Git excludes configured for .flow-states/, .worktrees/, .flow.json, .claude/cost/, .claude/scheduled_tasks.lock, test_adversarial_flow.*, adversarial_flow_test.go, adversarial_flow_test.rb, adversarial_flow_spec.rb, and AdversarialFlowTests.swift
• Pre-commit hook installed — blocks direct git commit, requires /flow:flow-commit
• Global launcher installed at ~/.local/bin/flow — run flow tui from any primed project
• bin/* stubs installed (list whichever names appear in stubs_installed from Step 3); remind the user to edit each one to wire it to their actual toolchain
• Decompose plugin installed (or already present) — DAG planning support from the matt-k-wong/mkw-DAG-architect marketplace
• Generated files committed and pushed

Display the skills configuration as a pipe-delimited markdown table with exactly this format (not a bullet list):

| Skill     | Commit | Continue |
|-----------|--------|----------|
| start       | —      | auto     |
| code        | auto   | auto     |
| review      | auto   | auto     |
| learning    | auto   | auto     |
| complete    | manual | —        |
| abort       | manual | —        |

Use the actual values from skills_dict (Step 2). The table above is just an example. Show — for axes that don't apply to a skill. The table must use pipe | delimiters — never render as a bullet list.