supervisor-spawn-worker

Supervisor Spawn Worker

<!-- BEGIN GENERATED FROM pasture schema --> <!-- GENERATED FROM pasture v0.0.32 artifact v1 --> Command: pasture:supervisor:spawn-worker — Launch a worker agent for an assigned slice

Launch the wave of workers for parallel vertical slice implementation, reviewed by ephemeral reviewers.

-> Full workflow in PROCESS.md <- Phase 9

Ride the Wave — Coordinated Phase 8-10 Execution

Phase 8: PLAN
  ├─ Read RATIFIED_PLAN + URD
  ├─ Spawn ephemeral Explore subagents (Task tool, scoped queries)
  ├─ Use Explore findings to map codebase
  ├─ Decompose into vertical slices + integration points
  └─ Create leaf tasks for every slice

Phase 9: BUILD
  ├─ Spawn N Workers for parallel slice implementation
  ├─ Workers implement their slices in parallel
  └─ Workers do NOT shut down when finished

Phase 10: REVIEW + FIX CYCLES (up to the chosen review-effort budget — iterate until 0/0/0 clean, else surface to user)
  ├─ Cycle 1:
  │   ├─ Spawn ephemeral reviewers (Task tool, per-slice review)
  │   ├─ Reviewers review ALL slices (severity tree: BLOCKER/IMPORTANT/MINOR)
  │   ├─ Workers fix ALL findings (BLOCKER + IMPORTANT + MINOR) with atomic commits
  │   └─ Spawn new ephemeral reviewers for re-review
  ├─ Cycle 2 (if needed): same pattern
  ├─ Cycle N (as many as needed): same pattern
  └─ Continue until a fix-free clean round confirms 0 BLOCKER + 0 IMPORTANT + 0 MINOR

DONE → Phase 11 (UAT)
  ├─ Shut down Workers
  └─ FOLLOWUP epic (if any) is created at UAT from user-DEFER'd items only

Cycle Exit Conditions:
  Fix-free clean round: 0 BLOCKER + 0 IMPORTANT + 0 MINOR   → Proceed to Phase 11 (UAT)
  ANY finding remains (BLOCKER/IMPORTANT/MINOR)             → Workers fix, spawn new ephemeral reviewers (up to chosen budget; on exhaustion, surface to user)
  Genuinely stuck (cannot reach a clean round)             → Escalate to architect for re-planning

[sup-spawn-task-tool]

• Given: implementation tasks
• When: spawning
• Then: use Task tool with run_in_background: true
• Should not: block on worker completion

[sup-spawn-parallel-wave]

• Given: multiple workers
• When: launching
• Then: spawn all slices in parallel as a single wave
• Should not: spawn sequentially

[sup-spawn-worker-context]

• Given: worker assignment
• When: providing context
• Then: include Pasture task ID, full context, and handoff document
• Should not: omit checklist or criteria

[sup-spawn-handoff-doc]

• Given: worker handoff
• When: creating
• Then: author the supervisor→worker handoff in the slice (or a dedicated handoff) Pasture task body
• Should not: skip the handoff or store it as a filesystem path

[sup-spawn-no-close-before-review]

• Given: workers complete their slices
• When: first wave finishes
• Then: do NOT close slices — ephemeral reviewers must review ALL slices first
• Should not: close a slice that has not been reviewed at least once

[sup-spawn-fix-and-rereview]

• Given: reviewers finish reviewing
• When: BLOCKERs or IMPORTANT findings exist
• Then: send findings to workers for fixing, then spawn new ephemeral reviewers for re-review
• Should not: skip re-review after fixes

[sup-spawn-max-cycles]

• Given: worker-reviewer cycle
• When: counting iterations
• Then: iterate review->fix->re-review up to the chosen review-effort budget until a fix-free clean round confirms 0 BLOCKER + 0 IMPORTANT + 0 MINOR within budget; on budget exhaustion without clean, surface outstanding findings to the user at a gate
• Should not: hardcode the budget, proceed past the chosen budget without surfacing to the user, close a wave on a fix-applying round, or proceed with any finding silently outstanding

[sup-spawn-important-after-cycles]

