liph/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

commit pi sessions

Browse Source
This commit is contained in:
liph
2026-07-27 08:46:32 +02:00
parent 37ea5bb522
commit 44d6863b59
435 changed files with 14054 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pi/.pi/agent/prompts/Doc/chain-commands.md
+108
View File
@@ -0,0 +1,108 @@
# 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. |
pi/.pi/agent/prompts/Doc/prompts.md
+75
View File
@@ -0,0 +1,75 @@
# Prompts
Slash-style prompts for the interactive pi session. Each file is a `p-<verb>.md` template with a frontmatter `description` + `argument-hint` and a structured body. Invoke with `:p-<verb> [arg]` or via the `:prompts` TUI picker.
## When to use which
| Prompt | Use it when… | Pairs well with |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **`p-plan`** | You're about to start a non-trivial change and want a structured plan before coding. | `p-brainstorm` (first), then `p-refactor` / `p-test` |
| **`p-brainstorm`** | You have a problem but no chosen approach yet; want 3–5 alternatives with trade-offs. | `p-plan` (after picking one) |
| **`p-explain`** | You don't understand a piece of code, a concept, or an error message. | `p-debug` / `p-diagnose` (if it's a problem) |
| **`p-debug`** | A test, build, or command is failing with a clear error. You have the error in hand. | `p-test` (add a regression test after the fix) |
| **`p-diagnose`** | Nothing is "failing" but behavior is wrong — wrong values, races, perf drift, "passes locally, broken in prod." | `p-debug` (if you find a hard failure) |
| **`p-review`** | You want a code review of a diff, file, or staged change. General quality feedback. | `p-secaudit` (security subset) |
| **`p-secaudit`** | Touching auth, input handling, secrets, network, deserialization, or any trust boundary. | `p-review` (broader quality), `p-test` |
| **`p-refactor`** | Restructuring code without changing behavior. Safety-first, mechanical steps. | `p-test` (first, as the safety net), `p-review` (after) |
| **`p-test`** | You need to write or expand tests for existing or new code. | `p-debug` (after a failure), `p-refactor` (before) |
| **`p-doc`** | Writing or improving README, docstrings, JSDoc, godoc, or ADRs. | `p-summarize` (skim the code first) |
| **`p-commit`** | About to commit. You want a conventional message and (optionally) a PR description. | `p-review` (final check before committing) |
| **`p-summarize`** | A file, log, diff, or document is too long to read in full. You need the gist + key details. | `p-plan` / `p-debug` (then dive into specifics) |
## Decision flow
```
Got an idea or vague problem?
└─ Yes → p-brainstorm → pick an approach → p-plan → implement
└─ p-test → p-commit
Touching existing code that needs to change?
└─ p-refactor (after p-test confirms a safety net) → p-review → p-commit
Something is broken?
├─ Hard failure (error message, failing test) → p-debug
└─ Soft failure (wrong output, race, perf) → p-diagnose
→ fix → p-test (regression) → p-commit
Touching a trust boundary, auth, secrets, or untrusted input?
└─ p-secaudit (then p-review for general quality)
Need to understand a long file/log/diff quickly?
└─ p-summarize
Need to write or update docs?
└─ p-doc
Don't know what something does or what an error means?
└─ p-explain
```
## 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 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. |
| **`c-fix-commit`** | `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`** | `p-refactor → p-test → p-review → p-commit` | You want a safe refactor with tests, review, and a commit. |
| **`c-security-loop`** | `p-secaudit → p-review → p-test` | You need a security-first review plus tests before proceeding. |
Invoke a chain with `/prompt-workflow`, not `/c-recipe`:
```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"
```
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"
```
## Conventions
- Every prompt uses `$@` for the user-supplied argument. Pass an argument at invocation time; if the request is under-specified, the prompt will ask clarifying questions.
- Output is structured (numbered sections, fixed categories) so the result is diff-friendly and skim-friendly.
- Prompts intentionally do **not** overlap with subagent workflows (`agents/`, `chains/`, `skills/`) — those are for orchestration; these are for interactive turns.
- Prefer one prompt per turn. Chain them yourself (`p-brainstorm` → `p-plan` → `p-refactor`) rather than asking one prompt to do everything.