spawn-teammates

name	spawn-teammates
description	Reproducible teammate creation during Sprint Planning. Reads Sprint and Backlog state, spawns Developer teammates via Agent Teams with consistent naming and assignment.
disable-model-invocation	false

Inputs

• sprint.json → id, status
• backlog.json → Sprint PBIs (derived: items[] where sprint_id == sprint.id)

Outputs

• sprint.json → developers[] populated, status: "active"
• Agent Teams teammates spawned

Preconditions

• state.json phase: "sprint_planning" or "integration_sprint"
• sprint.json status: "planning"
• backlog.json has ≥1 refined PBI with sprint_id == sprint.id

Steps

0. Freeze Sprint base. Run bash .scrum/scripts/freeze-sprint-base.sh. This captures sprint.json.base_sha = $(git rev-parse HEAD) exactly once per Sprint. PBI worktrees fork from this commit. The wrapper refuses while docs/design/ has uncommitted changes — scaffold stubs and catalog-config enables must be committed first (sprint-planning Step 13), or they will be missing from every worktree. If it refuses, go back and commit; do not work around it.

1. Read sprint.json→id (the current Sprint id is also at state.json.current_sprint_id)

2. Derive Sprint PBIs from backlog.json:

   SPRINT_PBIS=$(jq -r --arg sid "$SPRINT_ID" \
     '.items[]? | select(.sprint_id == $sid and .status == "refined") | .id' \
     .scrum/backlog.json)
   

3. Compute target developer count = min(count of $SPRINT_PBIS, 6). 1 Developer = 1 PBI. The count is not persisted; the invariant developers | length == derived count is the exit criterion.

4. Extract Sprint number N from sprint.json id (e.g., "sprint-001"→1)

5. Each Developer: a. ID: dev-001-s{N}, dev-002-s{N} (zero-pad + -s{N} mandatory, no short forms) b. Implement assignment from backlog.json implementer_id c. Entry: {"id": "dev-001-s{N}", "assigned_work": {"implement": [...]}, "status": "active", "sub_agents": []}

5.5. Create PBI worktrees. For each PBI assigned in this Sprint run: bash .scrum/scripts/create-pbi-worktree.sh <pbi-id> This creates .scrum/worktrees/<pbi-id> checked out at pbi/<pbi-id> forked from sprint.base_sha, sets up the .scrum symlink, and writes branch, worktree, base_sha into .scrum/pbi/<pbi-id>/state.json.

6. Reconcile backlog.json: Update all PBI implementer_id to match final dev-NNN-sN IDs

7. Register each Developer in sprint.json. For every entry from step 5a:

   .scrum/scripts/set-sprint-developer.sh "$DEV_ID" status active
   .scrum/scripts/set-sprint-developer.sh "$DEV_ID" current_pbi "$ASSIGNED_PBI"
   .scrum/scripts/set-sprint-developer.sh "$DEV_ID" assigned_work \
     "$(jq -nc --arg pbi "$ASSIGNED_PBI" '{implement:[$pbi]}')"
   .scrum/scripts/set-sprint-developer.sh "$DEV_ID" sub_agents '[]'
   

   (The wrapper above auto-grows the developers[] array. The assigned_work write seeds assigned_work.implement[] so the schema-required PBI-allocation surface is set through wrappers — raw edits of .scrum/sprint.json are guard-blocked. sub_agents starts empty and is populated later by install-subagents. There is no developer_count field to seed anymore — count is developers | length.)

8. Spawn Agent Teams teammates (../../agents/developer.md). Name = exact ID from 5a. Compute PROJECT_ROOT=$(git rev-parse --show-toplevel) at spawn time and substitute it into the task prompt below in place of <PROJECT_ROOT>. Each Developer's <pbi-id> is the one assigned to them in 5a/6.

   Task:

   Your working directory: <PROJECT_ROOT>/.scrum/worktrees/<pbi-id>
   First action: cd "<PROJECT_ROOT>/.scrum/worktrees/<pbi-id>"
   All file operations and commits must stay inside this directory.
   Use `.scrum/scripts/commit-pbi.sh` for commits — never raw `git commit`.
   
   Invoke the `pbi-pipeline` skill to drive design → impl+UT → per-PBI
   review for your assigned PBI. Do NOT invoke `cross-review` — that is
   a Sprint-end skill owned by the Scrum Master (FR-009 Layer 2).
   
   When pbi-pipeline finishes the UT Run stage successfully, run
   `.scrum/scripts/mark-pbi-ready-to-merge.sh <pbi-id>` (this sets
   backlog status to `in_progress_merge`) and notify SM:
   `[<pbi-id>] PBI_READY_TO_MERGE branch=pbi/<pbi-id> sha=<head>`.
   Then stop and wait.
   

9. Verify all teammates active + assignments received

10. sprint.json → status: "active":

    .scrum/scripts/update-sprint-status.sh active
    

Ref: FR-007

Re-Spawn Recovery (FR-022)

When Teammate Liveness Protocol detects terminated Developer:

1. Read sprint.json→get developer entry + assigned_work
2. Read backlog.json→get PBI status to determine remaining work
3. Update sprint.json developer status: "failed":

   .scrum/scripts/set-sprint-developer.sh "$DEV_ID" status failed
   

4. Spawn new teammate: same ID (e.g., dev-001-s{N}), ../../agents/developer.md
5. Task prompt = remaining work only (always via pbi-pipeline). Branch on the PBI's backlog status:
   • refined (not yet started) → "Invoke pbi-pipeline for PBI-XXX from the start"
   • in_progress_design → "Resume pbi-pipeline for PBI-XXX from the Design stage; prior design docs at: ..."
   • in_progress_impl / in_progress_pbi_review / in_progress_ut_run → "Resume pbi-pipeline for PBI-XXX from the impl→pbi_review→ut_run cycle; design docs at: ..."
   • in_progress_merge → "Re-run mark-pbi-ready-to-merge.sh and re-notify SM; the prior worktree is intact"
6. Update sprint.json developer status: "active":

   .scrum/scripts/set-sprint-developer.sh "$DEV_ID" status active
   

Exit Criteria

• sprint.json.developers | length equals the derived target count from Step 3 (one entry per Sprint PBI, max 6)
• All Developers: assigned_work.implement[] non-empty
• All teammates spawned + active
• sprint.json status: "active"