• Given: IMPORTANT or MINOR findings remain
• When: deciding next step
• Then: keep iterating review->fix->re-review until ALL severity groups reach 0 — every severity must be resolved before the wave closes
• Should not: proceed to UAT with non-zero findings or route any review severity (IMPORTANT/MINOR) to the FOLLOWUP epic

[frag--review-clean-exit]

• Given: per-slice code review
• When: evaluating review results
• Then: iterate review -> fix -> re-review up to the chosen review-effort budget; clean = 0 BLOCKER + 0 IMPORTANT + 0 MINOR within budget; on budget exhaustion without clean, SURFACE the outstanding findings to the user at a gate for a decision
• Should not: hardcode the budget; proceed past the chosen budget without surfacing outstanding findings to the user; loop forever when a finite budget was chosen

Task Recovery

Recover from live Pasture state at session start and after compaction; never trust cached task rows.

Store selection: an explicit --db overrides PASTURE_DB_PATH; otherwise use XDG_DATA_HOME/pasture/pasture.db, HOME/.local/share/pasture/pasture.db, then .pasture/pasture.db. Use the same selected store for every command. If a recovery query fails, report its actual store path, failed operation, impact, and permission/schema/configuration repair; failure is not an empty work queue.

Set PASTURE_NAMESPACE to the repository's canonical namespace URI, for example https://github.com/dayvidpham/pasture. The CLI reads it as the default for --namespace when the flag is omitted; an explicit --namespace always wins. task list, task ready, and task blocked are scoped to that effective namespace, and --all-namespaces ignores both sources. When neither source is set, those reads are unscoped. Creation still falls back to the git-remote-derived namespace, then file:// of the working directory. Inspect the returned full URI before choosing repository work. Separate reads are not an atomic snapshot.

Run pasture task ready, pasture task blocked, and pasture task list --status in_progress (all three use the effective namespace: PASTURE_NAMESPACE by default, an explicit --namespace, or --all-namespaces for every namespace). For each referenced active task, run pasture task show "$TASK_URI", pasture task comments "$TASK_URI", and pasture task timeline "$TASK_URI". All *_URI variables in examples are inputs bound to full task URIs from an assignment, a verified tracker read, or the actual JSON id returned by create; never use legacy short IDs. Resolve each variable before execution and quote it as one operand.

Create returns an object whose id is the task URI: capture it with --format json and python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])'. Persist that URI before label/comment steps. Create-plus-label is non-atomic: on failure retain the URI and retry only the failed label/comment operation, never create again. Only open, in_progress, and closed are statuses; blockage is represented by live dependencies and notes, not a blocked status.

Assignment transfer is not initial allocation: before using pasture task assignment transfer, obtain the existing owner-responsibility assignment and its exact successor assignment ID, registered committing actor, and registered worker occupant from the supervisor. If the task is unassigned, stop and let the supervisor arrange allocation; no assignment-start command is implied. Never repeat an identical transfer as a substitute for allocating different workers.

Parent stays open and is blocked by child: pasture task dep add "$PARENT_URI" --blocked-by "$CHILD_URI". Reference documents belong in description frontmatter under references:, never fabricated blockers. Workers report evidence and handoffs without closing their slices or leaves; the supervisor closes only after independent review and satisfied gates. Use git agent-commit for local commits. Never install, enable, or modify Git hooks, Git hook path configuration, or pre-commit integration without explicit user approval. Tracker writes are durable; Git history lands separately.

Task Attribution

Select the current registered author with pasture task agents list and pasture task agents show ACTOR-ID. Never auto-register or guess an identity during recovery. Every comment supplies --author explicitly; machine examples use the pre-registered pasture-system/00000000-0000-0000-0000-000000000000 actor. If it is absent, stop and request registration from the operator rather than claiming registration is fixed. Preserve human intent verbatim and quote historical attribution as evidence, not as a forged new author.

When to Use

Implementation tasks ready. Ephemeral reviewers will be spawned per-slice during review phase.

Ride the Wave — Overview

The supervisor executes Phases 8-10 as a single coordinated cycle called Ride the Wave:

