Worker Protocol

Overview

This skill defines the behavioral contract for spawned worker agents. It is injected into worker prompts and governs how workers operate.

Core principle: Workers are single-purpose, self-documenting, and gracefully exit.

Note: This skill is not invoked directly - it's embedded in worker prompts by worker-dispatch.

Worker Identity

Every worker has:

Property	Example	Purpose
`worker_id`	`worker-1701523200-123`	Unique identifier
`issue`	`123`	Assigned issue number
`attempt`	`1`	Which attempt this is
`orchestration_id`	`orch-2025-12-02-001`	Parent orchestration

Startup Checklist

Workers MUST execute this checklist before starting work:

markdown

## Worker Startup Checklist

1. [ ] Read assigned issue completely
2. [ ] Check issue comments for context/history
3. [ ] Verify on correct branch (`git branch --show-current`)
4. [ ] Check worktree is clean (`git status`)
5. [ ] Run existing tests to verify baseline (`pnpm test` or equivalent)
6. [ ] Post startup comment to issue

Startup Comment Template

markdown

🤖 **Worker Started**

| Property | Value |
|----------|-------|
| Worker ID | `[WORKER_ID]` |
| Attempt | [N] |
| Branch | `[BRANCH_NAME]` |
| Started | [TIMESTAMP] |

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

**Approach:**
[Brief planned approach]

---
*Orchestration: [ORCHESTRATION_ID]*

Progress Reporting

When to Report

Workers post progress comments:

•On start - Startup checklist complete
•On milestone - Significant progress (e.g., "tests passing")
•On blocker - When encountering impediment
•On completion - PR created or handover needed

Progress Comment Template

markdown

🤖 **Worker Update**

**Status:** [Implementing|Testing|Blocked|Complete]
**Turns Used:** [N]/100

**Progress:**
- [x] [Completed item]
- [x] [Completed item]
- [ ] [In progress item]
- [ ] [Remaining item]

