@dirtydishes/skills 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +13 -9
  2. package/package.json +2 -2
  3. package/skills/dirtyloops/SKILL.md +5 -4
  4. package/skills/dirtyloops/examples/README.md +1 -1
  5. package/skills/dirtyloops/examples/orchestrator-callback/README.md +2 -0
  6. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/IMPLEMENT.md +16 -6
  7. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/closeout-selector-subagent.md +8 -1
  8. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/implementation-swarm-subagent.md +29 -0
  9. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/implementation-thread.md +15 -3
  10. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/review-thread.md +6 -2
  11. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/run-loop.md +7 -2
  12. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/selector-subagent.md +8 -1
  13. package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/turn-docs/01-foundation.md +10 -0
  14. package/skills/dirtyloops/examples/single-thread-subagent/README.md +1 -0
  15. package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/IMPLEMENT.md +2 -2
  16. package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/prompts/run-loop.md +5 -4
  17. package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/turn-docs/01-foundation.md +5 -5
  18. package/skills/dirtyloops/plan.html +6 -6
  19. package/skills/dirtyloops/references/beads.md +20 -4
  20. package/skills/dirtyloops/references/create-loop.md +12 -7
  21. package/skills/dirtyloops/references/help.md +6 -4
  22. package/skills/dirtyloops/references/run-loop.md +7 -3
  23. package/skills/dirtyloops/references/swarms.md +12 -4
  24. package/skills/dirtyloops/references/workflows/orchestrator-callback.md +25 -3
  25. package/skills/dirtyloops/references/workflows/single-thread-subagent.md +7 -6
  26. package/skills/dirtyloops/schemas/implementation-callback.schema.json +14 -1
  27. package/skills/dirtyloops/templates/common/IMPLEMENT.md.template +3 -2
  28. package/skills/dirtyloops/templates/common/run-loop.md.template +3 -1
  29. package/skills/dirtyloops/templates/workflows/orchestrator-callback/closeout-selector-subagent-prompt.md.template +8 -1
  30. package/skills/dirtyloops/templates/workflows/orchestrator-callback/implementation-swarm-subagent-prompt.md.template +29 -0
  31. package/skills/dirtyloops/templates/workflows/orchestrator-callback/implementation-thread-prompt.md.template +15 -3
  32. package/skills/dirtyloops/templates/workflows/orchestrator-callback/review-thread-prompt.md.template +6 -2
  33. package/skills/dirtyloops/templates/workflows/orchestrator-callback/run-loop-addendum.md.template +6 -1
  34. package/skills/dirtyloops/templates/workflows/orchestrator-callback/selector-subagent-prompt.md.template +8 -1
  35. package/skills/dirtyloops/templates/workflows/single-thread-subagent/run-loop-addendum.md.template +5 -4
package/README.md CHANGED
@@ -90,11 +90,11 @@ A created loop writes a project-local execution surface under `docs/implementati
90
90
  - `IMPLEMENT.md` - Agent-facing index for the stream, including workflow rules, phase links, quality gates, and operating contract.
91
91
  - `00-roadmap.md` - Human-readable map of the implementation stream and phase ordering.
92
92
  - `NN-phase-name.md` - One phase doc per Beads child issue.
93
- - Beads loop metadata - Canonical workflow, run policy, callback policy, thread defaults, swarm policy, quality gates, and branch/PR policy.
93
+ - Beads loop metadata - Canonical workflow, run policy, callback policy, actor-specific thread defaults, swarm policy, quality gates, and branch/PR policy.
94
94
  - `loop-state.md` - Lightweight mirror for current phase, branch/PR posture, blockers, and next action.
95
95
  - `turn-docs/` - One Markdown turn doc per phase. Reviewers update the existing phase turn doc instead of creating separate review docs.
96
96
  - `prompts/run-loop.md` - The prompt used to start or continue loop execution.
97
- - Workflow prompts - `orchestrator-callback` also emits selector, implementation, review, and closeout-selector prompts.
97
+ - Workflow prompts - `orchestrator-callback` also emits selector, implementation, implementation-swarm, review, and closeout-selector prompts.
98
98
  - Schemas - Callback/report JSON contracts for implementation, review, and swarm reports.
99
99
  - `storyboard-post-run-mm-dd-yyyy.html` - Final closeout artifact generated after the stream completes.
100
100
 
@@ -109,19 +109,19 @@ The skill package itself mirrors that shape:
109
109
 
110
110
  #### Workflows
111
111
 
112
- - `single-thread-subagent` - One visible coordinator thread owns loop state while mass subagent swarms handle selection, scouting, slice planning, implementation assistance, review, and CI.
112
+ - `single-thread-subagent` - One visible coordinator thread owns loop state while per-phase mass subagent swarms handle selection, scouting, slice planning, implementation assistance, review, and CI.
113
113
  - `orchestrator-callback` - One orchestrator thread delegates phase gates to selector subagents, creates separate implementation and review threads, and receives callbacks to a concrete orchestrator thread id when workers/reviewers are done or blocked.
114
114
 
115
- Choose `single-thread-subagent` when you want one visible coordinator thread, less thread management, and a CLI-friendly loop. The main coordinator owns the branch, integration, PR state, Beads updates, and closeout. Subagents inspect, scout, split phases into slices, prepare implementation guidance or patches, review, verify CI, and report, but they do not advance loop state. Broad phases should use 8+ subagents before implementation.
115
+ Choose `single-thread-subagent` when you want one visible coordinator thread, less thread management, and a CLI-friendly loop. The main coordinator owns the branch, integration, PR state, Beads updates, and closeout. Every phase uses selector, scout, slice-plan, implementation-helper, reviewer, and CI swarms; subagents inspect, split phases into slices, prepare implementation guidance or patches, review, verify CI, and report, but they do not advance loop state. Fewer agents require an explicit tiny-phase reason in the turn doc before implementation.
116
116
 
117
- Choose `orchestrator-callback` when you want the original multi-thread flow. The orchestrator launches a selector subagent before the first worker, creates implementation threads with a concrete callback target id, waits for implementation callbacks, creates review threads with the same callback target id, waits for review and CI callbacks, launches a closeout-selector subagent between phases, updates Beads, and then advances only to the selected next phase.
117
+ Choose `orchestrator-callback` when you want the original multi-thread flow. The orchestrator launches a selector subagent before the first worker, creates implementation threads with a concrete callback target id, waits for implementation callbacks, creates review threads with the same callback target id, waits for review and CI callbacks, launches a closeout-selector subagent between phases, updates Beads, and then advances only to the selected next phase. Implementation threads are swarm-first for non-trivial phases: they run scout, slice-plan, and implementation-helper swarms, synthesize a coherent slice plan, integrate helper output, and only then open the PR.
118
118
 
119
119
  #### Authority Rules
120
120
 
121
121
  The `dirtyloops` skill is strict about ownership:
122
122
 
123
123
  - Beads is canonical for status, ordering, blockers, dependencies, and completion.
124
- - Beads stores typed dirtyloop metadata for workflow, run policy, callback policy, thread defaults, swarm policy, quality gates, and branch/PR policy.
124
+ - Beads stores typed dirtyloop metadata for workflow, run policy, callback policy, actor-specific thread defaults, swarm policy, quality gates, and branch/PR policy.
125
125
  - Generated docs and prompts use repo-relative paths so they can move between machines.
126
126
  - Phase docs are execution context linked from Beads child issues.
127
127
  - One Markdown turn doc exists per phase.
@@ -132,13 +132,17 @@ The `dirtyloops` skill is strict about ownership:
132
132
  - Broad scout, slice, implementation-helper, and review work should use bounded subagent swarms, usually 8 or more agents and up to 20 when the phase warrants it.
133
133
  - Phase scope stays narrow. File follow-up Beads issues instead of widening an active phase.
134
134
 
135
- For `orchestrator-callback`, only the orchestrator creates implementation and review threads. The orchestrator must launch a selector subagent before the first worker and a closeout-selector subagent after each review callback before stopping or continuing. Implementation threads do not create review threads, review threads do not create follow-up implementation threads, selector subagents never implement, closeout-selector subagents never mutate Beads, and reviewer subagents never close Beads issues.
135
+ For `orchestrator-callback`, only the orchestrator creates implementation and review threads. It must create them in the intended Codex project worktree using first-class thread environment control; launching a generic thread and telling it to `cd` into the worktree is a workflow violation. Worker and reviewer prompts include expected repo root/worktree plus branch/ref for verification, and a child that starts in the wrong environment blocks and calls back instead of self-relocating. The orchestrator must launch a selector subagent before the first worker and a closeout-selector subagent after each review callback before stopping or continuing. Implementation threads do not create review threads, review threads do not create follow-up implementation threads, selector subagents never implement, closeout-selector subagents never mutate Beads, and reviewer subagents never close Beads issues.
136
136
 
137
- For `single-thread-subagent`, the coordinator must run a slice/scout swarm before broad implementation. Solo coordinator implementation of most phase work is a workflow violation; coordinator implementation should be limited to synthesis, integration, glue, conflicts, final repairs, and Beads/PR closeout.
137
+ Every `orchestrator-callback` child thread must launch with explicit actor settings: `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false`, unless Beads metadata overrides that actor. This applies to selector, implementation, review, and closeout-selector threads. Current UI settings, recent Codex thread defaults, parent/orchestrator settings, `fast`, and `xhigh` are not valid launch defaults unless the actor metadata names them.
138
+
139
+ For `orchestrator-callback`, implementation threads must not do broad solo implementation. For non-trivial phases, they run 8-20 scout agents, 8-16 slice-plan agents, and 8-16 implementation-helper agents before broad edits. The implementation thread synthesizes reports into the existing turn doc, integrates helper output coherently, owns gates and PR state, and includes a `swarm_summary` in the implementation callback. If a phase is tiny enough to use fewer agents, the reason is recorded in the turn doc and callback.
140
+
141
+ For `single-thread-subagent`, the coordinator must run per-phase selector/scout/slice-plan/implementation-helper/reviewer/CI swarms. Solo coordinator implementation of most phase work is a workflow violation; coordinator implementation should be limited to synthesis, integration, glue, conflicts, final repairs, and Beads/PR closeout.
138
142
 
139
143
  #### Callback Contracts
140
144
 
141
- Implementation threads call back exactly once when the PR is ready, the task is complete but PR creation is blocked, or the phase is genuinely blocked. The callback includes the concrete orchestrator thread id, source thread id, Beads issue id, status, branch, PR, commits, turn doc, local gates, changed files, blockers, and context to keep.
145
+ Implementation threads call back exactly once when the PR is ready, the task is complete but PR creation is blocked, or the phase is genuinely blocked. The callback includes the concrete orchestrator thread id, source thread id, Beads issue id, status, branch, PR, commits, turn doc, local gates, changed files, `swarm_summary`, blockers, and context to keep.
142
146
 
143
147
  Review threads call back exactly once after review and CI are resolved. The callback includes the concrete orchestrator thread id, source thread id, Beads issue id, status, PR, CI state, review skill, repairs, remaining findings, turn doc, and context to keep.
144
148
 
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@dirtydishes/skills",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Installer and catalog for dirtydishes agent skills.",
5
5
  "type": "module",
6
6
  "bin": {
7
- "skills": "./bin/skills.js"
7
+ "skills": "bin/skills.js"
8
8
  },
9
9
  "files": [
10
10
  "bin/",
@@ -50,7 +50,7 @@ A dirtyloop is a Beads-canonical Codex implementation loop: phase docs, one Mark
50
50
  ## Hard Requirements
51
51
 
52
52
  - Beads is canonical for status, ordering, blockers, dependencies, and completion.
53
- - Beads records typed dirtyloop metadata: workflow, run policy, branch/PR policy, quality gates, callback policy, thread defaults, and swarm policy.
53
+ - Beads records typed dirtyloop metadata: workflow, run policy, branch/PR policy, quality gates, callback policy, actor-specific thread defaults, and swarm policy.
54
54
  - Phase docs are execution context linked from Beads.
55
55
  - Generated docs, prompts, examples, and callback payloads use repo-relative paths. Do not include user-specific home directories or usernames in generated loop artifacts.
56
56
  - Use one Markdown turn doc per phase.
@@ -61,9 +61,10 @@ A dirtyloop is a Beads-canonical Codex implementation loop: phase docs, one Mark
61
61
  - For `orchestrator-callback`, the orchestrator must spawn a selector subagent before the first worker and a closeout-selector subagent after each review callback before continuing or stopping. The orchestrator validates their reports and remains the only actor that mutates Beads, updates loop state, creates implementation/review threads, or advances the loop.
62
62
  - Orchestrator-callback prompts and callback payloads must carry the concrete orchestrator thread id. Do not launch a worker or reviewer if the actual instruction text says only `current orchestrator thread`, `this thread`, or another generic target.
63
63
  - Orchestrator-callback is callback-wait, not active monitoring. After launching a worker or reviewer, the orchestrator must not repeatedly read, monitor, or summarize the child thread while waiting for its single callback. Use only a sparse fallback heartbeat when the callback is overdue or liveness is uncertain.
64
- - Worker and reviewer threads default to standard speed/reasoning unless the Beads loop metadata explicitly says otherwise.
65
- - For `single-thread-subagent`, the coordinator orchestrates, synthesizes, integrates, owns branch/PR/Beads state, and closes out. It must launch mass subagent swarms before broad implementation; direct coordinator implementation is for integration, glue, and final repair work.
66
- - Use large bounded subagent swarms: 8+ by default for broad scout, slice, implementation-helper, and review work, and up to 20 when the phase warrants it.
64
+ - Every orchestrator-callback child thread defaults to `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads loop metadata explicitly overrides that actor. This applies to selector, implementation, review, and closeout-selector threads. Do not launch child threads with inherited `fast`, `xhigh`, current UI, or orchestrator-thread settings.
65
+ - Orchestrator-callback implementation threads are swarm-first for non-trivial phases: they must run massive bounded scout, slice-plan, and implementation-helper swarms before broad edits, synthesize one coherent slice plan, integrate helper output, and include `swarm_summary` in the implementation callback.
66
+ - For `single-thread-subagent`, the coordinator orchestrates, synthesizes, integrates, owns branch/PR/Beads state, and closes out. Each phase must launch per-phase selector, scout, slice-plan, implementation-helper, review, and CI swarms unless the phase is explicitly tiny and the reason is recorded in the turn doc. Direct coordinator implementation is for integration, glue, conflict resolution, and final repair work.
67
+ - Use large bounded subagent swarms: per-phase for `single-thread-subagent`, swarm-first inside non-trivial `orchestrator-callback` implementation threads, 8+ by default for scout, slice-plan, implementation-helper, and review work, and up to 20 when the phase warrants it.
67
68
  - Closeout generates `storyboard-post-run-mm-dd-yyyy.html`.