1. PLAN  → supervisor-plan-tasks: decompose into slices + integration points
2. EXPLORE → Ephemeral Explore subagents (Task tool): map codebase, short-lived
3. BUILD → N Workers: implement slices in parallel
4. REVIEW → Ephemeral reviewers (Task tool): review per-slice
5. FIX   → Workers fix BLOCKERs + IMPORTANTs with atomic commits
6. RE-REVIEW → Spawn new ephemeral reviewers for re-review
7. REPEAT → Steps 5-6 up to the chosen review-effort budget until a fix-free clean round confirms 0/0/0; on budget exhaustion without clean, surface to the user
8. TRACK → ALL severities (BLOCKER/IMPORTANT/MINOR) must reach 0 — none route to FOLLOWUP
9. NEXT  → When fix-free clean (0 BLOCKER + 0 IMPORTANT + 0 MINOR) → Phase 11 (UAT); escalate to architect only if genuinely stuck

Key rules:

• Reviewers are ephemeral (spawned per review cycle via Task tool)
• Slices are never closed until reviewed at least once
• Configurable review-effort budget (chosen at Phase 8: 3 rounds / 1 round / 0 rounds / unlimited / custom) — iterate review→fix→re-review up to the budget until 0 BLOCKER + 0 IMPORTANT + 0 MINOR on a fix-free round; on budget exhaustion without clean, surface outstanding findings to the user at a gate; escalate to architect only if genuinely stuck
• The FOLLOWUP epic is fed ONLY by user-DEFER'd UAT items, never by review severities

Handoff Template (Supervisor → Worker)

Before spawning each worker, author its handoff in the slice (or a dedicated handoff) Pasture task body:

Storage: the Pasture task body IS the handoff — no filesystem path.

# Handoff: Supervisor → Worker <N>

## Context
- Request: ${REQUEST_ID_URI}
- URD: ${URD_ID_URI}
- IMPL_PLAN: ${IMPL_PLAN_ID_URI}
- Ratified Proposal: ${PROPOSAL_ID_URI}

## Your Slice
- Slice: SLICE-<N>
- Task ID: ${SLICE_TASK_ID_URI}
- Production Code Path: <what end users run>

## Key Files
| File | What You Own |
|------|-------------|
| pkg/feature/types.go | ListOptions, ListEntry types |
| cmd/feature/list_test.go | List command tests |
| pkg/feature/service.go | ListItems() method |
| cmd/feature/list.go | list subcommand wiring |

## Implementation Order
1. Layer 1: Types (your slice only)
2. Layer 2: Tests (import production code — will FAIL, expected)
3. Layer 3: Implementation + Wiring (make tests PASS)

## Validation Checklist
- [ ] Production code verified via code inspection
- [ ] Tests import actual CLI (not test-only export)
- [ ] No dual-export anti-pattern
- [ ] No TODO placeholders
- [ ] Service wired with real dependencies

## Persistence
Do NOT shut down after implementation. You will receive review feedback
and may need to fix BLOCKERs and IMPORTANT findings. Stay alive for the
full Ride the Wave cycle.

Task Call

Task({
  description: "Worker: implement SLICE-N",
  prompt: `Call Skill(/pasture:worker) and implement the assigned slice.

Pasture Task ID: "${TASK_ID_URI}"
Read full requirements + handoff: pasture task show "${TASK_ID_URI}"

Do NOT shut down after implementation. You will receive review feedback and may need to fix issues.`,
  subagent_type: "general-purpose",
  run_in_background: true
})

Per [sup-spawn-workers], use subagent_type: "general-purpose", not a custom agent type. The worker skill is invoked inside the agent via Skill(/pasture:worker).

TeamCreate: SendMessage Assignment

When workers are spawned via TeamCreate, they receive context through SendMessage instead of a Task prompt. The message MUST be self-contained — teammates have no prior context:

SendMessage({
  type: "message",
  recipient: "worker-1",
  content: `You are assigned SLICE-1. Start by calling Skill(/pasture:worker).

Your Pasture task ID: "${SLICE_TASK_ID_URI}"
Run this to get full requirements + handoff: pasture task show "${SLICE_TASK_ID_URI}"

Key references (run pasture task show on each for full context):
- Request: "${REQUEST_ID_URI}"
- URD: "${URD_ID_URI}"
- IMPL_PLAN: "${IMPL_PLAN_ID_URI}"
- Ratified Proposal: "${PROPOSAL_ID_URI}"

Read the handoff doc and your Pasture task before starting implementation.

IMPORTANT: Do NOT shut down after completing implementation. You will receive
review feedback from ephemeral reviewers and may need to fix BLOCKERs and IMPORTANT
findings. Stay alive for the full Ride the Wave cycle.`,
  summary: "SLICE-1 assignment with Pasture context"
})