**Current:**
[What you're working on right now]

**Next:**
[What you'll do next]

---
*Worker: [WORKER_ID]*

Exit Conditions

Workers exit when ANY of these conditions are met:

1. PR Created (Success)

markdown

🤖 **Worker Complete** ✅

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

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

**Tests:**
- [N] tests passing
- Coverage: [X]%

**Ready for:** CI verification

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

2. Handover Needed (Turn Limit)

When approaching 100 turns (at ~85-90 turns):

markdown

🤖 **Handover Required** 🔄

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

**Handover file created:** `.orchestrator/handover-[ISSUE].md`

A replacement worker will continue this work with full context.

---
*Worker: [WORKER_ID]*

See worker-handover skill for handover file format.

3. Blocked (External Dependency)

Only after exhausting all options:

markdown

🤖 **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:**
[Explanation of why this is a true blocker, not just a hard problem]

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

4. Failed (Needs Research)

When implementation fails after good-faith effort:

markdown

🤖 **Worker Failed - Research Needed** 🔬

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

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

**Error/Issue:**

[Error output or description]

code


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

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

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

Review Gate (MANDATORY)

Before creating ANY PR, workers MUST:

•Complete comprehensive-review skill (7 criteria)
•Post review artifact to issue comment (exact format required)
•Address ALL findings using apply-all-findings skill
•Verify "Unaddressed: 0" in artifact
•Update artifact status to "COMPLETE"

Review artifact format (machine-parseable):

markdown

<!-- REVIEW:START -->
## Code Review Complete

| Property | Value |
|----------|-------|
| Worker | `[WORKER_ID]` |
| Issue | #[ISSUE] |
| Reviewed | [TIMESTAMP] |

[... full artifact per comprehensive-review skill ...]

**Review Status:** ✅ COMPLETE
<!-- REVIEW:END -->

CRITICAL: The PreToolUse hook will BLOCK gh pr create if:

•No review artifact found in issue comments
•Review status is not COMPLETE
•Unaddressed findings > 0

Security-Sensitive Changes

If worker modifies files matching security-sensitive patterns:

•**/auth/**, **/api/**, **/middleware/**
•**/*password*, **/*token*, **/*secret*

Worker MUST:

•Invoke security-review skill OR run codex-subagent security-reviewer
•Include security review in artifact
•Mark "Security-Sensitive: YES" in artifact

Behavioral Rules

DO

•✅ Work ONLY on assigned issue
•✅ Follow all project skills (TDD, strict-typing, ipv6-first, etc.)
•✅ Commit frequently with descriptive messages
•✅ Update issue with progress comments
•✅ Test thoroughly before creating PR
•✅ Complete comprehensive-review before PR
•✅ Post review artifact to issue
•✅ Address ALL review findings (no exceptions)
•✅ Prepare handover if approaching turn limit
•✅ Exit cleanly when done

DO NOT

•❌ Start work on other issues
•❌ Modify unrelated code
•❌ Skip tests to save turns
•❌ Create PR without passing tests
•❌ Create PR without review artifact
•❌ Leave review findings unaddressed
•❌ Defer findings without tracking issues
•❌ Ignore project standards
•❌ Continue past 100 turns
•❌ Delete or modify other workers' branches

Commit Message Format

Workers use this commit format:

code

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

[Body if needed]

🤖 Worker: [WORKER_ID]

Types:

•feat: New feature
•fix: Bug fix
•test: Test additions
•refactor: Code refactoring
•docs: Documentation

Example:

code

feat: Add dark mode toggle to settings (#123)

- Created ThemeContext with dark/light modes
- Added toggle switch to settings page
- Persisted preference to localStorage

🤖 Worker: worker-1701523200-123

PR Creation

PREREQUISITE: Review artifact MUST be posted to issue before PR creation.

Pre-PR Verification

bash

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

if [ "$REVIEW_EXISTS" = "0" ]; then
  echo "ERROR: No review artifact found. Complete comprehensive-review first."
  exit 1
fi

# Verify review is COMPLETE with 0 unaddressed
REVIEW_STATUS=$(gh api "/repos/$OWNER/$REPO/issues/$ISSUE/comments" \
  --jq '[.[] | select(.body | contains("<!-- REVIEW:START -->"))] | last | .body' \
  | grep -o "Review Status:.*" | head -1)

echo "Review status: $REVIEW_STATUS"

PR Title Format

code

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

PR Body Template

markdown

## Summary
[1-2 sentence description]

Closes #[ISSUE]

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

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests passing
- [ ] Manual testing completed

## Code Review
- [x] Review artifact posted to issue
- [x] All findings addressed
- [x] Review status: COMPLETE

## Checklist
- [ ] Code follows project style
- [ ] Types are complete (no `any`)
- [ ] Documentation updated
- [ ] IPv6-first verified (if applicable)

---
🤖 **Automated PR**
Worker: `[WORKER_ID]`
Orchestration: `[ORCHESTRATION_ID]`
Attempt: [N]
Review: See issue #[ISSUE] for review artifact

Worktree Awareness

Workers operate in isolated worktrees and must:

•Stay in worktree - Don't cd to main repo
•Use relative paths - Worktree is the root
•Commit to branch - Not main
•Push to remote - For PR creation

bash

# Verify worktree
git worktree list

# Verify branch
git branch --show-current  # Should be feature/[ISSUE]-*

# Verify not on main
if [ "$(git branch --show-current)" = "main" ]; then
  echo "ERROR: On main branch in worktree!"
  exit 1
fi

Turn Awareness

Workers should be aware of their turn budget:

Turns	Status	Action
0-50	Early	Normal work
50-80	Mid	Monitor progress
80-90	Late	Prepare handover if needed
90-100	Critical	Finalize and handover

At turn 85+:

code

⚠️ **Turn Check:** [N]/100 turns used

If work is not nearly complete, begin handover preparation now.

Error Recovery

When errors occur:

•Don't panic - Errors are information
•Document - Capture error output
•Analyze - Understand what went wrong
•Retry once - Try an alternative approach
•Report - If still failing, report for research

markdown

🤖 **Error Encountered**

**Command:** `[command that failed]`
**Error:**

[error output]

code


**Analysis:** [What I think went wrong]
**Retry:** [What I'll try next]

Handover Trigger

Workers MUST create handover when:

•Turn count reaches 90+
•Cannot complete in remaining turns
•Blocked but context valuable for next attempt

See worker-handover skill for handover file format.

Integration

This protocol is used by:

•All spawned workers

This protocol requires workers to follow:

•issue-driven-development - Core workflow
•strict-typing - Type requirements
•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 findings
•security-review - For security-sensitive files
•deferred-finding - For tracking deferred findings
•review-gate - PR creation gate

This protocol is enforced by:

•PreToolUse hook on gh pr create - Blocks without review artifact
•Stop hook - Verifies review completion before session end