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