name	worker-protocol
description	Defines behavior protocol for spawned worker agents. Injected into worker prompts. Covers startup, progress reporting, exit conditions, and handover preparation.

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:

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

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

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

<!-- 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-reviewer subagent OR perform security-review skill
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:

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

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

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

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

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

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