mirror of
https://github.com/obra/superpowers.git
synced 2026-08-01 15:11:36 +08:00
Compare commits
5 Commits
fix/t1-sdd
...
fix/t5-cod
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
e9686d5c09 | ||
|
|
d8189d1587 | ||
|
|
db4538fcb8 | ||
|
|
9b8b14fe12 | ||
|
|
75756d2900 |
@@ -34,15 +34,6 @@ Subagent (general-purpose):
|
||||
|
||||
Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
|
||||
|
||||
## You Do Not Dispatch Subagents
|
||||
|
||||
Do all of this review yourself. Never spawn a subagent to review part
|
||||
of the diff, and never spawn another reviewer for a second opinion.
|
||||
This process already provides every review seat the work gets; a
|
||||
reviewer you spawn duplicates one of them at full cost, and its
|
||||
verdict counts for nothing. If the diff feels too large for one
|
||||
pass, review it in passes yourself and say so in your report.
|
||||
|
||||
## What to Check
|
||||
|
||||
**Plan alignment:**
|
||||
|
||||
@@ -197,6 +197,17 @@ Everything you paste into a dispatch prompt — and everything a subagent
|
||||
prints back — stays resident in your context for the rest of the session
|
||||
and is re-read on every later turn. Hand artifacts over as files.
|
||||
|
||||
**Waiting on dispatched subagents:** never poll a wait interface with
|
||||
short timeouts, and never sit in one silent, open-ended wait either.
|
||||
While you have local work — ledger updates, packaging the next review,
|
||||
reading reports — keep working; child results arrive on their own.
|
||||
When you are genuinely idle, wait in bounded stretches (five to ten
|
||||
minutes, where your platform allows), and between stretches post one
|
||||
line of status and reconcile your live children: list them, and chase
|
||||
any that finished without reporting. A bounded stretch keeps nearly
|
||||
all of a long wait's efficiency while guaranteeing a stuck or lost
|
||||
child is noticed within minutes, not at the end of the session.
|
||||
|
||||
### 1. Dispatch the implementer
|
||||
|
||||
Record BASE (`git rev-parse HEAD`) before dispatching — the review package
|
||||
@@ -223,12 +234,6 @@ and fix-round diffs need it.
|
||||
later dispatches — a real session's dispatch hit 42k chars of which 99%
|
||||
was pasted history. A fresh subagent needs its task, the interfaces it
|
||||
touches, and the global constraints. Nothing else.
|
||||
- The dispatch carries the no-subagents contract (it is in the
|
||||
implementer template): the implementer never dispatches subagents —
|
||||
not helpers, and never a reviewer. Review arrives from you, after the
|
||||
report. In real sessions, every reviewer a worker spawned duplicated
|
||||
the task review the controller dispatched anyway — a full extra
|
||||
review seat per task.
|
||||
- If an earlier task parked a finding in the area this task touches, carry
|
||||
a pointer to that ledger entry in the dispatch.
|
||||
- Record the implementer's agent identity from the dispatch result —
|
||||
@@ -440,7 +445,6 @@ Use superpowers:finishing-a-development-branch.
|
||||
| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. |
|
||||
| "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
|
||||
| "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
|
||||
| "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
|
||||
|
||||
## Example Workflow
|
||||
|
||||
|
||||
@@ -47,18 +47,6 @@ Subagent (general-purpose):
|
||||
While iterating, run the focused test for what you're changing; run the
|
||||
full suite once before committing, not after every edit.
|
||||
|
||||
## You Do Not Dispatch Subagents
|
||||
|
||||
Do all of this task's work yourself. Never spawn a subagent to
|
||||
implement part of the task, and above all never spawn a reviewer to
|
||||
check your work. Self-review (below) means reading your own diff.
|
||||
Review is the controller's job: after you report, it dispatches a
|
||||
fresh reviewer against your diff. A reviewer you spawn duplicates
|
||||
that review at full cost, and its approval counts for nothing in
|
||||
the process. If you catch yourself thinking "an independent review
|
||||
would strengthen my report" — that review is already scheduled.
|
||||
Report instead.
|
||||
|
||||
## Code Organization
|
||||
|
||||
You reason best about code you can hold in context at once, and your edits are more
|
||||
|
||||
@@ -43,15 +43,6 @@ Subagent (general-purpose):
|
||||
Your review is read-only on this checkout. Do not mutate the working
|
||||
tree, the index, HEAD, or branch state in any way.
|
||||
|
||||
## You Do Not Dispatch Subagents
|
||||
|
||||
Do all of this review yourself. Never spawn a subagent to review part
|
||||
of the diff, and never spawn another reviewer for a second opinion.
|
||||
This process already provides every review seat the work gets; a
|
||||
reviewer you spawn duplicates one of them at full cost, and its
|
||||
verdict counts for nothing. If the diff feels too large for one
|
||||
pass, review it in passes yourself and say so in your report.
|
||||
|
||||
## Scope
|
||||
|
||||
Your scope is the findings list and the fix diff. Verdict every finding.
|
||||
|
||||
@@ -52,15 +52,6 @@ Subagent (general-purpose):
|
||||
Your review is read-only on this checkout. Do not mutate the working
|
||||
tree, the index, HEAD, or branch state in any way.
|
||||
|
||||
## You Do Not Dispatch Subagents
|
||||
|
||||
Do all of this review yourself. Never spawn a subagent to review part
|
||||
of the diff, and never spawn another reviewer for a second opinion.
|
||||
This process already provides every review seat the work gets; a
|
||||
reviewer you spawn duplicates one of them at full cost, and its
|
||||
verdict counts for nothing. If the diff feels too large for one
|
||||
pass, review it in passes yourself and say so in your report.
|
||||
|
||||
## Do Not Trust the Report
|
||||
|
||||
Treat the implementer's report as unverified claims about the code. It
|
||||
|
||||
@@ -7,7 +7,76 @@ Add to your Codex config (`~/.codex/config.toml`):
|
||||
multi_agent = true
|
||||
```
|
||||
|
||||
This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. When using subagent-driven-development, close reviewer subagents when their review returns. Keep each implementer subagent open until its task's review passes — the fix loop resumes the implementer — then close it. If your harness cannot send another message to a spawned agent, dispatch each fix round as a fresh implementer carrying the brief, the report file, and the findings.
|
||||
This enables the multi-agent tools that skills like
|
||||
`dispatching-parallel-agents` and `subagent-driven-development` use.
|
||||
Which tools you get depends on the multi-agent version your model
|
||||
preset selects (current presets run V2; older ones run V1). Trust your
|
||||
actual tool list over any table — including this one — when they
|
||||
disagree.
|
||||
|
||||
- **Spawning:** give children a clean context with
|
||||
`spawn_agent {fork_turns: "none"}`; the default `"all"` copies your
|
||||
entire transcript into the child. On Codex 0.145+, role files under
|
||||
`~/.codex/agents/` attach to isolated forks via `agent_type`.
|
||||
Full-history forks accept `model` and `reasoning_effort` overrides
|
||||
(only `agent_type` is refused there) — isolated forks are the SDD
|
||||
default for context hygiene, not because overrides require them.
|
||||
- **Fix rounds:** resume the implementer with `followup_task` — it
|
||||
delivers your message, triggers a turn, and transparently reloads a
|
||||
child the harness evicted. Never dispatch a fresh implementer on the
|
||||
theory that a spawned agent cannot be messaged again; on V2 it
|
||||
always can.
|
||||
- **Lifecycle:** V2 has no `close_agent`. Finished children are
|
||||
evicted automatically when slots are needed; leaving them unclosed
|
||||
costs nothing. Only V1 sessions have `close_agent` — there, close
|
||||
reviewers when their review returns, and close each implementer
|
||||
after its task's review passes.
|
||||
- **Model names:** never copy a model name from a skill, table, or old
|
||||
session into `spawn_agent` without checking it against your current
|
||||
spawn allowlist — V2 accepts only V2-capable presets and hard-errors
|
||||
on the rest.
|
||||
|
||||
## Waiting on children
|
||||
|
||||
`wait_agent` is an event subscription, not a poll: a long wait wakes
|
||||
the moment a child produces mailbox activity, with the same latency as
|
||||
a short one. Short-timeout polling buys nothing and costs a tool call —
|
||||
and a context rebill — per poll. In measured sessions, roughly
|
||||
two-thirds of all wait calls were short polls that timed out.
|
||||
|
||||
- While you still have local work, do not wait at all. A completed
|
||||
child's final answer is pushed into your mailbox and arrives with
|
||||
your next turn.
|
||||
- When you are genuinely idle with children outstanding, wait in
|
||||
bounded stretches: `wait_agent` with `timeout_ms` 300000-600000
|
||||
(5-10 minutes). After each stretch — wake or timeout — post one
|
||||
status line, run `list_agents`, and chase any child that finished
|
||||
without reporting. Never stack polls shorter than five minutes; the
|
||||
event subscription wakes a bounded stretch just as fast as a short
|
||||
one.
|
||||
- Completion mail cannot wake an idle controller (it is delivered
|
||||
without triggering a turn); covering that idle window is
|
||||
`wait_agent`'s only job. A stretch that times out with no activity
|
||||
is your cue to reconcile, not to shorten the next stretch.
|
||||
|
||||
## Model routing on spawns
|
||||
|
||||
Every `spawn_agent` you issue — including when you are yourself a
|
||||
spawned child running a fan-out — sets `model` AND `reasoning_effort`
|
||||
explicitly, per the Model Selection rules of the skill you are
|
||||
executing. Setting `model` alone is a trap: the child's effort
|
||||
silently resets to that model's default, not to yours.
|
||||
|
||||
Ask your human partner to add a machine-level backstop to
|
||||
`~/.codex/config.toml` so any spawn that slips through still routes to
|
||||
a deliberate tier instead of silently inheriting the session's most
|
||||
expensive model:
|
||||
|
||||
```toml
|
||||
[agents]
|
||||
default_subagent_model = "<a mid-tier model from your spawn allowlist>"
|
||||
default_subagent_reasoning_effort = "medium"
|
||||
```
|
||||
|
||||
## Environment Detection
|
||||
|
||||
|
||||
Reference in New Issue
Block a user