109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
# 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`:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/prompt-workflow c-design-build --bg "add a rate-limiter to the API"
|
|
```
|
|
|
|
Stop or inspect a background run:
|
|
|
|
```text
|
|
/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):
|
|
|
|
```text
|
|
subagent({ action: "status" })
|
|
```
|
|
|
|
## Ad-hoc chains
|
|
|
|
You can also run the same sequence on the fly without creating a recipe file:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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. |
|