Per [sup-teamcreate-msg], include Pasture task IDs and pasture task show commands in every assignment. Teammates cannot see your conversation or task tree.

Worker Persistence (Ride the Wave)

Per [sup-worker-persistence], workers stay alive for the full review-fix cycle:

1. Worker completes slice → notifies supervisor
2. Supervisor does NOT close the slice or shut down the worker
3. Ephemeral reviewers review the slice
4. If ANY findings (BLOCKER/IMPORTANT/MINOR): supervisor sends fix assignment to worker
5. Worker fixes issues → notifies supervisor
6. New ephemeral reviewers re-review
7. Repeat steps 4-6 up to the chosen review-effort budget until a fix-free clean round confirms 0/0/0; on budget exhaustion without clean, surface outstanding findings to the user at a gate
8. After a fix-free clean round (0 BLOCKER + 0 IMPORTANT + 0 MINOR): supervisor shuts down worker

Fix Assignment Message Template

SendMessage({
  type: "message",
  recipient: "worker-1",
  content: `Review cycle <N> found issues in your slice (SLICE-1).

BLOCKERs (must fix — blocks slice closure):
- "${FINDING_ID_URI}": <description> (pasture task show "${FINDING_ID_URI}")

IMPORTANT (must fix — must reach 0 before wave close):
- "${FINDING_ID_URI}": <description> (pasture task show "${FINDING_ID_URI}")

MINOR (must fix — must reach 0 before wave close):
- "${FINDING_ID_URI}": <description> (pasture task show "${FINDING_ID_URI}")

After fixing all items:
  pasture task comment add --author pasture-system/00000000-0000-0000-0000-000000000000 "${SLICE_ID_URI}" "Fixes applied for review cycle <N>"

Do NOT shut down. Ephemeral reviewers will re-review.`,
  summary: "Review cycle <N> fixes for SLICE-1"
})

Worker Should Update Pasture Status

• On start: pasture task update "${TASK_ID_URI}" --status=in_progress
• On implementation complete (NOT slice close): pasture task comment add --author pasture-system/00000000-0000-0000-0000-000000000000 "${TASK_ID_URI}" "Implementation complete, awaiting review"
• On blocked: pasture task update "${TASK_ID_URI}" --notes="Blocked: <reason>"
• Slice closure: only the supervisor closes slices after review passes

Assign via Pasture

pasture task assignment transfer "${TASK_ID_URI}" --slot owner-responsibility --assignment "${SUCCESSOR_ASSIGNMENT_ID}" --actor pasture-system/00000000-0000-0000-0000-000000000000 --occupant "${REGISTERED_WORKER_ACTOR}"
pasture task update "${TASK_ID_URI}" --status=in_progress

Follow-up Slice Handoff (FOLLOWUP_SLICE-N)

For follow-up slices, the handoff (authored in the Pasture task body — no filesystem path) extends with additional fields:

# Handoff: Supervisor → Worker <N> (Follow-up)

## Context
- Original Request: "${REQUEST_ID_URI}"
- Follow-up Epic: "${FOLLOWUP_EPIC_ID_URI}"
- FOLLOWUP_URD: "${FOLLOWUP_URD_ID_URI}"
- FOLLOWUP_IMPL_PLAN: "${FOLLOWUP_IMPL_PLAN_ID_URI}"

## Your Slice
- Slice: FOLLOWUP_SLICE-<N>
- Task ID: "${SLICE_TASK_ID_URI}"

## DEFER'd Items (from UAT)
| Item Task ID | Source UAT | Description |
|---|---|---|
| "${ITEM_ID_1_URI}" | "${UAT_ID_URI}" | <user-DEFER'd item description> |
| "${ITEM_ID_2_URI}" | "${UAT_ID_URI}" | <user-DEFER'd item description> |

## Acceptance Criteria
- All DEFER'd items in this slice resolved (tests pass, production code path verified)
- See pasture task show "${SLICE_TASK_ID_URI}" for full validation_checklist

<!-- END GENERATED FROM pasture schema -->