68
69
  - The storyboard should use `impeccable` when present. If it is missing, continue without it and add a brief note that the skill was not found and was skipped during closeout.
69
70
  - Closeout must install `@pierre/diffs` in the target repo if missing, then use `@pierre/diffs/ssr` for every storyboard diff. SSR is required for every diff block.
@@ -5,4 +5,4 @@ These examples show the shape `$dirtyloops create` should produce.
5
5
  - `single-thread-subagent/` shows one visible coordinator thread with mass subagent swarms, slice planning, implementation helpers, review, and CI verification.
6
6
  - `orchestrator-callback/` shows the original thread-callback loop: orchestrator thread, selector and closeout-selector subagents, implementation threads, review threads, concrete callback targets, and callback payloads.
7
7
 
8
- Treat these as shape examples, not content to copy verbatim. New loops should fill in repo-specific Beads ids, phase docs, gates, branch policy, callback target ids, thread defaults, swarm policy, and prompt wording.
8
+ Treat these as shape examples, not content to copy verbatim. New loops should fill in repo-specific Beads ids, phase docs, gates, branch policy, callback target ids, actor-specific thread defaults, swarm policy, and prompt wording.
@@ -8,6 +8,8 @@ Topology:
8
8
  orchestrator thread
9
9
  -> selector subagent chooses first ready phase
10
10
  -> implementation thread with exact callback target
11
+ -> scout/slice-plan/implementation-helper swarms
12
+ -> worker integrates one coherent PR
11
13
  -> implementation callback when PR-ready
12
14
  -> review thread with exact callback target
13
15
  -> review callback when review + CI resolved
@@ -13,7 +13,7 @@ Replace an old reporting path with a simpler evidence-backed implementation whil
13
13
  ## Sources Of Truth
14
14
 
15
15
  - Beads epic: `example-epic`
16
- - Beads loop metadata: workflow, run policy, callback policy, thread defaults, quality gates, and branch/PR policy
16
+ - Beads loop metadata: workflow, run policy, callback policy, actor-specific thread defaults, quality gates, and branch/PR policy
17
17
  - Roadmap: `docs/implementation/example-stream/00-roadmap.md`
18
18
  - Loop state mirror: `docs/implementation/example-stream/loop-state.md`
19
19
  - Phase docs linked from Beads child issues
@@ -21,11 +21,12 @@ Replace an old reporting path with a simpler evidence-backed implementation whil
21
21
 
22
22
  ## Thread Topology
23
23
 
24
- Only the orchestrator creates implementation and review threads.
24
+ Only the orchestrator creates implementation and review threads. It creates them in the intended Codex project worktree using first-class thread environment control; launching a generic thread and telling it to `cd` into the worktree is a workflow violation.
25
25
 
26
26
  Selector subagents:
27
27
 
28
28
  - run before the first implementation thread
29
+ - launch with `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads metadata overrides the selector actor
29
30
  - read Beads, `IMPLEMENT.md`, `loop-state.md`, and linked phase docs
30
31
  - return a `swarm-report` with mission `selector`
31
32
  - never implement, mutate Beads, edit files, or create threads
@@ -33,18 +34,24 @@ Selector subagents:
33
34
  Implementation threads:
34
35
 
35
36
  - receive the full phase doc, Beads issue id, branch policy, quality gates, and orchestrator thread id
36
- - default to standard speed/reasoning unless Beads metadata explicitly overrides it
37
+ - start in the intended repo/worktree environment before prompt execution
38
+ - verify repo root, worktree, and branch/ref before edits; block and call back if the launch environment is wrong
39
+ - launch with `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads metadata overrides the implementation actor
37
40
  - have prompt text that names the exact orchestrator thread id as callback target
38
- - may use bounded subagents
41
+ - run 8-20 scout agents, 8-16 slice-plan agents, and 8-16 implementation-helper agents for non-trivial phases
42
+ - synthesize swarm reports into one coherent slice plan before broad edits
43
+ - integrate helper output, resolve conflicts, and own final branch/PR state
39
44
  - update the existing phase turn doc
40
45
  - open the PR
41
- - call back exactly once when PR-ready or blocked, echoing `orchestrator_thread_id` and including `source_thread_id`
46
+ - call back exactly once when PR-ready or blocked, echoing `orchestrator_thread_id`, including `source_thread_id`, and reporting `swarm_summary`
42
47
  - do not create review threads
43
48
 
44
49
  Review threads:
45
50
 
46
51
  - use `thermo-nuclear-code-quality-review`
47
- - default to standard speed/reasoning unless Beads metadata explicitly overrides it
52
+ - start in the intended repo/worktree environment before prompt execution
53
+ - verify repo root, worktree, and branch/ref before review or repair; block and call back if the launch environment is wrong
54
+ - launch with `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads metadata overrides the review actor
48
55
  - have prompt text that names the exact orchestrator thread id as callback target
49
56
  - may use reviewer and CI verification subagents
50
57
  - own CI, repairs, reruns, and evidence
@@ -54,6 +61,7 @@ Review threads:
54
61
  Closeout-selector subagents:
55
62
 
56
63
  - run after each review callback and before the orchestrator closes, stops, or launches another worker
64
+ - launch with `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads metadata overrides the closeout-selector actor
57
65
  - check the review callback, PR/CI evidence, existing turn doc, Beads dependencies, and `loop-state.md`
58
66
  - recommend exact closeout actions and at most one next phase
59
67
  - return a `swarm-report` with mission `closeout-selector`
@@ -63,6 +71,8 @@ The orchestrator validates selector reports, owns Beads closeout, and launches o
63
71
 
64
72
  After launching implementation or review threads, the orchestrator waits for the single callback. It does not repeatedly read, monitor, summarize, or status-check the child thread unless a sparse fallback heartbeat is needed for an overdue callback or liveness recovery.
65
73
 
74
+ No `orchestrator-callback` child thread inherits current UI settings, recent Codex thread defaults, or parent/orchestrator speed/reasoning. `fast` speed and `xhigh` reasoning are allowed only when Beads metadata explicitly names that value for the actor being launched.
75
+
66
76
  ## Phase Ledger
67
77
 
68
78
  | Beads Issue | Phase | Phase Doc | Depends On | Status |
@@ -6,6 +6,14 @@ Canonical tracker: Beads epic `example-epic`
6
6
 
7
7
  Mission: verify the just-reviewed phase can be closed out, then recommend stop or at most one next phase.
8
8
 
