troykelly/worker-protocol

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:

## 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

🤖 **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:

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

Progress Comment Template

🤖 **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)

🤖 **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):

🤖 **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:

🤖 **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:

🤖 **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]

**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:

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

Review artifact format (machine-parseable):

<!-- 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:

1. Invoke security-review skill OR run codex-subagent security-reviewer
2. Include security review in artifact
3. 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:

[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:

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

# 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

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

PR Body Template

## 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:

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

# 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+:

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

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

Error Recovery

When errors occur:

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

🤖 **Error Encountered**

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

[error output]

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

Handover Trigger

Workers MUST create handover when:

1. Turn count reaches 90+
2. Cannot complete in remaining turns
3. 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