Successfully replaced 2 block(s) in /home/liph/dotfiles/pi/.pi/agent/prompts/Doc/prompts.md.

    ...
 42 ```
 43
 44 ## Chain recipes
 45
-46 The `c-*` files are not prompts you run directly in the editor. They are orchestration recipes that run a sequence of `p-*` prompts through the `pi-subagents` prompt-workflow adapter. Each `p-*` step is executed as a forked-context subagent, so later steps can see earlier outputs. Chains run asynchronously by default.
+46 The `c-*` files are not prompts you run directly in the editor. They are orchestration recipes that run a sequence of `p-*` prompts through the `pi-subagents` prompt-workflow adapter. Each `p-*` step is executed as a forked-context subagent, so later steps can see earlier outputs. Chains run in the foreground by default (stop with `Esc`/`Ctrl+C`); add `--bg` to detach them.
 47
 48 | Recipe             | Sequence                                  | Use it when…                                                               |
 49 | ------------------ | ----------------------------------------- | -------------------------------------------------------------------------- |
 50 | **`c-design-build`** | `p-brainstorm → p-plan → p-test → p-commit` | You want to design a feature, plan it, add tests, and commit in one go.    |
    ...
 54
 55 Invoke a chain with `/prompt-workflow`, not `/c-recipe`:
 56
 57 ```text
-58 /prompt-workflow c-design-build --bg "add a rate-limiter to the API"
-59 /prompt-workflow c-fix-commit --bg "the checkout intermittently times out"
-60 /prompt-workflow c-refactor-commit --bg "src/utils.ts"
-61 /prompt-workflow c-security-loop --bg "auth endpoint"
+58 /prompt-workflow c-design-build "add a rate-limiter to the API"
+59 /prompt-workflow c-fix-commit "the checkout intermittently times out"
+60 /prompt-workflow c-refactor-commit "src/utils.ts"
+61 /prompt-workflow c-security-loop "auth endpoint"
 62 ```
 63
-64 Each chain runs in the background. Watch it with `/subagents-fleet` or check status with `subagent({ action: "status" })`. If you want to run the same sequence ad-hoc, use `/chain-prompts`:
+64 Add `--bg` to run detached; then watch with `/subagents-fleet`, stop with `/subagents-stop <id>`, or check status with `subagent({ action: "status" })`. To let the agent pick the chain for you, use `/run workflow-router "<task>"`. If you want to run the same sequence ad-hoc, use `/chain-prompts`:
 65
 66 ```text
 67 /chain-prompts p-brainstorm -> p-plan -> p-test -> p-commit -- "add a rate-limiter"
 68 ```
    ...

--- /home/liph/dotfiles/pi/.pi/agent/prompts/Doc/prompts.md
+++ /home/liph/dotfiles/pi/.pi/agent/prompts/Doc/prompts.md
@@ -42,9 +42,9 @@
 ```

 ## Chain recipes

-The `c-*` files are not prompts you run directly in the editor. They are orchestration recipes that run a sequence of `p-*` prompts through the `pi-subagents` prompt-workflow adapter. Each `p-*` step is executed as a forked-context subagent, so later steps can see earlier outputs. Chains run asynchronously by default.
+The `c-*` files are not prompts you run directly in the editor. They are orchestration recipes that run a sequence of `p-*` prompts through the `pi-subagents` prompt-workflow adapter. Each `p-*` step is executed as a forked-context subagent, so later steps can see earlier outputs. Chains run in the foreground by default (stop with `Esc`/`Ctrl+C`); add `--bg` to detach them.

 | Recipe             | Sequence                                  | Use it when…                                                               |
 | ------------------ | ----------------------------------------- | -------------------------------------------------------------------------- |
 | **`c-design-build`** | `p-brainstorm → p-plan → p-test → p-commit` | You want to design a feature, plan it, add tests, and commit in one go.    |