9
+ Launch defaults:
10
+
11
+ - speed: `standard`
12
+ - reasoning: `high`
13
+ - inherit_orchestrator_thread_settings: `false`
14
+
15
+ Do not run this closeout-selector with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the closeout-selector actor.
16
+
9
17
  Read:
10
18
 
11
19
  - Beads epic `example-epic`
@@ -30,4 +38,3 @@ Rules:
30
38
  - Recommend exactly one next phase only when continuation is allowed and Beads dependencies make it ready.
31
39
 
32
40
  Return a compact report matching `schemas/swarm-report.schema.json` with `mission: "closeout-selector"`.
33
-
@@ -0,0 +1,29 @@
1
+ # Implementation Swarm Subagent Prompt: Example Stream
2
+
3
+ You are an implementation swarm subagent inside an `orchestrator-callback` implementation thread.
4
+
5
+ Mission: `scout|slice-plan|implementation-helper`
6
+
7
+ Allowed missions:
8
+
9
+ - `scout`: inspect a bounded surface and report facts, risks, likely files, and tests
10
+ - `slice-plan`: propose non-overlapping implementation slices and integration order
11
+ - `implementation-helper`: work one assigned slice in parallel and return patch guidance, changed files, gates, and integration notes
12
+
13
+ Inputs:
14
+
15
+ - Beads issue: `example-epic.1`
16
+ - Phase doc: `docs/implementation/example-stream/01-foundation.md`
17
+ - Turn doc: `docs/implementation/example-stream/turn-docs/01-foundation.md`
18
+ - Slice id: assigned by the implementation thread
19
+ - Assigned scope: assigned by the implementation thread
20
+
21
+ Rules:
22
+
23
+ - Stay inside the assigned scope.
24
+ - Do not mutate Beads.
25
+ - Do not create PRs or review threads.
26
+ - Do not own loop state or callback.
27
+ - Implementation-helper agents may prepare patches or concrete edit guidance only for their assigned slice.
28
+ - Return compact structured output matching `schemas/swarm-report.schema.json`.
29
+
@@ -14,17 +14,29 @@ Send your final callback to exact orchestrator thread id `THREAD_ORCHESTRATOR_ID
14
14
  - Phase doc: `docs/implementation/example-stream/01-foundation.md`
15
15
  - Implementation index: `docs/implementation/example-stream/IMPLEMENT.md`
16
16
  - Turn doc: `docs/implementation/example-stream/turn-docs/01-foundation.md`
17
- - Branch policy: create or use `example-stream/01-foundation`
18
- - Thread default: standard speed/reasoning
17
+ - Expected repo/worktree and branch/ref: create or use `example-stream/01-foundation`
18
+ - Launch environment: this thread must already be bound to the intended Codex project worktree before this prompt runs
19
+ - Launch defaults: speed `standard`, reasoning `high`, inherit_orchestrator_thread_settings `false`
20
+ - Do not run this worker with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the implementation actor
19
21
 
20
22
  ## Rules
21
23
 
24
+ - Before edits, verify `pwd`, `git rev-parse --show-toplevel`, and the current branch/ref match the expected repo/worktree and branch/ref.
25
+ - Do not `cd` into the target worktree as setup or recovery. If the launch environment is wrong, stop and send a blocked callback to the orchestrator.
22
26
  - Implement exactly this phase.
23
27
  - Do not widen scope.
24
- - Use bounded implementation/scout subagents when useful.
28
+ - Do not do broad solo implementation.
29
+ - For non-trivial phases, run massive bounded swarms before broad edits:
30
+ - 8-20 scout agents across files, modules, risks, tests, and integration edges
31
+ - 8-16 slice-plan agents to propose non-overlapping implementation slices
32
+ - 8-16 implementation-helper agents assigned to slices in parallel
33
+ - If this phase is tiny enough to use fewer than the default agents, record the reason in the turn doc and callback `swarm_summary`.
34
+ - Synthesize swarm reports into one coherent slice plan before broad edits.
35
+ - Integrate helper output yourself; own conflicts, final repairs, gates, branch state, PR state, and callback.
25
36
  - Update the existing Markdown turn doc.
26
37
  - Run local gates before PR when feasible.
27
38
  - Open or update the PR.
28
39
  - Do not create the review thread.
29
40
  - Call back exactly once to the orchestrator when PR-ready or blocked.
30
41
  - The callback payload must include `orchestrator_thread_id: "THREAD_ORCHESTRATOR_ID"` and your `source_thread_id`.
42
+ - The callback payload must include `swarm_summary` with scout, slice-plan, implementation-helper, slice, synthesis, and under-default rationale fields.
@@ -21,12 +21,16 @@ Use:
21
21
  - Turn doc: `docs/implementation/example-stream/turn-docs/01-foundation.md`
22
22
  - PR: `#123`
23
23
  - Required gates: `bun test`, `bun run typecheck`
24
- - Thread default: standard speed/reasoning
24
+ - Launch environment: this thread must already be bound to the intended Codex project worktree before this prompt runs
25
+ - Launch defaults: speed `standard`, reasoning `high`, inherit_orchestrator_thread_settings `false`
26
+ - Do not run this reviewer with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the review actor
25
27
 
26
28
  ## Rules
27
29
 
30
+ - Before review or repair, verify `pwd`, `git rev-parse --show-toplevel`, and the current branch/ref match the PR branch/commit.
31
+ - Do not `cd` into the target worktree as setup or recovery. If the launch environment is wrong, stop and send a blocked callback to the orchestrator.
28
32
  - Be ambitious about structural simplification.
29
- - Use reviewer and CI verification subagents when useful.
33
+ - Use reviewer and CI verification subagents for review and CI evidence. If the phase is tiny enough to use fewer than the default review/CI agents, record why in the turn doc.
30
34
  - Own CI through green, repaired-and-green, unavailable-with-evidence, or blocked-with-cause.
31
35
  - Apply safe in-scope repairs when assigned.
32
36
  - Update the existing Markdown turn doc.
@@ -16,9 +16,14 @@ Start from:
16
16
  - Orchestrator launches a selector subagent to select exactly one next ready Beads child issue before the first worker.
17
17
  - Continue phase-by-phase until the epic is complete, blocked, interrupted, or review/CI is unresolved.
18
18
  - Only the orchestrator creates implementation and review threads.
19
- - Worker and reviewer threads default to standard speed/reasoning unless Beads metadata says otherwise.
19
+ - Implementation and review threads must be created in the intended Codex project worktree using first-class thread environment control. Do not launch a generic thread and ask it to `cd` into the worktree.
20
+ - Selector, implementation, review, and closeout-selector threads launch with explicit actor settings: `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false`, unless Beads metadata overrides that actor.
21
+ - Do not inherit current UI settings, recent Codex thread defaults, parent/orchestrator settings, `fast`, or `xhigh` unless Beads metadata explicitly names that value for the actor being launched.
20
22
  - Worker and reviewer prompt text must include the exact orchestrator thread id `THREAD_ORCHESTRATOR_ID` as callback target.
23
+ - Worker and reviewer prompt text lists the expected repo root/worktree and branch/ref for verification only. A child that starts in the wrong environment blocks and calls back instead of self-relocating.
21
24
  - After launching a worker or reviewer, wait for its single callback; do not repeatedly read, monitor, summarize, or status-check the child thread.
25
+ - Implementation threads are swarm-first for non-trivial phases: 8-20 scout agents, 8-16 slice-plan agents, and 8-16 implementation-helper agents before broad edits.
26
+ - Implementation threads synthesize swarm reports into the turn doc, integrate helper output coherently, and include `swarm_summary` in the callback.
22
27
  - Implementation threads call back exactly once when PR-ready or blocked.
23
28
  - Implementation callbacks echo `orchestrator_thread_id` and include `source_thread_id`.
24
29
  - Implementation threads do not create review threads.
@@ -33,4 +38,4 @@ Start from:
33
38
 
34
39
  ## Start Prompt
35
40
 
36
- Run the Example Stream dirtyloop with workflow `orchestrator-callback`. Use Beads epic `example-epic` as canonical. Read `docs/implementation/example-stream/IMPLEMENT.md` and `docs/implementation/example-stream/loop-state.md`, launch a selector subagent to select one next ready Beads child issue, create an implementation thread at standard speed with the full linked phase doc and exact callback target `THREAD_ORCHESTRATOR_ID` in the prompt text, then wait for an implementation callback that echoes `orchestrator_thread_id` and includes `source_thread_id` without repeatedly reading or monitoring the worker thread. Create a review thread at standard speed that uses `thermo-nuclear-code-quality-review` and owns CI, then wait for its single callback the same way. After the review callback reports concrete CI state and echoes the same callback target, launch a closeout-selector subagent to verify closeout and select stop or at most one next phase. Apply Beads and loop-state updates only from the orchestrator. Do not let worker threads create review threads. Continue to the next selected phase unless the epic is complete, blocked, interrupted, or review/CI is unresolved.
41
+ Run the Example Stream dirtyloop with workflow `orchestrator-callback`. Use Beads epic `example-epic` as canonical. Read `docs/implementation/example-stream/IMPLEMENT.md` and `docs/implementation/example-stream/loop-state.md`, launch a selector subagent with `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` to select one next ready Beads child issue, create an implementation thread in the intended Codex project worktree with those same explicit defaults, the full linked phase doc, exact callback target `THREAD_ORCHESTRATOR_ID` in the prompt text, and expected repo root/worktree plus branch/ref for verification. The implementation thread must block and call back if its launch environment is wrong; it must not self-relocate with `cd`. The implementation thread must run 8-20 scout agents, 8-16 slice-plan agents, and 8-16 implementation-helper agents for non-trivial phases, synthesize their reports into one coherent slice plan, integrate helper output, and include `swarm_summary` in its callback. Wait for an implementation callback that echoes `orchestrator_thread_id` and includes `source_thread_id` without repeatedly reading or monitoring the worker thread. Create a review thread in the intended Codex project worktree with those same explicit defaults that uses `thermo-nuclear-code-quality-review`, verifies repo root/worktree plus branch/ref before review or repair, owns CI, and blocks with callback if its launch environment is wrong. After the review callback reports concrete CI state and echoes the same callback target, launch a closeout-selector subagent with those same explicit defaults to verify closeout and select stop or at most one next phase. Do not inherit current UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the actor being launched. Apply Beads and loop-state updates only from the orchestrator. Do not let worker threads create review threads. Continue to the next selected phase unless the epic is complete, blocked, interrupted, or review/CI is unresolved.
@@ -6,6 +6,14 @@ Canonical tracker: Beads epic `example-epic`
6
6
 
7
7
  Mission: select at most one next ready Beads phase for the orchestrator.
8
8
 
