dotfiles/pi/.pi/agent/prompts/Doc/chain-commands.md

Chain Commands Reference

This file documents how to invoke the c-* chain recipes defined in ~/.pi/agent/prompts/.

What the chains are

The c-* files are orchestration recipes. They do not contain new prompts; they reuse the existing p-* prompts and run them in sequence through the pi-subagents prompt-workflow adapter. Each step is executed as a forked-context subagent, so later steps can see the outputs from earlier steps.

Available chains

Command file	Sequence	Use it when
c-design-build.md	p-brainstorm → p-plan → p-test → p-commit	You want to design a feature, plan it, add tests, and commit in one go.
c-fix-commit.md	p-summarize → p-diagnose → p-debug → p-test	You need to understand a bug, diagnose it, fix it, and add regression tests.
c-refactor-commit.md	p-refactor → p-test → p-review → p-commit	You want a safe refactor with tests, review, and a commit.
c-security-loop.md	p-secaudit → p-review → p-test	You need a security-first review plus tests before proceeding.

How to run a chain

Chains are not invoked with /c-... in the editor, because normal slash expansion just pastes the file body into the chat. Instead, run them through the pi-subagents adapter with /prompt-workflow:

/prompt-workflow c-design-build "add a rate-limiter to the API"
/prompt-workflow c-fix-commit "the checkout intermittently times out"
/prompt-workflow c-refactor-commit "src/utils.ts"
/prompt-workflow c-security-loop "auth endpoint"

Each chain runs in the foreground by default, so it stays in the current Pi session and you can cancel the current turn with Esc or Ctrl+C.

Add --bg (or --async) to detach the chain and keep working in the main chat while it runs in the background:

/prompt-workflow c-design-build --bg "add a rate-limiter to the API"

Stop or inspect a background run:

/subagents-fleet           # live inspector (Ctrl+Alt+F also opens it)
/subagents-stop <run-id>   # kill a specific run
subagent({ action: "stop", id: "<run-id>" })

Inspect any run (foreground or background):

subagent({ action: "status" })

Ad-hoc chains

You can also run the same sequence on the fly without creating a recipe file:

/chain-prompts p-brainstorm -> p-plan -> p-test -> p-commit -- "add a rate-limiter"
/chain-prompts p-summarize -> p-diagnose -> p-debug -> p-test -- "intermittent timeout"
/chain-prompts p-refactor -> p-test -> p-review -> p-commit -- "src/utils.ts"
/chain-prompts p-secaudit -> p-review -> p-test -- "auth endpoint"

Use --bg or --async to detach an ad-hoc chain:

/chain-prompts p-refactor -> p-test -> p-review -> p-commit --bg -- "src/utils.ts"

Automatic routing

If you don't want to pick the recipe manually, use the workflow-router agent:

/run workflow-router "add a rate-limiter to the API"

The router reads the task, chooses the best c-* chain, and runs it in the foreground (async: false) so you can stop it with Esc/Ctrl+C. It dispatches through the subagent tool using the same p-* prompt bodies the chain recipes use.

You can also invoke it from another agent or prompt:

subagent({ agent: "workflow-router", task: "the checkout intermittently times out" })

Why individual prompts are the subagents

Only the p-*.md files are marked with subagent: true and fork: true. The c-*.md recipe files are pure wrappers. When /prompt-workflow loads a recipe:

1. It sees the chain: frontmatter.
2. It resolves each named step to a p-*.md file.
3. It runs that prompt as a forked-context subagent (delegate by default).
4. The output of each step is passed to the next step via the chain runner.

This keeps the chain recipes small and the individual prompts reusable as both standalone slash templates and chain steps.

Context flow

Because each p-* step uses fork: true, every subagent inherits the parent session history. That means later steps naturally see what earlier steps produced, without needing explicit {previous} placeholders inside the prompt bodies.

The trade-off is higher per-step context usage. If token cost becomes an issue, a future migration could switch the p-* prompts to fresh: true and introduce explicit {previous} handling inside their bodies.

Troubleshooting

Symptom	What to check
/c-design-build just pastes text	Use /prompt-workflow c-design-build ... instead.
Chain step fails with “Unknown prompt workflow”	Run /reload, then /prompt-workflow list and confirm each p-* in the chain appears.
Want the chain to run in background	Add --bg or --async to the /prompt-workflow command.
Steps seem disconnected	fork: true is required on each p-*.md. Check frontmatter.