/implement — Full Implementation Workflow

Execute the complete implementation workflow for task: $ARGUMENTS

Pre-flight

•Verify GitHub CLI is authenticated (fail early, not at Stage 7):

bash

gh auth status

If not authenticated, STOP and tell the user to run gh auth login.

•Read tasks/$ARGUMENTS/dor.md — if it doesn't exist, STOP and tell the user to create it from tasks/TEMPLATE-dor.md
•Verify ALL DoR checkboxes are checked. If any are unchecked, STOP and report what's missing.
•Read tasks/$ARGUMENTS/plan.md if it exists.
•If $ARGUMENTS is numeric, verify the GitHub issue exists and use its title:

bash

gh issue view $ARGUMENTS --json title,state --jq '.title' 2>/dev/null

•Initialize the workflow state file:

bash

python3 scripts/advance-stage.py $ARGUMENTS --init

Stage 1: Requirements Verification

Advance the state machine:

bash

python3 scripts/advance-stage.py $ARGUMENTS 1

Spawn a Haiku teammate to verify requirements. The teammate can spawn its own subagents to explore the codebase, check dependencies, and validate the DoR in parallel.

If issues found → stop and ask the user. Shut down the teammate when done.

Stage 2: Architecture + Red Team

Advance the state machine:

bash

python3 scripts/advance-stage.py $ARGUMENTS 2 --verify tasks/$ARGUMENTS/dor.md

Spawn an Opus teammate for architecture review AND red teaming. The teammate should spawn parallel subagents for:

•Architecture review → write to tasks/$ARGUMENTS/architecture-review.md
•Red team analysis → write to tasks/$ARGUMENTS/red-team.md

If blocking findings → address before proceeding. Shut down the teammate when done.

Stage 3: Implementation

Advance the state machine (verifies architecture artifacts exist):

bash

python3 scripts/advance-stage.py $ARGUMENTS 3 --verify tasks/$ARGUMENTS/architecture-review.md tasks/$ARGUMENTS/red-team.md

Create git worktree:

bash

git worktree add ../worktree-$ARGUMENTS -b task/$ARGUMENTS

Spawn a Sonnet teammate to implement in the worktree. The teammate can spawn parallel subagents to work on different files simultaneously:

•Follow the plan from tasks/$ARGUMENTS/plan.md
•Follow golden rules from CLAUDE.md
•Run linters after each file
•Commit frequently

This teammate will be shut down before Stage 4 (max 2 active). If fixes are needed after review, spawn a new Sonnet teammate.

Stage 4: Testing (Separate Teammate)

Advance the state machine:

bash

python3 scripts/advance-stage.py $ARGUMENTS 4 --verify ../worktree-$ARGUMENTS

Shut down the implementation teammate first (max 2 active).

Spawn a new Sonnet teammate for testing. The teammate can spawn subagents to write tests in parallel across different modules:

•ONLY read interfaces — not implementation bodies
•Write tests for: happy path, edge cases, error cases
•Run the tests

Critical: The test writer must NOT be the same teammate that wrote the code.

Stage 5: Review

Advance the state machine:

bash

python3 scripts/advance-stage.py $ARGUMENTS 5 --verify tests/

Shut down the test teammate.

Spawn an Opus teammate to review. The teammate can spawn parallel subagents for:

•Correctness review
•Security review
•Performance review
•Write findings to tasks/$ARGUMENTS/review.md

If blocking findings → respawn the Sonnet teammate to fix, then re-review.

Stage 6: DoD Gates

Advance the state machine (verifies review artifact exists):

bash

python3 scripts/advance-stage.py $ARGUMENTS 6 --verify tasks/$ARGUMENTS/review.md

Run all mechanical gates:

bash

pre-commit run --all-files
pytest tests/ -v --tb=short --cov=src --cov-fail-under=90
gitleaks detect --source . --no-banner

Stage 7: Push & Create PR

Advance the state machine:

bash

python3 scripts/advance-stage.py $ARGUMENTS 7

If all gates pass:

•Verify a remote exists:

bash

git remote get-url origin 2>/dev/null

If no remote, STOP. Tell the user to add a remote with git remote add origin <url>. Do NOT fall back to local merge — all code reaches main through PRs.

•Get the current commit SHA (for CI polling later):

bash

PUSH_SHA=$(git rev-parse HEAD)

•Push the branch:

bash

git push -u origin task/$ARGUMENTS

•Create a pull request (conditionally link issue only if task-id is numeric):

bash

# Build the PR body
BODY="## Summary
<brief description from acceptance criteria>

## DoD Gates
- [x] Linting: pre-commit passed
- [x] Unit tests: pytest passed with >=90% coverage
- [x] Security: gitleaks clean
- [x] Agent review: Opus approved"

# Only add Closes # if task-id is numeric (a GitHub issue number)
if echo "$ARGUMENTS" | grep -qE '^[0-9]+$'; then
  BODY="$BODY

Closes #$ARGUMENTS"
fi

bash

gh pr create \
  --base main \
  --head task/$ARGUMENTS \
  --title "task/$ARGUMENTS: <summary from dor.md>" \
  --body "$BODY"

•Wait for CI to pass — SHA-matched polling with 10-minute timeout (20 checks, 30s apart):

bash

for i in $(seq 1 20); do
  RESULT=$(gh run list \
    --branch task/$ARGUMENTS \
    --commit "$PUSH_SHA" \
    --limit 1 \
    --json status,conclusion \
    --jq '.[0] // empty' 2>/dev/null)

  STATUS=$(echo "$RESULT" | python3 -c "import sys,json; raw=sys.stdin.read().strip(); d=json.loads(raw) if raw else {}; print(d.get('status',''))" 2>/dev/null || echo "")
  CONCLUSION=$(echo "$RESULT" | python3 -c "import sys,json; raw=sys.stdin.read().strip(); d=json.loads(raw) if raw else {}; print(d.get('conclusion',''))" 2>/dev/null || echo "")

  if [ "$STATUS" = "completed" ]; then
    if [ "$CONCLUSION" = "success" ]; then
      echo "CI passed."
      break
    else
      echo "CI failed with conclusion: $CONCLUSION"
      break
    fi
  fi
  echo "CI still running (attempt $i/20)... waiting 30s"
  sleep 30
done

If CI fails, investigate the failure and push fixes. Re-poll after each fix push. If CI times out (no completed run after 10 minutes), tell the user to check manually.

•Post the review artifact as a PR comment:

bash

gh pr comment --body "$(cat tasks/$ARGUMENTS/review.md)"

•Tell the user: "PR is ready for human review and merge." Include the PR URL.

bash

gh pr view --json url --jq '.url'

Agents do NOT merge PRs. Merging requires a human. This is a security boundary — see the red team review for rationale.

•Clean up the worktree:

bash

git worktree remove ../worktree-$ARGUMENTS

Remember: Max 2 teammates active at once. Shut down teammates as stages complete.