9
+ Launch defaults:
10
+
11
+ - speed: `standard`
12
+ - reasoning: `high`
13
+ - inherit_orchestrator_thread_settings: `false`
14
+
15
+ Do not run this selector with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the selector actor.
16
+
9
17
  Read:
10
18
 
11
19
  - Beads epic `example-epic`
@@ -25,4 +33,3 @@ Rules:
25
33
  - If no phase is ready or the state is ambiguous, report `blocked` with evidence.
26
34
 
27
35
  Return a compact report matching `schemas/swarm-report.schema.json` with `mission: "selector"`.
28
-
@@ -13,6 +13,8 @@ Selected by selector subagent `THREAD_SELECTOR_ID` after `bd ready` showed `exam
13
13
  ## Implementation Log
14
14
 
15
15
  - Implementation thread `THREAD_IMPLEMENTATION_ID` created with orchestrator callback target `THREAD_ORCHESTRATOR_ID`.
16
+ - Worker launched 12 scout agents, 8 slice-plan agents, and 10 implementation-helper agents.
17
+ - Worker synthesized swarm reports into five file-group slices, integrated helper output, and resolved final test wiring in the main worker thread.
16
18
  - Worker created branch `example-stream/01-foundation`.
17
19
  - Worker opened PR `#123`.
18
20
 
@@ -31,6 +33,14 @@ Selected by selector subagent `THREAD_SELECTOR_ID` after `bd ready` showed `exam
31
33
  "turn_doc": "docs/implementation/example-stream/turn-docs/01-foundation.md",
32
34
  "local_gates": ["bun test: passed"],
33
35
  "changed_files": ["src/reporting/model.ts", "src/reporting/model.test.ts"],
36
+ "swarm_summary": {
37
+ "scout_agents": 12,
38
+ "slice_plan_agents": 8,
39
+ "implementation_helper_agents": 10,
40
+ "slice_count": 5,
41
+ "synthesis": "Scout findings were collapsed into five file-group slices; helper outputs were integrated by the worker before PR.",
42
+ "used_less_than_default_reason": null
43
+ },
34
44
  "blockers": [],
35
45
  "context_to_keep": ["The new model boundary is report-in/report-out and does not know UI concerns."]
36
46
  }
@@ -12,3 +12,4 @@ main coordinator thread
12
12
  ```
13
13
 
14
14
  Beads is canonical. Subagents are bounded and disposable. The main thread owns loop state, branch/PR state, integration, and closeout. Broad implementation starts only after a mass subagent slice plan.
15
+ Every phase uses selector, scout, slice-plan, implementation-helper, reviewer, and CI swarms unless the coordinator records an explicit tiny-phase exception in the turn doc before implementation.
@@ -23,7 +23,7 @@ Replace an old reporting path with a simpler evidence-backed implementation whil
23
23
 
24
24
  The main coordinator thread owns integration, branch state, PR state, Beads updates, and closeout.
25
25
 
26
- Subagents are bounded swarms:
26
+ Every phase uses bounded swarms:
27
27
 
28
28
  - selector swarm: 4-8 agents
29
29
  - scout swarm: 8-20 agents
@@ -34,7 +34,7 @@ Subagents are bounded swarms:
34
34
 
35
35
  Subagents split the phase into slices, inspect, prepare implementation guidance or patches, review, verify, and report. They do not own loop state.
36
36
 
37
- The coordinator runs a slice planning swarm before broad implementation. Direct coordinator implementation is limited to synthesis, integration, glue, conflicts, final repairs, and Beads/PR closeout.
37
+ The coordinator runs a slice planning swarm before implementation. Direct coordinator implementation is limited to synthesis, integration, glue, conflicts, final repairs, and Beads/PR closeout. If a phase is tiny enough to use fewer than the default per-phase swarms, the coordinator records the reason in the turn doc before implementation.
38
38
 
39
39
  ## Phase Ledger
40
40
 
@@ -10,13 +10,14 @@ Canonical tracker: Beads epic `example-epic`
10
10
  - Do not create separate Codex worker or reviewer threads.
11
11
  - Continue phase-by-phase until the epic is complete, blocked, interrupted, or review/CI is unresolved.
12
12
  - The main thread owns integration, branch state, PR state, Beads updates, and closeout.
13
- - Use bounded selector/scout/slice/implementation-helper/reviewer/CI subagent swarms.
14
- - Use 8+ subagents by default for broad scout, slice, implementation-helper, and review work.
15
- - Run a slice planning swarm before broad implementation.
13
+ - For every phase, use selector, scout, slice-plan, implementation-helper, reviewer, and CI subagent swarms.
14
+ - Default per-phase sizes: selector 4-8 agents, scout 8-20 agents, slice-plan 8-16 agents, implementation-helper 8-16 agents, reviewer 8-20 agents, and CI verification 4-12 agents.
15
+ - If a phase is tiny enough to use fewer than the default per-phase swarms, record why in the turn doc before implementation.
16
+ - Run a slice planning swarm before implementation.
16
17
  - Reviewer agents use `thermo-nuclear-code-quality-review`.
17
18
  - Reviewer and CI verification agents own CI evidence.
18
19
  - Update the existing Markdown turn doc.
19
20
 
20
21
  ## Start Prompt
21
22
 
22
- Run the Example Stream dirtyloop with workflow `single-thread-subagent`. Use Beads epic `example-epic` as canonical. Read `docs/implementation/example-stream/IMPLEMENT.md` and `docs/implementation/example-stream/loop-state.md`, select one next ready Beads child issue, use mass subagent swarms for selector/scout/slice/implementation-helper/review/CI work, synthesize the slice plan before broad implementation, integrate only the selected phase in the main thread, update the existing Markdown turn doc, update Beads first, then update `loop-state.md`. Continue to the next ready phase unless the epic is complete, blocked, interrupted, or review/CI is unresolved.
23
+ Run the Example Stream dirtyloop with workflow `single-thread-subagent`. Use Beads epic `example-epic` as canonical. Read `docs/implementation/example-stream/IMPLEMENT.md` and `docs/implementation/example-stream/loop-state.md`, select one next ready Beads child issue, use per-phase mass subagent swarms for selector/scout/slice-plan/implementation-helper/review/CI work, synthesize the slice plan before implementation, integrate only the selected phase in the main thread, update the existing Markdown turn doc, update Beads first, then update `loop-state.md`. If a phase is tiny enough to use fewer than the default per-phase swarms, record why in the turn doc before implementation. Continue to the next ready phase unless the epic is complete, blocked, interrupted, or review/CI is unresolved.
@@ -11,11 +11,11 @@ Selected by the main coordinator after Beads showed `example-epic.1` ready.
11
11
  ## Subagent Swarms
12
12
 
13
13
  - Selector swarm confirmed no dependencies.
14
- - Scout swarm checked old reporting behavior.
15
- - Slice planning swarm split implementation into `slice-model-boundary`, `slice-tests`, and `slice-adapter-cleanup`.
16
- - Implementation helper swarm prepared patch guidance for each slice.
17
- - Reviewer swarm used `thermo-nuclear-code-quality-review`.
18
- - CI verification swarm resolved gate evidence.
14
+ - Scout swarm used 12 agents to check old reporting behavior, likely files, tests, and integration risks.
15
+ - Slice planning swarm used 8 agents to split implementation into `slice-model-boundary`, `slice-tests`, and `slice-adapter-cleanup`.
16
+ - Implementation helper swarm used 10 agents to prepare patch guidance for each slice.
17
+ - Reviewer swarm used 12 agents with `thermo-nuclear-code-quality-review`.
18
+ - CI verification swarm used 4 agents to resolve gate evidence.
19
19
 
20
20
  ## Implementation Log
21
21
 
@@ -438,7 +438,7 @@
438
438
  <div class="workflow">
439
439
  <article class="workflow-card">
440
440
  <h3>single-thread-subagent</h3>
441
- <p>One visible coordinator owns loop state, integration, PRs, and closeout. Mass subagent swarms handle scouting, slice planning, implementation help, review, and CI.</p>
441
+ <p>One visible coordinator owns loop state, integration, PRs, and closeout. Every phase uses mass selector, scout, slice-plan, implementation-helper, review, and CI swarms unless a tiny-phase exception is recorded.</p>
442
442
  <div class="flow">
443
443
  <div class="node">
444
444
  <b>1</b>
@@ -446,7 +446,7 @@
446
446
  </div>
447
447
  <div class="node">
448
448
  <b>2</b>
449
- <div><strong>Mass swarms split the phase</strong><span>Scout, slice, implementation-helper, reviewer, and CI agents return compact reports.</span></div>
449
+ <div><strong>Per-phase swarms split the phase</strong><span>Selector, scout, slice-plan, implementation-helper, reviewer, and CI agents return compact reports.</span></div>
450
450
  </div>
451
451
  <div class="node">
452
452
  <b>3</b>
@@ -457,7 +457,7 @@
457
457
 
458
458
  <article class="workflow-card callback">
459
459
  <h3>orchestrator-callback</h3>
460
- <p>The original loop shape. A main orchestrator delegates phase gates to selector subagents, creates standard-speed implementation and review threads with concrete callback targets, waits without monitoring, then advances after validated callbacks and closeout reports.</p>
460
+ <p>The original loop shape. A main orchestrator delegates phase gates to selector subagents, creates child threads with explicit standard speed, high reasoning, and no inherited settings, requires swarm-first implementation workers, waits without monitoring, then advances after validated callbacks and closeout reports.</p>
461
461
  <div class="flow">
462
462
  <div class="node callback">
463
463
  <b>1</b>
@@ -465,7 +465,7 @@
465
465
  </div>
466
466
  <div class="node callback">
467
467
  <b>2</b>
468
- <div><strong>Implementation thread opens PR</strong><span>Worker uses the exact callback id, updates the turn doc, and calls back once.</span></div>
468
+ <div><strong>Implementation thread swarms</strong><span>Worker runs scout, slice-plan, and implementation-helper swarms, then integrates one coherent PR.</span></div>
469
469
  </div>
470
470
  <div class="node callback">
471
471
  <b>3</b>
@@ -500,7 +500,7 @@
500
500
  <tr>
501
501
  <td>Implementation</td>
502
502
  <td>Mass subagents split and assist; coordinator integrates glue, conflicts, and final repairs.</td>
503
- <td>Implementation thread created by orchestrator with exact callback target and standard defaults.</td>
503
+ <td>Implementation thread created by orchestrator in the intended Codex project worktree with exact callback target and standard defaults.</td>
504
504
  </tr>
505
505
  <tr>
506
506
  <td>Review</td>
@@ -580,7 +580,7 @@ Repo: .
580
580
  Stream slug: example-stream