@@ -54,15 +54,15 @@

 Invoke a chain with `/prompt-workflow`, not `/c-recipe`:

 ```text
-/prompt-workflow c-design-build --bg "add a rate-limiter to the API"
-/prompt-workflow c-fix-commit --bg "the checkout intermittently times out"
-/prompt-workflow c-refactor-commit --bg "src/utils.ts"
-/prompt-workflow c-security-loop --bg "auth endpoint"
+/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 background. Watch it with `/subagents-fleet` or check status with `subagent({ action: "status" })`. If you want to run the same sequence ad-hoc, use `/chain-prompts`:
+Add `--bg` to run detached; then watch with `/subagents-fleet`, stop with `/subagents-stop <id>`, or check status with `subagent({ action: "status" })`. To let the agent pick the chain for you, use `/run workflow-router "<task>"`. If you want to run the same sequence ad-hoc, use `/chain-prompts`:

 ```text
 /chain-prompts p-brainstorm -> p-plan -> p-test -> p-commit -- "add a rate-limiter"
 ```


Now create the agents directory and workflow-router.md file.

I need to create `/home/liph/dotfiles/pi/.pi/agent/agents/workflow-router.md`.

But wait, the directory already exists at `/home/liph/.pi/agent/agents/` and is empty. The dotfiles path is `/home/liph/dotfiles/pi/.pi/agent/agents/`. I should create it.

Let me check if the dotfiles path exists.


total 68
drwxr-xr-x 11 liph liph 4096 Jul 24 18:08 .
drwxr-xr-x  6 liph liph 4096 Jul 23 20:54 ..
drwxr-xr-x  2 liph liph 4096 Jul 24 17:23 agents
-rw-r--r--  1 liph liph  121 Jul 21 21:24 auth.json
drwxr-xr-x  4 liph liph 4096 Jul 24 08:22 extensions
-rw-r--r--  1 liph liph 1345 Jul 22 12:50 models.json
drwxr-xr-x  3 liph liph 4096 Jul 21 21:26 npm
drwxr-xr-x  2 liph liph 4096 Jul 23 20:51 profiles
drwxr-xr-x  5 liph liph 4096 Jul 24 18:02 prompts
-rw-r--r--  1 liph liph 4863 Jul 24 17:47 run-history.jsonl
drwxr-xr-x 21 liph liph 4096 Jul 24 16:47 sessions
-rw-r--r--  1 liph liph 1452 Jul 24 16:28 settings.json
drwxr-xr-x  2 liph liph 4096 Jul 24 09:36 skills
drwxr-xr-x  2 liph liph 4096 Jul 23 20:34 state
drwxr-xr-x  2 liph liph 4096 Jul 24 08:34 themes
-rw-r--r--  1 liph liph   25 Jul 22 12:50 trust.json


The dotfiles path `/home/liph/dotfiles/pi/.pi/agent/agents/` exists. Good. I'll write `workflow-router.md` there.

write

---
name: workflow-router
description: Pick the best c-* chain for a task and run it in the foreground
tools: read, subagent
systemPromptMode: append
inheritProjectContext: true
inheritSkills: false
---

You are a workflow router. Given the user's task, choose and execute the single most appropriate `c-*` chain from `~/.pi/agent/prompts/`.

Available chains:

| Chain | Steps | Use it when |
|---|---|---|
| `c-design-build` | `p-brainstorm → p-plan → p-test → p-commit` | Designing or adding a new feature from a vague requirement. |
| `c-fix-commit` | `p-summarize → p-diagnose → p-debug → p-test` | A bug, failure, error, or regression. |
| `c-refactor-commit` | `p-refactor → p-test → p-review → p-commit` | Restructuring existing code without changing behavior. |
| `c-security-loop` | `p-secaudit → p-review → p-test` | Auth, input handling, secrets, network, deserialization, or trust boundaries. |

Steps:
1. Decide which chain is the best fit for the user's task.
2. Read `~/.pi/agent/prompts/c-<name>.md` and note the `chain:` frontmatter value.
3. For each `p-*.md` step in that chain, read `~/.pi/agent/prompts/<step>.md`, ignore its frontmatter, and use the body text (everything after the second `---`).
4. Run the chain with the `subagent` tool:
   - Set `async: false` so the user can stop it with `Esc` or `Ctrl+C`.
   - Each step uses `agent: "delegate"`.
   - The step `task` is the prompt body with `$@` replaced by the user's original task.
   - Use `label` and `phase` for readable status output.
5. Report which chain you chose and why.

Do not ask the user before running. Pick exactly one chain and execute it. If the task truly does not fit any chain, default to `c-design-build`.


Successfully wrote 1709 bytes to /home/liph/dotfiles/pi/.pi/agent/agents/workflow-router.md


Now run the tests to make sure the changes don't break anything.

bash

cd /home/liph/dotfiles/pi/.pi/agent/prompts && npm test 2>&1 | tail -80


npm error Missing script: "test"
npm error
npm error To see a list of scripts, run:
npm error   npm run
npm error A complete log of this run can be found in: /home/liph/.npm/_logs/2026-07-24T16_11_53_858Z-debug-0.log


The package.json doesn't have a "test" script at the top level? Let me check the test directory's package.json.


pi-prompt-workflows-tests

Static tests for the .pi/agent/prompts c-* and p-* workflow chain.

node --test --experimental-strip-types test/chain-workflow.test.ts


The test script is in test/package.json. I need to run it from the test directory.

bash

cd /home/liph/dotfiles/pi/.pi/agent/prompts/test && npm test 2>&1 | tail -100


npm notice run test
npm notice run node --test --experimental-strip-types test/chain-workflow.test.ts
Could not find 'test/chain-workflow.test.ts'


The script has a wrong path? It says `node --test --experimental-strip-types test/chain-workflow.test.ts`. When run from the `test` directory, it looks for `test/test/chain-workflow.test.ts`. So the script is meant to be run from the parent prompts directory. Let me run from the prompts dir using the test/package.json? Actually `npm test` from test dir uses the script which is wrong. Maybe the script should be `node --test --experimental-strip-types chain-workflow.test.ts`. Let me just run it manually.

cd /home/liph/dotfiles/pi/.pi/agent/prompts/test && node --test --experimental-strip-types chain-workflow.test.ts 2>&1 | tail -100


  ✔ c-security-loop.md.chain parses to p-secaudit -> p-review -> p-test (0.113006ms)
  ✔ c-security-loop.md contains a $@ placeholder for the user argument (0.100224ms)
✔ happy path: chain recipes are present and well-formed (2.677991ms)
▶ happy path: every prompt step resolves to a real file
  ✔ step p-brainstorm exists as a p-*.md file (0.180754ms)
  ✔ step p-plan exists as a p-*.md file (0.055804ms)
  ✔ step p-test exists as a p-*.md file (0.052312ms)
  ✔ step p-commit exists as a p-*.md file (0.067817ms)
  ✔ step p-summarize exists as a p-*.md file (0.051823ms)
  ✔ step p-diagnose exists as a p-*.md file (0.068307ms)
  ✔ step p-debug exists as a p-*.md file (0.067189ms)
  ✔ step p-refactor exists as a p-*.md file (0.063837ms)
  ✔ step p-review exists as a p-*.md file (0.061532ms)
  ✔ step p-secaudit exists as a p-*.md file (0.061322ms)
✔ happy path: every prompt step resolves to a real file (1.096465ms)
▶ happy path: every p-*.md has the required chain-step shape
  ✔ p-brainstorm declares subagent: true (0.444272ms)
  ✔ p-brainstorm declares fork: true (0.765479ms)
  ✔ p-brainstorm has description and argument-hint (0.146042ms)
  ✔ p-brainstorm body references $@ (0.175236ms)
  ✔ p-plan declares subagent: true (0.117057ms)
  ✔ p-plan declares fork: true (0.101551ms)
  ✔ p-plan has description and argument-hint (0.091285ms)
  ✔ p-plan body references $@ (0.086676ms)
  ✔ p-test declares subagent: true (0.102809ms)
  ✔ p-test declares fork: true (0.101901ms)
  ✔ p-test has description and argument-hint (0.10665ms)
  ✔ p-test body references $@ (0.096313ms)
  ✔ p-commit declares subagent: true (0.082974ms)
  ✔ p-commit declares fork: true (0.080529ms)
  ✔ p-commit has description and argument-hint (0.081646ms)
  ✔ p-commit body references $@ (0.092403ms)
  ✔ p-summarize declares subagent: true (0.122015ms)
  ✔ p-summarize declares fork: true (0.096104ms)
  ✔ p-summarize has description and argument-hint (0.093939ms)
  ✔ p-summarize body references $@ (0.102948ms)
  ✔ p-diagnose declares subagent: true (0.088212ms)
  ✔ p-diagnose declares fork: true (0.08863ms)
  ✔ p-diagnose has description and argument-hint (0.096244ms)
  ✔ p-diagnose body references $@ (0.143038ms)
  ✔ p-debug declares subagent: true (0.116638ms)
  ✔ p-debug declares fork: true (0.116219ms)
  ✔ p-debug has description and argument-hint (0.104904ms)
  ✔ p-debug body references $@ (0.084301ms)
  ✔ p-refactor declares subagent: true (0.07969ms)
  ✔ p-refactor declares fork: true (0.079551ms)
  ✔ p-refactor has description and argument-hint (0.081507ms)
  ✔ p-refactor body references $@ (0.082066ms)
  ✔ p-review declares subagent: true (0.080041ms)
  ✔ p-review declares fork: true (0.090796ms)
  ✔ p-review has description and argument-hint (0.08919ms)
  ✔ p-review body references $@ (0.088421ms)
  ✔ p-secaudit declares subagent: true (0.094917ms)
  ✔ p-secaudit declares fork: true (0.122505ms)
  ✔ p-secaudit has description and argument-hint (0.09338ms)
  ✔ p-secaudit body references $@ (0.090377ms)
✔ happy path: every p-*.md has the required chain-step shape (6.03709ms)
▶ edge cases: chain format boundaries
  ✔ every chain has at least one step (0.304725ms)
  ✔ no chain has a duplicate step (0.279652ms)
  ✔ every chain step is lowercase kebab-case starting with 'p-' (0.401667ms)
  ✔ chain frontmatter uses ' -> ' (single space) and not '->' or ' - >' (0.333849ms)
  ✔ every chain ends with a real prompt file, not a typo (0.258629ms)
✔ edge cases: chain format boundaries (1.76598ms)
▶ edge cases: argument-hint style
  ✔ every argument-hint is non-empty (0.566916ms)
  ✔ argument-hints are wrapped in [...] to match the documented convention (1.186353ms)
✔ edge cases: argument-hint style (1.845671ms)
▶ error cases: malformed frontmatter
  ✔ rejects a chain file with no closing fence (0.11126ms)
  ✔ rejects a chain value with no separator at all (0.085278ms)
  ✔ flags a chain step that does not exist on disk (0.083812ms)
✔ error cases: malformed frontmatter (0.380226ms)
▶ error cases: required keys
  ✔ every chain recipe has a non-empty description (0.233904ms)
  ✔ no p-* used in a chain is missing the subagent/fork flags (0.368212ms)
✔ error cases: required keys (0.684811ms)
▶ error cases: cross-doc consistency
  ✔ Doc/chain-commands.md has a table row for every chain recipe (0.339856ms)
  ✔ Doc/chain-commands.md table rows show the actual chain sequence (0.649889ms)
  ✔ Doc/prompts.md has a table row for every chain recipe (0.324351ms)
  ✔ Doc/prompts.md table rows show the actual chain sequence (0.421084ms)
  ✔ Doc/chain-commands.md documents ' -> ' as the chain separator (0.106092ms)
  ✔ Doc/prompts.md mentions every prompt used in any chain (0.114263ms)
✔ error cases: cross-doc consistency (2.242869ms)
▶ directory sanity
  ✔ has at least one chain recipe (0.087722ms)
  ✔ has at least one p-*.md prompt (0.057271ms)
  ✔ has both Doc pages (0.092332ms)
  ✔ Doc/ has no extra markdown files we did not expect (0.136334ms)
  ✔ every file in the prompts root is a recognized c-*, p-*, or Doc entry (0.165667ms)
✔ directory sanity (0.669446ms)
ℹ tests 100
ℹ suites 11
ℹ pass 100
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 160.816963


All 100 tests pass. Great.

Now I should provide a final summary to the user. I should also mention that the test package.json script path seems wrong (it expects test/chain-workflow.test.ts but should be chain-workflow.test.ts). Actually, maybe I should not mention it unless they care. But since I noticed it, I could offer to fix it. It's a small thing. But it's not related to their question. I'll leave it unless they ask.

Let me write a concise final response summarizing what I changed and how to use it.

Done. I updated your dotfiles to make the chains foreground-by-default and added an automatic router agent. All 100 existing tests still pass.

### What changed

**`c-*.md` recipes** — removed the hardcoded `--bg` from the examples. They now show:
- foreground invocation first (`/prompt-workflow c-design-build "<task>"`), so `Esc`/`Ctrl+C` stops it
- `--bg` as an optional detach flag, with `/subagents-fleet` and `/subagents-stop <id>` documented

**`Doc/chain-commands.md`** — rewritten to foreground-by-default, added the stop commands, and added an "Automatic routing" section.

**`Doc/prompts.md`** — examples now omit `--bg`, text explains foreground default + optional detach.

**`~/.pi/agent/agents/workflow-router.md`** (new) — a subagent with `tools: read, subagent` that picks the best `c-*` chain for a task and dispatches it with `async: false`.

### How to use it now

Run a chain in the current session, stoppable with `Esc`/`Ctrl+C`:

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

Let the agent pick and run the chain for you:

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

or from another prompt/agent:

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

Detach a chain when you want it to run in the background:

```text
/prompt-workflow c-design-build --bg "add a rate-limiter to the API"
/subagents-fleet
/subagents-stop <run-id>
```

If you're currently invoking these from a shell alias that uses `pi -p`, change the alias to start an interactive session or remove it and run the command inside an already-open Pi session.