docs(TASK-021): fix task-queue example IDs + document dispatch/collect/failure semantics

- prompts.rs DEFAULT_SPAWN_INSTRUCTIONS: example IDs task_1/task_2 -> "1"/"2"
  (real numeric-string IDs; old format silently produced dep_error + unblocked
  task), plus task-queue rules: root tasks with agent are never auto-dispatched,
  task_complete is what dispatches dependents, auto-dispatched agents must be
  collected, failed tasks permanently block dependents.
- architect config: optional task-queue mirroring guidance for parallel mode
  (disk task files stay the durable store; queue is in-memory).
- sisyphus config: short note on encoding dependency-shaped bursts as
  agent__task_create chains; todos remain the tracking source of truth.
This commit is contained in:
Dark-Alex-17 committed 2026-09-14 10:50:33 -06:00
1 parent 22976a79f9
commit f2d90ed7a6
3 files changed
+31 -3

No files matched your search

+14
View File
@@ -456,6 +456,20 @@ instructions: |
the task (step 5), and clean up — `git worktree remove .worktrees/task-NNN` and delete the task the task (step 5), and clean up — `git worktree remove .worktrees/task-NNN` and delete the task
branch (local + remote). branch (local + remote).
**Task-queue mirroring (optional).** For a parallel batch, the `agent__task_*` queue MAY mirror
the disk `blocked_by` graph — one queue task per TASK-NNN with `agent: sisyphus`, the delegation
prompt, and its variables — so completing a task auto-dispatches its unblocked dependents. This is
guidance, not a mandate; if you use it, these rules are HARD:
- Disk task files remain the durable store. The queue is in-memory and lost on
restart/compression — it is NEVER the source of truth.
- Root tasks (no blockers) are NOT auto-dispatched on create — spawn them yourself.
- Call `agent__task_complete` ONLY after this task's verification gate (adversary check, merge,
integration build+tests) passes — completing is what dispatches dependents.
- Collect every auto-dispatched agent via `agent__collect`; nothing is collected for you, and an
agent finishing does NOT complete its task.
- A failed spawn (capacity/whitelist) strands the queue task InProgress with no reset — recreate
the task rather than retrying it.
Phase F is UNCHANGED (same single draft PR from the run branch). Before opening it, verify no Phase F is UNCHANGED (same single draft PR from the run branch). Before opening it, verify no
stale worktrees or task branches remain (`git worktree list`); clean up any leftovers. stale worktrees or task branches remain (`git worktree list`); clean up any leftovers.
+5
View File
@@ -234,6 +234,11 @@ instructions: |
Never artificially cap at a small number. If there are 10 distinct things to find, spawn 10 agents. The system limit is the only ceiling that matters. Never artificially cap at a small number. If there are 10 distinct things to find, spawn 10 agents. The system limit is the only ceiling that matters.
For dependency-shaped bursts (explore → code → verify), `agent__task_create` chains MAY encode the
ordering — dependents with `agent`+`prompt` auto-dispatch when `agent__task_complete` unblocks them.
Same rules as direct spawning: collect every auto-dispatched agent via `agent__collect`, and an agent
finishing does NOT complete its task — call `agent__task_complete` yourself. Todos remain the tracking source of truth.
If the slices are likely to FEED each other (adjacent modules; one lane's discovery redirects another's search), run the burst in team mode per `parallel-research`: after spawning, send If the slices are likely to FEED each other (adjacent modules; one lane's discovery redirects another's search), run the burst in team mode per `parallel-research`: after spawning, send
every explorer the roster of its siblings (`agent__send_message --id <id> --message "Teammate roster: <slice>=<id>, ... Message a teammate directly when you find a fact in THEIR slice; every explorer the roster of its siblings (`agent__send_message --id <id> --message "Teammate roster: <slice>=<id>, ... Message a teammate directly when you find a fact in THEIR slice;
check your inbox after each search round and before finalizing."`) so cross-slice facts move directly between lanes instead of waiting for your synthesis. Never do this with reviewer check your inbox after each search round and before finalizing."`) so cross-slice facts move directly between lanes instead of waiting for your synthesis. Never do this with reviewer
+12 -3
View File
@@ -167,17 +167,26 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {"
``` ```
# Create tasks with dependencies (optional: auto-dispatch with --agent) # Create tasks with dependencies (optional: auto-dispatch with --agent)
agent__task_create --subject \"Explore existing patterns\" agent__task_create --subject \"Explore existing patterns\"
agent__task_create --subject \"Implement feature\" --blocked_by [\"task_1\"] --agent coder --prompt \"Implement based on patterns found\" agent__task_create --subject \"Implement feature\" --blocked_by [\"1\"] --agent coder --prompt \"Implement based on patterns found\"
agent__task_create --subject \"Write tests\" --blocked_by [\"task_2\"] agent__task_create --subject \"Write tests\" --blocked_by [\"2\"]
# Check what's runnable # Check what's runnable
agent__task_list agent__task_list
# After completing a task, mark it done to unblock dependents # After completing a task, mark it done to unblock dependents
# If dependents have --agent set, they auto-dispatch # If dependents have --agent set, they auto-dispatch
agent__task_complete --task_id task_1 agent__task_complete --task_id 1
``` ```
Task-queue rules (NOT obvious — read carefully):
- Task IDs are numeric strings (\"1\", \"2\", ...) assigned in creation order.
- A task created with `agent` but NO blockers is NEVER auto-dispatched — spawn it yourself.
- Auto-dispatch happens only inside `agent__task_complete`: completing a task is what
dispatches its newly-unblocked dependents.
- Auto-dispatched agents must still be collected via `agent__collect`, and an agent finishing
does NOT complete its task — call `agent__task_complete` yourself to advance the chain.
- A failed task permanently blocks its dependents — recreate the chain rather than retrying.
### Escalation Handling ### Escalation Handling
Child agents may need user input but cannot prompt the user directly. When this happens, Child agents may need user input but cannot prompt the user directly. When this happens,