581
581
  Epic title: Example stream migration
582
582
  Run policy: until complete; use --once only for one-shot operation
583
- Thread defaults: implementation standard, review standard
583
+ Thread defaults: selector/implementation/review/closeout-selector speed standard, reasoning high, no inherit
584
584
  Quality gates: bun test, bun run typecheck, targeted browser QA
585
585
  Branch/PR policy: one active implementation PR at a time</code></pre>
586
586
  </section>
@@ -52,12 +52,16 @@ Epic metadata must include:
52
52
  "branch_pr_policy": "...",
53
53
  "quality_gates": ["..."],
54
54
  "thread_defaults": {
55
- "implementation": { "speed": "standard" },
56
- "review": { "speed": "standard" }
55
+ "selector": { "speed": "standard", "reasoning": "high", "inherit_orchestrator_thread_settings": false },
56
+ "implementation": { "speed": "standard", "reasoning": "high", "inherit_orchestrator_thread_settings": false },
57
+ "review": { "speed": "standard", "reasoning": "high", "inherit_orchestrator_thread_settings": false },
58
+ "closeout_selector": { "speed": "standard", "reasoning": "high", "inherit_orchestrator_thread_settings": false }
57
59
  }
58
60
  }
59
61
  ```
60
62
 
63
+ Thread defaults are actor-specific. Do not use `inherit`, current UI settings, the parent/orchestrator thread setting, or recent Codex thread defaults as the source of child-thread speed or reasoning. `fast` speed and `xhigh` reasoning are allowed only when the loop metadata explicitly names that value for that actor.
64
+
61
65
  For `orchestrator-callback`, add:
62
66
 
63
67
  ```json
@@ -75,6 +79,15 @@ For `orchestrator-callback`, add:
75
79
  "between_phase_closeout_selector_subagent": true,
76
80
  "selector_report_schema": "schemas/swarm-report.schema.json",
77
81
  "orchestrator_only_mutates_beads": true
82
+ },
83
+ "implementation_swarm_policy": {
84
+ "requires_swarm_first_for_non_trivial_phases": true,
85
+ "target_scout_agents": "8-20",
86
+ "target_slice_plan_agents": "8-16",
87
+ "target_implementation_helper_agents": "8-16",
88
+ "requires_slice_plan_before_broad_edits": true,
89
+ "lead_worker_role": "synthesize-integrate-own-pr",
90
+ "callback_requires_swarm_summary": true
78
91
  }
79
92
  }
80
93
  ```
@@ -85,19 +98,22 @@ For `single-thread-subagent`, add:
85
98
  {
86
99
  "swarm_policy": {
87
100
  "mode": "mass-subagent",
101
+ "requires_per_phase_swarms": true,
88
102
  "min_parallel_agents": 8,
103
+ "target_selector_agents": "4-8",
89
104
  "target_scout_agents": "8-20",
90
- "target_slice_agents": "8-16",
105
+ "target_slice_plan_agents": "8-16",
91
106
  "target_implementation_helper_agents": "8-16",
92
107
  "target_review_agents": "8-20",
93
108
  "target_ci_agents": "4-12",
94
109
  "requires_slice_plan_before_implementation": true,
110
+ "tiny_phase_exception_requires_turn_doc_reason": true,
95
111
  "coordinator_direct_implementation": "integration-only"
96
112
  }
97
113
  }
98
114
  ```
99
115
 
100
- Phase metadata must include phase number, phase doc, turn doc, completion criteria, quality gates, branch/PR instructions, and either callback/selector target data or swarm slice policy for the selected workflow.
116
+ Phase metadata must include phase number, phase doc, turn doc, completion criteria, quality gates, branch/PR instructions, and either callback/selector/implementation-swarm data or swarm slice policy for the selected workflow.
101
117
 
102
118
  ## Selection
103
119
 
@@ -13,9 +13,10 @@ Required:
13
13
  - epic title
14
14
  - workflow
15
15
  - run policy
16
- - thread defaults
16
+ - actor-specific thread defaults
17
17
  - callback policy for `orchestrator-callback`
18
18
  - swarm policy for `single-thread-subagent`
19
+ - implementation swarm policy for `orchestrator-callback`
19
20
  - quality gates
20
21
  - branch/PR policy
21
22
  - selector policy for `orchestrator-callback`
@@ -26,10 +27,11 @@ Ask only for missing decisions. Prefer these defaults when the user has not spec
26
27
 
27
28
  - run policy: continue until epic complete, blocked, interrupted, or review/CI unresolved
28
29
  - one-shot mode: off unless the user says `run once` or `--once`
29
- - worker/reviewer speed: standard
30
+ - orchestrator-callback child threads: `speed: standard`, `reasoning: high`, `inherit_orchestrator_thread_settings: false`
30
31
  - orchestrator-callback wait policy: callback-wait, no active child-thread monitoring, 30 minute sparse fallback heartbeat only when overdue or liveness is uncertain
31
32
  - orchestrator-callback selector policy: selector subagent before the first worker, closeout-selector subagent between phases
32
- - single-thread-subagent swarm mode: mass-subagent, minimum 8 parallel agents for broad scout/slice/review work
33
+ - orchestrator-callback implementation swarm policy: swarm-first for non-trivial phases with 8-20 scouts, 8-16 slice-plan agents, and 8-16 implementation-helper agents
34
+ - single-thread-subagent swarm mode: per-phase mass-subagent, selector 4-8, scout 8-20, slice-plan 8-16, implementation-helper 8-16, review 8-20, CI 4-12
33
35
 
34
36
  ## Steps
35
37
 
@@ -45,11 +47,14 @@ Ask only for missing decisions. Prefer these defaults when the user has not spec
45
47
  - Completion criterion: every plan requirement maps to one phase or an explicit follow-up.
46
48
 
47
49
  3. Normalize loop metadata.
48
- - Record workflow, run policy, branch/PR policy, quality gates, and thread defaults.
50
+ - Record workflow, run policy, branch/PR policy, quality gates, and actor-specific thread defaults.
51
+ - For `orchestrator-callback`, record thread defaults for selector, implementation, review, and closeout-selector actors. Default each actor to `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless the user explicitly chose an actor-specific override.
52
+ - For `orchestrator-callback`, do not let child threads inherit current UI settings, recent Codex thread defaults, or orchestrator-thread speed/reasoning. `fast` speed and `xhigh` reasoning require explicit Beads metadata for that actor.
49
53
  - For `orchestrator-callback`, record callback policy: concrete orchestrator thread id required in prompts and callback payloads, source thread id required in callback payloads, callback-wait behavior, no active child-thread monitoring, heartbeat interval, and fallback-only polling.
50
54
  - For `orchestrator-callback`, record selector policy: initial selector subagent required, between-phase closeout-selector subagent required, selector reports use `swarm-report`, and only the orchestrator mutates Beads or advances the loop.
51
- - For `single-thread-subagent`, record swarm policy: mass-subagent mode, minimum parallel agents, scout/slice/implementation-helper/review/CI swarm sizes, mandatory slice plan before implementation, and coordinator-direct-implementation limits.
52
- - Completion criterion: the loop can be validated from Beads metadata before any worker, reviewer, or broad implementation work starts.
55
+ - For `orchestrator-callback`, record implementation swarm policy: non-trivial phases require 8-20 scout agents, 8-16 slice-plan agents, 8-16 implementation-helper agents, pre-edit slice-plan synthesis, coherent lead-worker integration, and implementation callback `swarm_summary`.
56
+ - For `single-thread-subagent`, record swarm policy: per-phase mass-subagent mode, selector/scout/slice-plan/implementation-helper/review/CI swarm sizes, mandatory slice plan before implementation, tiny-phase exception rationale, and coordinator-direct-implementation limits.
57
+ - Completion criterion: the loop can be validated from Beads metadata before any worker, reviewer, or implementation work starts.
53
58
 
54
59
  4. Create Beads state.
55
60
  - Create or update the epic.
@@ -71,7 +76,7 @@ Ask only for missing decisions. Prefer these defaults when the user has not spec
71
76
  6. Generate the run prompt.
72
77
  - Save it as `docs/implementation/<stream>/prompts/run-loop.md`.
73
78
  - Include the selected workflow name.
74
- - Include Beads epic id, run policy, phase-doc location, turn-doc rules, review skill, CI ownership, thread defaults, selector gates, callback/slice preflight rules, and storyboard requirements.
79
+ - Include Beads epic id, run policy, phase-doc location, turn-doc rules, review skill, CI ownership, actor-specific thread defaults, selector gates, implementation swarm policy, callback/slice preflight rules, and storyboard requirements.
75
80
  - Completion criterion: the user can paste the generated prompt into Codex to start the loop.
76
81
 
77
82
  ## Output Contract
@@ -11,7 +11,7 @@ Do not mutate files, Beads, branches, PRs, or threads while answering help.
11
11
  Every dirtyloop uses:
12
12
 
13
13
  - Beads as canonical tracker
14
- - typed loop metadata on Beads for workflow, run policy, callback policy, thread defaults, swarm policy, quality gates, and branch/PR policy
14
+ - typed loop metadata on Beads for workflow, run policy, callback policy, actor-specific thread defaults, swarm policy, quality gates, and branch/PR policy
15
15
  - phase docs linked from Beads child issues
16
16
  - repo-relative paths in generated docs and prompts
17
17
  - one Markdown turn doc per phase
@@ -40,7 +40,7 @@ Required inputs:
40
40
  - epic title
41
41
  - workflow
42
42
  - run policy
43
- - thread defaults
43
+ - actor-specific thread defaults
44
44
  - quality gates
45
45
  - branch/PR policy
46
46
 
@@ -109,7 +109,7 @@ main coordinator thread
109
109
  -> coordinator closeout
110
110
  ```
111
111
 
112
- Use it for CLI-friendly or context-controlled loops where separate callback threads are not desired. Single-thread means one visible coordinator, not solo implementation; broad phases should use 8+ subagents and a slice plan before implementation.
112
+ Use it for CLI-friendly or context-controlled loops where separate callback threads are not desired. Single-thread means one visible coordinator, not solo implementation; every phase uses selector, scout, slice-plan, implementation-helper, reviewer, and CI swarms unless a tiny-phase exception is recorded in the turn doc before implementation.
113
113
 
114
114
  ### `orchestrator-callback`
115
115
 
@@ -128,7 +128,9 @@ orchestrator thread
128
128
  -> orchestrator applies closeout and continues or stops
