Worker Protocol

Behavioral contract for spawned worker agents. Embedded in worker prompts by worker-dispatch.

Core principle: Single-purpose, self-documenting, graceful exit.

Worker Identity

Property	Example	Purpose
worker_id	`worker-1701523200-123`	Unique identifier
issue	`123`	Assigned issue
attempt	`1`	Which attempt

Worktree Isolation (FIRST)

CRITICAL: Workers MUST operate in isolated worktrees. Never work in the main repository.

Verify Worktree Before ANY Work

# FIRST thing every worker does - verify isolation
verify_worktree() {
  # Check we're in a worktree, not main repo
  WORKTREE_ROOT=$(git worktree list --porcelain | grep "^worktree" | head -1 | cut -d' ' -f2)
  CURRENT_DIR=$(pwd)

  if [ "$WORKTREE_ROOT" = "$CURRENT_DIR" ] && git worktree list | grep -q "$(pwd).*\["; then
    echo "✓ In isolated worktree: $(pwd)"
  else
    echo "ERROR: Not in an isolated worktree!"
    echo "Current: $(pwd)"
    echo "Worktrees: $(git worktree list)"
    exit 1
  fi

  # Verify on feature branch, not main
  BRANCH=$(git branch --show-current)
  if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
    echo "ERROR: On $BRANCH branch - must be on feature branch!"
    exit 1
  fi

  echo "✓ On branch: $BRANCH"
}

If NOT in a worktree: STOP. Post error to issue. Exit immediately.

Workers must NEVER:

Work directly in the main repository
Create branches in main repo
Modify files that other workers might touch

Startup Checklist

Workers MUST execute this checklist before starting work:

Verify worktree isolation (see above - MUST be first)
Read assigned issue completely
Check issue comments for context/history
Verify on correct feature branch (git branch --show-current)
Check worktree is clean (git status)
Run existing tests to verify baseline (pnpm test or equivalent)
Post startup comment to issue

Startup comment template:

**Worker Started**

| Property | Value |
|----------|-------|
| Worker ID | `[WORKER_ID]` |
| Attempt | [N] |
| Branch | `[BRANCH]` |

**Understanding:** [1-2 sentence summary of what issue requires]

**Approach:** [Brief planned approach]

---
*Orchestration: [ORCHESTRATION_ID]*

Progress Reporting

Post to issue on: start, milestone, blocker, completion

**Status:** [Implementing|Testing|Blocked|Complete] | Turns: [N]/100
- [x] Completed item
- [ ] Current item

Exit Conditions

Exit when ANY occurs. Return structured JSON and post appropriate comment.

1. COMPLETED (Success)

**Worker Complete** ✅

**PR Created:** #[PR_NUMBER]
**Issue:** #[ISSUE]
**Branch:** `[BRANCH]`

**Summary:** [1-2 sentences describing what was implemented]

**Tests:** [N] passing | Coverage: [X]%

---
*Worker: [WORKER_ID] | Turns: [N]/100*

Return: {"status": "COMPLETED", "pr": [PR_NUMBER], "summary": "..."}

2. BLOCKED (External Dependency)

Only after exhausting all options:

**Worker Blocked** 🚫

**Reason:** [Clear description of blocker]

**What I tried:**
1. [Approach 1] - [Why it didn't work]
2. [Approach 2] - [Why it didn't work]

**Required to unblock:**
- [ ] [Specific action needed from human/external]

**Cannot proceed because:** [Why this is a true blocker, not just hard]

---
*Worker: [WORKER_ID] | Attempt: [N]*

Return: {"status": "BLOCKED", "pr": null, "summary": "Blocked: [reason]"}

3. HANDOVER (Turn Limit)

At 85-90 turns, prepare handover:

**Handover Required** 🔄

**Turns Used:** [N]/100
**Reason:** Approaching turn limit

Handover context posted below. Replacement worker will continue.

---
*Worker: [WORKER_ID]*

Then post full handover with  markers per worker-handover skill.

Return: {"status": "HANDOVER", "pr": null, "summary": "Handover at [N] turns"}

4. FAILED (Needs Research)

When implementation fails after good-faith effort:

**Worker Failed - Research Needed** 🔬

**Failure:** [What failed]
**Attempt:** [N]

**What I tried:**
1. [Approach 1] - [Result]
2. [Approach 2] - [Result]

**Error:**

[Error output]


**Hypothesis:** [What might be wrong]

**Research needed:**
- [ ] [Specific question to research]

---
*Worker: [WORKER_ID] | Triggering research cycle*

Return: {"status": "FAILED", "pr": null, "summary": "Failed: [reason]"}

Review Gate (MANDATORY)

Before creating ANY PR:

Complete comprehensive-review (7 criteria)
Post review artifact to issue:  ... 
Address ALL findings (Unaddressed: 0)
Status: COMPLETE

PreToolUse hook BLOCKS gh pr create without valid review artifact.

Security-Sensitive Files

If modifying: **/auth/**, **/api/**, **/*password*, **/*token*, **/*secret*

→ Complete security-review and include in artifact.

Behavioral Rules

DO:

Work ONLY on assigned issue
TDD: tests first
Commit frequently with descriptive messages
Post progress to issue
Complete review before PR
Handover at 90+ turns

DO NOT:

Start other issues
Modify unrelated code
Skip tests
Create PR without review artifact
Continue past 100 turns

Commit Format

[type]: [description] (#[ISSUE])

Worker: [WORKER_ID]

Types: feat, fix, test, refactor, docs

PR Creation

Prerequisite: Review artifact in issue comments with status COMPLETE.

# Verify review exists
gh api "/repos/$OWNER/$REPO/issues/$ISSUE/comments" \
  --jq '[.[] | select(.body | contains("<!-- REVIEW:START -->"))] | length'

PR body:

## Summary
[1-2 sentences]

Closes #[ISSUE]

## Changes
- [Change 1]
- [Change 2]

## Review
Review artifact: See issue #[ISSUE]

---
Worker: `[WORKER_ID]`

Turn Awareness

Turns	Action
0-80	Normal work
80-90	Monitor, prepare handover if needed
90+	Finalize and handover

Handover Trigger

At 90+ turns or when context valuable for next attempt:

Post handover to issue with  markers
Commit all work
Exit with {"status": "HANDOVER", ...}

See worker-handover for full format.

Integration

Workers MUST follow these skills:

Skill	Purpose
`issue-driven-development`	Core workflow
`strict-typing`	Type requirements (no `any`)
`ipv6-first`	Network requirements
`tdd-full-coverage`	Testing approach
`clean-commits`	Commit standards
`worker-handover`	Handover format
`comprehensive-review`	Code review (MANDATORY before PR)
`apply-all-findings`	Address all review findings
`security-review`	For security-sensitive files
`deferred-finding`	For tracking deferred findings
`review-gate`	PR creation gate

Enforced by: PreToolUse hook on gh pr create, Stop hook for review verification

worker-protocol