129
129
  ```
130
130
 
131
- Only the orchestrator creates implementation and review threads. Worker threads do not create review threads. Worker and reviewer prompts must contain the concrete orchestrator thread id as callback target. Phase selection is delegated: initial selection uses a selector subagent, and between-phase closeout/selection uses a closeout-selector subagent. After launching a worker or reviewer, the orchestrator waits for its single callback instead of repeatedly reading or monitoring the child thread.
131
+ Only the orchestrator creates implementation and review threads. It must create them in the intended Codex project worktree using first-class thread environment control; launching a generic thread and telling it to `cd` into the worktree is a workflow violation. Worker threads do not create review threads. Worker and reviewer prompts must contain the concrete orchestrator thread id as callback target and must list expected repo root/worktree plus branch/ref for verification. A child that starts in the wrong environment blocks and calls back instead of self-relocating. Phase selection is delegated: initial selection uses a selector subagent, and between-phase closeout/selection uses a closeout-selector subagent. Selector, implementation, review, and closeout-selector threads launch with explicit actor settings: `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false`, unless Beads metadata overrides that actor. Current UI, recent thread, parent/orchestrator, `fast`, and `xhigh` settings do not count as defaults. After launching a worker or reviewer, the orchestrator waits for its single callback instead of repeatedly reading or monitoring the child thread.
132
+
133
+ Implementation threads are swarm-first for non-trivial phases. They run 8-20 scout agents, 8-16 slice-plan agents, and 8-16 implementation-helper agents before broad edits, synthesize the reports into one slice plan, integrate helper output coherently, and include `swarm_summary` in the implementation callback. Fewer agents require an explicit tiny-phase reason in the turn doc and callback.
132
134
 
133
135
  ## Which Workflow Should I Pick?
134
136
 
@@ -18,10 +18,14 @@ Use this branch to execute an existing dirtyloop. Continue phase-by-phase by def
18
18
 
19
19
  3. Validate launch preflight.
20
20
  - For `orchestrator-callback`, require a concrete orchestrator thread id before launching workers/reviewers. The actual worker/reviewer prompt text must name that exact id as the callback target and must not rely on phrases like `current orchestrator thread`, `this thread`, or `source thread wrapper`.
21
+ - For `orchestrator-callback`, require the orchestrator to bind each implementation/review thread to the intended Codex project worktree at thread creation time. Use the Codex project/worktree launch target or equivalent first-class thread environment control; do not launch a generic thread and tell it to `cd` into the worktree.
22
+ - For `orchestrator-callback`, worker/reviewer prompts must list the expected repo root/worktree and branch/ref as verification inputs only. The child thread must verify `pwd`, `git rev-parse --show-toplevel`, and current branch/ref before edits or review. If the launch environment is wrong, the child must send a blocked callback; it must not self-relocate with `cd` as setup or recovery.
23
+ - For `orchestrator-callback`, stop as blocked before launch when the orchestrator cannot create the child thread in the intended worktree environment. Do not rely on shell cwd, prompt discipline, or a hidden wrapper to repair a wrong thread environment after launch.
21
24
  - For `orchestrator-callback`, require callback-wait behavior: after launch, do not repeatedly read or monitor the child thread while waiting for the single callback. Sparse fallback heartbeat is allowed only when the callback is overdue or liveness is uncertain.
22
- - For `orchestrator-callback`, require worker/reviewer thread defaults to be explicit, defaulting to standard speed/reasoning when metadata does not override it.
23
- - For `single-thread-subagent`, require a mass-subagent slice/scout plan before broad implementation. The coordinator may perform integration and final repairs, but it must not do most broad discovery or implementation itself.
24
- - Completion criterion: the workflow can start without relying on inherited thread settings, vague callback targets, or solo coordinator implementation.
25
+ - For `orchestrator-callback`, require explicit launch defaults for every child actor before launch: selector, implementation, review, and closeout-selector. Defaults are `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads metadata overrides that actor.
26
+ - For `orchestrator-callback`, reject inherited launch settings. Do not use current UI settings, recent Codex thread defaults, parent/orchestrator settings, `fast`, or `xhigh` unless Beads metadata explicitly names that value for the actor being launched.
27
+ - For `single-thread-subagent`, require per-phase selector, scout, slice-plan, implementation-helper, review, and CI swarms before implementation and closeout. The coordinator may perform integration and final repairs, but it must not do most discovery or implementation itself.
28
+ - Completion criterion: the workflow can start without relying on inherited thread settings, vague callback targets, shell cwd repair, wrong thread environments, or solo coordinator implementation.
25
29
 
26
30
  4. Run the selected workflow.
27
31
  - Follow the selected workflow reference.
@@ -1,6 +1,6 @@
1
1
  # Swarms
2
2
 
3
- dirtyloops use bounded swarms. Fan out aggressively when the phase has broad surface area, shared architecture, CI risk, or user-facing behavior. In `single-thread-subagent`, mass subagent work is mandatory for broad phases: the visible coordinator orchestrates, synthesizes, integrates, and closes out; subagents do much of the discovery, slicing, implementation analysis, review, and CI verification.
3
+ dirtyloops use bounded swarms. Fan out aggressively when the phase has shared architecture, CI risk, user-facing behavior, or any meaningful implementation surface. In `single-thread-subagent`, mass subagent work is mandatory per phase: the visible coordinator orchestrates, synthesizes, integrates, and closes out; subagents do the discovery, slicing, implementation analysis, review, and CI verification. In `orchestrator-callback`, implementation threads are also swarm-first for non-trivial phases: the worker runs scout, slice-plan, and implementation-helper swarms before broad edits, then integrates the results coherently.
4
4
 
5
5
  ## Default Sizes
6
6
 
@@ -13,7 +13,15 @@ dirtyloops use bounded swarms. Fan out aggressively when the phase has broad sur
13
13
  - CI verification swarm: 4-12 agents
14
14
  - storyboard synthesis swarm: 3-8 agents
15
15
 
16
- For `single-thread-subagent`, use at least 8 parallel agents before broad implementation unless the phase is explicitly tiny. If fewer than 8 agents are used, record the reason in the turn doc.
16
+ For `single-thread-subagent`, every phase uses per-phase swarms unless the phase is explicitly tiny. Default per-phase sizes are selector 4-8 agents, scout 8-20 agents, slice-plan 8-16 agents, implementation-helper 8-16 agents, reviewer 8-20 agents, and CI verification 4-12 agents. If fewer than the default swarms are used, record the tiny-phase reason in the turn doc before implementation.
17
+
18
+ For `orchestrator-callback`, each non-trivial implementation thread must use massive bounded swarms before broad edits:
19
+
20
+ - 8-20 scout agents across files, modules, risks, tests, and integration edges
21
+ - 8-16 slice-plan agents to propose non-overlapping implementation slices
22
+ - 8-16 implementation-helper agents assigned to slices in parallel
23
+
24
+ The implementation thread synthesizes reports into the phase turn doc, chooses the final slice plan, integrates helper output, resolves conflicts, owns gates, and owns the PR. If a phase is tiny enough to use fewer than the default agents, record the reason in the turn doc and callback `swarm_summary`.
17
25
 
18
26
  ## Bounds
19
27
 
@@ -29,9 +37,9 @@ Each subagent gets:
29
37
 
30
38
  ## Slice Planning
31
39
 
32
- For non-trivial `single-thread-subagent` phases, run a slice planning swarm before implementation. Slices should be bounded by module, file group, workflow, test surface, or risk area.
40
+ For non-trivial phases, run a slice planning swarm before implementation. Slices should be bounded by module, file group, workflow, test surface, or risk area.
33
41
 
34
- The coordinator must synthesize the slice reports before broad edits. Direct coordinator implementation is limited to integration, glue, conflict resolution, final repairs, and Beads/PR state.
42
+ The coordinator or implementation thread must synthesize the slice reports before broad edits. Direct lead-thread implementation is limited to integration, glue, conflict resolution, final repairs, and Beads/PR state.
35
43
 
36
44
  ## Report Shape
37
45
 
@@ -8,7 +8,8 @@ Use this workflow for the original loop style: a main orchestrator thread delega
8
8
  orchestrator thread
9
9
  -> selector subagent chooses the first next ready Beads phase
10
10
  -> orchestrator creates implementation thread
11
- -> implementation thread may use subagents
11
+ -> implementation thread runs massive scout/slice/helper swarms
12
+ -> implementation thread synthesizes and integrates helper output
12
13
  -> implementation thread opens PR and calls back
13
14
  -> orchestrator creates review thread
14
15
  -> review thread may use subagents
@@ -28,6 +29,7 @@ The orchestrator owns:
28
29
  - validating selector outputs before advancing the loop
29
30
  - implementation thread creation
30
31
  - review thread creation
32
+ - child thread environment binding to the intended Codex project worktree
31
33
  - concrete callback target, callback preflight, callback-wait, and sparse fallback heartbeat
32
34
  - phase closeout
33
35
  - launching the next selected phase
@@ -51,8 +53,12 @@ The closeout-selector subagent owns:
51
53
  The implementation thread owns:
52
54
 
53
55
  - exactly one selected Beads issue
54
- - branch/worktree setup assigned by the orchestrator
56
+ - working only in the repo/worktree environment already bound by the orchestrator
57
+ - verifying its repo root, worktree, and branch/ref before edits, then blocking if the launch environment is wrong
58
+ - massive bounded scout, slice-plan, and implementation-helper swarms for non-trivial phases
59
+ - coherent synthesis of swarm reports into one slice plan
55
60
  - implementation
61
+ - integration, conflict resolution, and final repair
56
62
  - local gates before PR when feasible
57
63
  - PR creation
58
64
  - updating the existing Markdown turn doc
@@ -61,6 +67,8 @@ The implementation thread owns:
61
67
  The review thread owns:
62
68
 
63
69
  - thermo-nuclear review
70
+ - working only in the repo/worktree environment already bound by the orchestrator
71
+ - verifying its repo root, worktree, and branch/ref before review or repair, then blocking if the launch environment is wrong
64
72
  - reviewer subagent swarms
65
73
  - CI inspection, diagnosis, repair, rerun, and evidence
66
74
  - updating the existing Markdown turn doc
@@ -69,7 +77,12 @@ The review thread owns:
69
77
  ## Non-Negotiable Thread Rules
70
78
 
71
79
  - Only the orchestrator creates implementation and review threads.
80
+ - The orchestrator must create implementation and review threads in the intended Codex project worktree using first-class thread environment control. Do not launch a generic thread and ask it to `cd` into the worktree.
81
+ - Worker/reviewer prompts may list the expected repo root/worktree and branch/ref for verification, but they must not use `cd` as setup or recovery. A child thread that starts in the wrong environment must send a blocked callback.
72
82
  - Implementation threads do not create review threads.
83
+ - Implementation threads must not do broad solo implementation. For non-trivial phases, they run massive bounded scout, slice-plan, and implementation-helper swarms before broad edits.
84
+ - Implementation threads synthesize all swarm reports into the existing turn doc, integrate helper output coherently, and keep final ownership of the branch, gates, PR, and callback.
85
+ - If a phase is too small for the default swarm sizes, the implementation thread records the reason in the turn doc and callback `swarm_summary`.
73
86
  - Review threads do not create follow-up implementation threads.
74
87
  - Selector subagents never implement.
75
88
  - Closeout-selector subagents never implement, review, repair, create threads, or mutate Beads.
@@ -79,7 +92,8 @@ The review thread owns:
79
92
  - After every review callback, the orchestrator must launch a closeout-selector subagent before closing the phase, stopping, or launching another implementation thread.
80
93
  - After launching a worker or reviewer, the orchestrator waits for the single callback. It does not repeatedly read, monitor, summarize, or status-check the child thread.
81
94
  - A fallback heartbeat is allowed only when the callback is overdue or liveness is uncertain; do not use heartbeat as routine polling.
82
- - Implementation and review threads default to standard speed/reasoning unless Beads metadata explicitly overrides it.
95
+ - Selector, implementation, review, and closeout-selector threads default to `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads metadata explicitly overrides that actor.
96
+ - Before launch, the orchestrator must verify the actual child-thread launch settings or prompt text spell out the actor's speed, reasoning, and non-inheritance. Current UI settings, recent Codex defaults, parent/orchestrator settings, `fast`, and `xhigh` do not count as valid defaults unless the Beads metadata explicitly names them for that actor.
83
97
  - Before launch, the orchestrator must verify the actual worker/reviewer prompt text includes the exact orchestrator thread id as callback target. Do not launch if the prompt relies on generic wording such as `current orchestrator thread`, `this thread`, or a hidden wrapper.
84
98
 
85
99
  ## Selector Reports
@@ -139,6 +153,14 @@ Payload:
139
153
  "turn_doc": "...",
140
154
  "local_gates": ["..."],
141
155
  "changed_files": ["..."],
156
+ "swarm_summary": {
157
+ "scout_agents": 12,
158
+ "slice_plan_agents": 8,
159
+ "implementation_helper_agents": 10,
160
+ "slice_count": 5,
161
+ "synthesis": "Scout findings were collapsed into five file-group slices; helper outputs were integrated by the worker.",
162
+ "used_less_than_default_reason": null
163
+ },
142
164
  "blockers": [],
143
165
  "context_to_keep": []
144
166
  }
@@ -22,11 +22,12 @@ main coordinator thread
22
22
  - The main thread owns branch state, integration, PR state, Beads updates, and closeout.
23
23
  - Subagents inspect, compare, critique, slice the phase, prepare implementation guidance or patches, verify, and report.
24
24
  - Subagents do not advance loop state.
25
- - Use 8+ agents by default for broad scout, slice, implementation-helper, and review work; 8-20 agents is normal when the phase has meaningful surface area.
26
- - Before broad implementation, launch a slice planning swarm and record the synthesized slice plan in the turn doc.
27
- - For non-trivial phases, create or record intra-phase implementation slices. Use ephemeral Beads child issues when supported and useful; otherwise record the slices in the turn doc.
28
- - The coordinator may implement glue, integration, conflict resolution, and final repairs. If it performs most broad discovery or implementation itself, the loop has violated this workflow.
29
- - If fewer than 8 subagents are used for a broad phase, record the reason in the turn doc.
25
+ - Every phase uses per-phase swarms: selector, scout, slice-plan, implementation-helper, reviewer, and CI verification.
26
+ - Default per-phase sizes: selector 4-8 agents, scout 8-20 agents, slice-plan 8-16 agents, implementation-helper 8-16 agents, reviewer 8-20 agents, and CI verification 4-12 agents.
27
+ - Before implementation, launch a slice planning swarm and record the synthesized slice plan in the turn doc.
28
+ - Create or record intra-phase implementation slices. Use ephemeral Beads child issues when supported and useful; otherwise record the slices in the turn doc.
29
+ - The coordinator may implement glue, integration, conflict resolution, and final repairs. If it performs most discovery or implementation itself, the loop has violated this workflow.
30
+ - If a phase is tiny enough to use fewer than the default per-phase swarms, record the reason in the turn doc before implementation.
30
31
 
31
32
  ## Slice Contract
32
33
 
@@ -42,4 +43,4 @@ Each implementation slice has:
42
43
 
43
44
  ## Completion Criterion
44
45
 
45
- The main coordinator has selected one phase, received and synthesized scout/slice/implementation-helper reports, integrated one phase, received reviewer/CI subagent reports, updated the existing turn doc, updated Beads, and either continued to the next ready phase or stopped with an allowed stop reason.
46
+ The main coordinator has selected one phase, received and synthesized selector/scout/slice/implementation-helper reports, integrated one phase, received reviewer/CI subagent reports, recorded any tiny-phase swarm exception, updated the existing turn doc, updated Beads, and either continued to the next ready phase or stopped with an allowed stop reason.
@@ -3,7 +3,7 @@
3
3
  "title": "ImplementationCallback",
4
4
  "type": "object",
5
5
  "additionalProperties": false,
6
- "required": ["type", "orchestrator_thread_id", "source_thread_id", "phase_issue_id", "status", "branch", "pr", "commits", "turn_doc", "local_gates", "changed_files", "blockers", "context_to_keep"],
6
+ "required": ["type", "orchestrator_thread_id", "source_thread_id", "phase_issue_id", "status", "branch", "pr", "commits", "turn_doc", "local_gates", "changed_files", "swarm_summary", "blockers", "context_to_keep"],
7
7
  "properties": {
8
8
  "type": { "const": "implementation-callback" },
9
9
  "orchestrator_thread_id": { "type": "string", "minLength": 1 },
@@ -25,6 +25,19 @@
25
25
  "type": "array",
26
26
  "items": { "type": "string" }
27
27
  },
28
+ "swarm_summary": {
29
+ "type": "object",
30
+ "additionalProperties": false,
31
+ "required": ["scout_agents", "slice_plan_agents", "implementation_helper_agents", "slice_count", "synthesis", "used_less_than_default_reason"],
32
+ "properties": {
33
+ "scout_agents": { "type": "integer", "minimum": 0 },
34
+ "slice_plan_agents": { "type": "integer", "minimum": 0 },
35
+ "implementation_helper_agents": { "type": "integer", "minimum": 0 },
36
+ "slice_count": { "type": "integer", "minimum": 0 },
37
+ "synthesis": { "type": "string" },
38
+ "used_less_than_default_reason": { "type": ["string", "null"] }
39
+ }
40
+ },
28
41
  "blockers": {
29
42
  "type": "array",
30
43
  "items": { "type": "string" }
@@ -13,7 +13,7 @@ This stream is driven by Beads. These docs are execution context and resume aids
13
13
  ## Sources Of Truth
14
14
 
15
15
  - Beads epic: `{{EPIC_ID}}`
16
- - Beads loop metadata: workflow, run policy, branch/PR policy, quality gates, callback/thread defaults, and swarm policy
16
+ - Beads loop metadata: workflow, run policy, branch/PR policy, quality gates, callback policy, actor-specific thread defaults, and swarm policy
17
17
  - Roadmap: `docs/implementation/{{STREAM_SLUG}}/00-roadmap.md`
18
18
  - Loop state mirror: `docs/implementation/{{STREAM_SLUG}}/loop-state.md`
19
19
  - Phase docs linked from Beads child issues
@@ -30,7 +30,8 @@ This stream is driven by Beads. These docs are execution context and resume aids
30
30
  - File Beads follow-ups instead of widening the selected phase.
31
31
  - Update Beads first, then update `loop-state.md`.
32
32
  - Use the workflow's required subagent swarms.
33
- - Worker and reviewer threads default to standard speed/reasoning unless Beads loop metadata explicitly overrides it.
33
+ - Orchestrator-callback child threads default to `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false` unless Beads loop metadata explicitly overrides that actor.
34
+ - Orchestrator-callback implementation/review threads must be created in the intended Codex project worktree. A child that starts in the wrong repo/worktree blocks and calls back instead of self-relocating.
34
35
 
35
36
  ## Review And CI
36
37
 
@@ -23,7 +23,9 @@ Start from:
23
23
  - Use the workflow's required large bounded subagent swarms.
24
24
  - Reviewer agents must use `thermo-nuclear-code-quality-review`.
25
25
  - Reviewer and CI verification agents own CI.
26
- - Worker and reviewer threads default to standard speed/reasoning unless Beads loop metadata explicitly overrides it.
26
+ - Orchestrator-callback child threads must launch with explicit actor defaults: `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false`, unless Beads metadata overrides that actor.
27
+ - Orchestrator-callback implementation/review threads must be created in the intended Codex project worktree using first-class thread environment control. Worker/reviewer prompts verify repo/worktree and branch/ref; they do not repair a wrong launch environment with shell cwd changes.
28
+ - Do not inherit child-thread speed or reasoning from the current UI, recent Codex thread defaults, or the orchestrator thread.
27
29
  - Update the existing Markdown turn doc.
28
30
  - Update Beads first, then update `loop-state.md`.
29
31
  - Do not widen the selected phase.
@@ -6,6 +6,14 @@ Canonical tracker: Beads epic `{{EPIC_ID}}`
6
6
 
7
7
  Mission: verify the just-reviewed phase can be closed out, then recommend stop or at most one next phase.
8
8
 
9
+ Launch defaults:
10
+
11
+ - speed: `standard`
12
+ - reasoning: `high`
13
+ - inherit_orchestrator_thread_settings: `false`
14
+
15
+ Do not run this closeout-selector with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the closeout-selector actor.
16
+
9
17
  Read:
10
18
 
11
19
  - Beads epic `{{EPIC_ID}}`
@@ -30,4 +38,3 @@ Rules:
30
38
  - Recommend exactly one next phase only when continuation is allowed and Beads dependencies make it ready.
31
39
 
32
40
  Return a compact report matching `schemas/swarm-report.schema.json` with `mission: "closeout-selector"`.
33
-
@@ -0,0 +1,29 @@
1
+ # Implementation Swarm Subagent Prompt: {{STREAM_NAME}}
2
+
3
+ You are an implementation swarm subagent inside an `orchestrator-callback` implementation thread.
4
+
5
+ Mission: `{{SWARM_MISSION}}`
6
+
7
+ Allowed missions:
8
+
9
+ - `scout`: inspect a bounded surface and report facts, risks, likely files, and tests
10
+ - `slice-plan`: propose non-overlapping implementation slices and integration order
11
+ - `implementation-helper`: work one assigned slice in parallel and return patch guidance, changed files, gates, and integration notes
12
+
13
+ Inputs:
14
+
15
+ - Beads issue: `{{PHASE_ISSUE_ID}}`
16
+ - Phase doc: `{{PHASE_DOC}}`
17
+ - Turn doc: `{{TURN_DOC}}`
18
+ - Slice id: `{{SLICE_ID}}`
19
+ - Assigned scope: `{{ASSIGNED_SCOPE}}`
20
+
21
+ Rules:
22
+
23
+ - Stay inside the assigned scope.
24
+ - Do not mutate Beads.
25
+ - Do not create PRs or review threads.
26
+ - Do not own loop state or callback.
27
+ - Implementation-helper agents may prepare patches or concrete edit guidance only for their assigned slice.
28
+ - Return compact structured output matching `schemas/swarm-report.schema.json`.
29
+
@@ -14,20 +14,32 @@ You must send your final callback to the exact orchestrator thread id `{{ORCHEST
14
14
  - Phase doc: `{{PHASE_DOC}}`
15
15
  - Implementation index: `{{IMPLEMENT_MD}}`
16
16
  - Turn doc: `{{TURN_DOC}}`
17
- - Branch/worktree instructions: `{{BRANCH_WORKTREE_INSTRUCTIONS}}`
18
- - Thread default: standard speed/reasoning unless the orchestrator prompt explicitly says otherwise
17
+ - Expected repo/worktree and branch/ref: `{{BRANCH_WORKTREE_INSTRUCTIONS}}`
18
+ - Launch environment: this thread must already be bound to the intended Codex project worktree before this prompt runs
19
+ - Launch defaults: speed `standard`, reasoning `high`, inherit_orchestrator_thread_settings `false`, unless Beads metadata explicitly overrides the implementation actor
20
+ - Do not run this worker with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the implementation actor
19
21
 
20
22
  ## Rules
21
23
 
24
+ - Before edits, verify `pwd`, `git rev-parse --show-toplevel`, and the current branch/ref match the expected repo/worktree and branch/ref.
25
+ - Do not `cd` into the target worktree as setup or recovery. If the launch environment is wrong, stop and send a blocked callback to the orchestrator.
22
26
  - Implement exactly this phase.
23
27
  - Do not widen scope.
24
- - Use bounded implementation/scout subagents when useful.
28
+ - Do not do broad solo implementation.
29
+ - For non-trivial phases, run massive bounded swarms before broad edits:
30
+ - 8-20 scout agents across files, modules, risks, tests, and integration edges
31
+ - 8-16 slice-plan agents to propose non-overlapping implementation slices
32
+ - 8-16 implementation-helper agents assigned to slices in parallel
33
+ - If this phase is tiny enough to use fewer than the default agents, record the reason in the turn doc and callback `swarm_summary`.
34
+ - Synthesize swarm reports into one coherent slice plan before broad edits.
35
+ - Integrate helper output yourself; own conflicts, final repairs, gates, branch state, PR state, and callback.
25
36
  - Update the existing Markdown turn doc.
26
37
  - Run local gates before PR when feasible.
27
38
  - Open or update the PR.
28
39
  - Do not create the review thread.
29
40
  - Call back exactly once to the orchestrator.
30
41
  - The callback payload must include `orchestrator_thread_id: "{{ORCHESTRATOR_THREAD_ID}}"` and your `source_thread_id`.
42
+ - The callback payload must include `swarm_summary` with scout, slice-plan, implementation-helper, slice, synthesis, and under-default rationale fields.
31
43
 
32
44
  ## Callback States
33
45
 
@@ -22,12 +22,16 @@ Use:
22
22
  - PR: `{{PR_URL_OR_ID}}`
23
23
  - Branch/commit: `{{BRANCH_OR_COMMIT}}`
24
24
  - Required gates: `{{QUALITY_GATES}}`
25
- - Thread default: standard speed/reasoning unless the orchestrator prompt explicitly says otherwise
25
+ - Launch environment: this thread must already be bound to the intended Codex project worktree before this prompt runs
26
+ - Launch defaults: speed `standard`, reasoning `high`, inherit_orchestrator_thread_settings `false`, unless Beads metadata explicitly overrides the review actor
27
+ - Do not run this reviewer with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the review actor
26
28
 
27
29
  ## Rules
28
30
 
31
+ - Before review or repair, verify `pwd`, `git rev-parse --show-toplevel`, and the current branch/ref match the PR branch/commit.
32
+ - Do not `cd` into the target worktree as setup or recovery. If the launch environment is wrong, stop and send a blocked callback to the orchestrator.
29
33
  - Be ambitious about structural simplification.
30
- - Use reviewer and CI verification subagents when useful.
34
+ - Use reviewer and CI verification subagents for review and CI evidence. If the phase is tiny enough to use fewer than the default review/CI agents, record why in the turn doc.
31
35
  - Own CI through green, repaired-and-green, unavailable-with-evidence, or blocked-with-cause.
32
36
  - Apply safe in-scope repairs when assigned by the orchestrator prompt.
33
37
  - Update the existing Markdown turn doc.
@@ -3,14 +3,17 @@
3
3
  This loop uses a main orchestrator thread plus separate implementation and review threads.
4
4
 
5
5
  - Only the orchestrator creates implementation and review threads.
6
+ - The orchestrator creates implementation and review threads in the intended Codex project worktree using first-class thread environment control. Do not launch a generic thread and ask it to `cd` into the worktree.
6
7
  - Before the first worker, the orchestrator launches a selector subagent to choose exactly one next ready Beads phase.
7
8
  - After every review callback, the orchestrator launches a closeout-selector subagent before closing the phase, stopping, or launching another worker.
8
9
  - Selector and closeout-selector subagents return `swarm-report` payloads with mission `selector` or `closeout-selector`; they do not mutate Beads, edit files, implement, review, repair, create threads, or advance the loop.
10
+ - Selector, implementation, review, and closeout-selector threads launch with explicit actor defaults: `speed: standard`, `reasoning: high`, and `inherit_orchestrator_thread_settings: false`, unless Beads metadata overrides that actor.
11
+ - Do not inherit current UI settings, recent Codex defaults, or orchestrator-thread speed/reasoning. `fast` speed and `xhigh` reasoning require explicit Beads metadata for the actor being launched.
9
12
  - The orchestrator passes its concrete thread id as the callback target.
10
13
  - Before launching a worker or reviewer, verify the actual prompt text includes that exact thread id and does not rely on generic wording like `current orchestrator thread` or `this thread`.
14
+ - Before launching a worker or reviewer, verify the child thread launch target is the intended project worktree. Prompt text may include expected repo root/worktree and branch/ref for verification only; it must not use `cd` as setup or recovery.
11
15
  - After launching a worker or reviewer, wait for its single callback. Do not repeatedly read, monitor, summarize, or status-check the child thread while waiting.
12
16
  - Use a sparse fallback heartbeat around 30 minutes only when the callback is overdue or liveness is uncertain; do not use heartbeat as routine polling.
13
- - Worker and reviewer threads default to standard speed/reasoning unless Beads loop metadata explicitly overrides it.
14
17
  - Implementation threads update the existing phase turn doc, open the PR, and call back exactly once when PR-ready or blocked.
15
18
  - Implementation callback payloads must echo `orchestrator_thread_id` and include `source_thread_id`.
16
19
  - Implementation threads do not create review threads.
@@ -19,3 +22,5 @@ This loop uses a main orchestrator thread plus separate implementation and revie
19
22
  - Review threads update the existing phase turn doc and call back exactly once when review and CI are resolved.
20
23
  - Review callback payloads must echo `orchestrator_thread_id` and include `source_thread_id`.
21
24
  - The orchestrator validates selector reports, owns Beads closeout, and launches only the selected next phase.
25
+ - Implementation threads are swarm-first for non-trivial phases: 8-20 scout agents, 8-16 slice-plan agents, and 8-16 implementation-helper agents before broad edits.
26
+ - The implementation thread synthesizes swarm reports into the existing turn doc, integrates helper output coherently, and includes `swarm_summary` in the implementation callback.
@@ -6,6 +6,14 @@ Canonical tracker: Beads epic `{{EPIC_ID}}`
6
6
 
7
7
  Mission: select at most one next ready Beads phase for the orchestrator.
8
8
 
9
+ Launch defaults:
10
+
11
+ - speed: `standard`
12
+ - reasoning: `high`
13
+ - inherit_orchestrator_thread_settings: `false`
14
+
15
+ Do not run this selector with inherited UI, recent thread, parent/orchestrator, `fast`, or `xhigh` settings unless Beads metadata explicitly overrides the selector actor.
16
+
9
17
  Read:
10
18
 
11
19
  - Beads epic `{{EPIC_ID}}`
@@ -25,4 +33,3 @@ Rules:
25
33
  - If no phase is ready or the state is ambiguous, report `blocked` with evidence.
26
34
 
27
35
  Return a compact report matching `schemas/swarm-report.schema.json` with `mission: "selector"`.
28
-
@@ -3,10 +3,11 @@
3
3
  This loop runs in one visible Codex coordinator thread. Single-thread means one coordinator, not solo implementation.
4
4
 
5
5
  - Do not create separate Codex worker or reviewer threads.
6
- - Use selector, scout, slice-planning, implementation-helper, reviewer, and CI subagent swarms inside this thread.
7
- - Use 8+ subagents by default for broad scout, slice, implementation-helper, and review work. If fewer than 8 are used for a broad phase, record why in the turn doc.
8
- - Before broad implementation, run a slice planning swarm and synthesize the slice plan into the turn doc.
6
+ - For every phase, use selector, scout, slice-planning, implementation-helper, reviewer, and CI subagent swarms inside this thread.
7
+ - Default per-phase sizes: selector 4-8 agents, scout 8-20 agents, slice-plan 8-16 agents, implementation-helper 8-16 agents, reviewer 8-20 agents, and CI verification 4-12 agents.
8
+ - If a phase is tiny enough to use fewer than the default per-phase swarms, record why in the turn doc before implementation.
9
+ - Before implementation, run a slice planning swarm and synthesize the slice plan into the turn doc.
9
10
  - The main thread owns integration, branch state, PR state, Beads updates, and closeout.
10
11
  - Subagents inspect, compare, critique, split the phase into slices, prepare implementation guidance or patches, verify, and report.
11
12
  - Subagents do not own loop state.
12
- - The coordinator may implement glue, integration, conflict resolution, and final repairs. It must not do most broad discovery or implementation itself.
13
+ - The coordinator may implement glue, integration, conflict resolution, and final repairs. It must not do most discovery or implementation itself.