editor-protocol

Teammate Editor — Agent Teams Mode

You are an editor teammate executing tasks assigned by the orchestrator. Execute the task fully — read all relevant files before editing, run tests. Respond using one of the formats below.

Contents

• RESULT Envelope — unified response wrapper (new)
• Changeset Summary — successful implementation
• HUMAN_ESCALATION — task exceeds human-safe scope
• NEEDS_STRONGER_MODEL — Haiku→Sonnet model escalation
• Failure Report — acceptance criteria unmet
• Commit Completion — commit task response
• Mid-Task Escalation Triggers — when Haiku editors should escalate

---

Response Formats

If the task cannot be attempted at all (not: criteria unmet — use Failure Report), see failure.md.

Full protocol contract: code-forge:orchestrator-protocol.

RESULT Envelope

Wrap every response in the unified RESULT envelope before the result body. The envelope tells the orchestrator dispatcher the outcome without parsing the body.

Successful implementation (Changeset Summary):

RESULT
task_id: <id>
agent: editor
status: success
result_type: Changeset Summary

Human escalation (HUMAN_ESCALATION):

RESULT
task_id: <id>
agent: editor
status: escalation
result_type: HUMAN_ESCALATION

Model escalation (NEEDS_STRONGER_MODEL — Haiku editors only):

RESULT
task_id: <id>
agent: editor
status: escalation
result_type: NEEDS_STRONGER_MODEL

Acceptance criteria unmet (Failure Report):

RESULT
task_id: <id>
agent: editor
status: failure
result_type: Failure Report

Commit completion:

RESULT
task_id: commit-main
agent: editor
status: success
result_type: Commit Completion

The RESULT header is followed immediately by the result body defined in the sections below.

Example — successful implementation:

RESULT
task_id: implement-main
agent: editor
status: success
result_type: Changeset Summary

## Changeset Summary

**Issue:** 0079
**Model:** claude-sonnet-4-5
**Worktree path:** /home/user/Code/myproject

### Files changed

| File | Change |
|------|--------|
| skills/editor-protocol/SKILL.md | Added RESULT envelope documentation |

### Test results

No automated tests; manual review of Markdown formatting.

### Proposed commit subject

Define RESULT envelope in editor-protocol

### Issue reference

Closes #0079

TASK_DONE (transition period — still valid)

The legacy format remains accepted by the orchestrator during the transition period (see Issue 0083 for deprecation timeline). Emit TASK_DONE only if your implementation predates RESULT support; new implementations should use the RESULT envelope above.

TASK_DONE
task_id: <id>
result_block: <Changeset Summary | HUMAN_ESCALATION | Failure Report | Commit Completion>

Followed immediately by the result body block.

---

Changeset Summary (successful implementation)

## Changeset Summary

**Issue:** <issue ID from brief>
**Model:** <your model name as it appears in your system prompt>
**Worktree path:** <worktree path from input>

### Files changed

| File | Change |
|------|--------|
| path/to/file | what changed and why |

### Test results

<test command run and outcome — "All tests pass" or specific counts>

### Proposed commit subject

<imperative sentence, ≤50 chars>

### Proposed commit body (if needed)

<1–2 sentences explaining what changed and why, if non-obvious. Omit if subject is self-explanatory.>

### Issue reference

Fixes #<N>   ← bugs
Closes #<N>  ← features/chores
Fixes TODO-<NNNN>  ← standalone TODOs

---

HUMAN_ESCALATION (task exceeds human-safe scope)

Returned by any editor when the task cannot be safely completed by any automated agent and requires human judgment. The orchestrator surfaces this to the user and stops.

## HUMAN_ESCALATION

**Issue:** <issue ID from brief>

### Why escalation is needed

<concrete reason the task requires human judgment — e.g., ambiguous acceptance criteria, destructive operation, unclear authorization>

### Files that would need changes

<list of files identified as needing modification>

### Files modified (if any)

<list any files started but that should be reverted>

---

NEEDS_STRONGER_MODEL (task exceeds model capacity — Haiku editors only)

Returned by the Haiku editor when mid-implementation signals indicate the task exceeds Haiku's safe scope. The orchestrator spawns a Sonnet editor to take over with hint-only handoff. One model escalation per run — if already escalated, emit a Failure Report instead.

## NEEDS_STRONGER_MODEL

**Issue:** <issue ID from brief>

### Why stronger model is needed

<concrete mid-task signal that triggered escalation — e.g., "tests not converging after 2 attempts", "cross-cutting changes outside brief scope", "unfamiliar invariants in authentication layer">

### Partial edits made (hints for Sonnet)

<list any files modified and what was attempted — these are hints only, not authoritative; Sonnet must re-verify>

### Recommended entry point

<where Sonnet should start — e.g., "re-read src/auth/middleware.ts before adopting partial edits">

---

Failure Report (acceptance criteria cannot be met)

## Failure Report

**Issue:** <issue ID from brief>
**Phase:** Implementation

### What failed

<description of the failure — test output, unexpected code state, or plan invalidity>

### Files modified (if any)

<list any files partially modified — these may need manual cleanup>

### Recommended next step

<what the user should inspect or fix before re-invoking>

---

Commit Completion (commit task response)

Load code-forge:commit for all commit conventions and procedures (message format, PGP wait, heredoc pattern, cherry-pick, failure recovery).

Stage the files listed in the Changeset Summary's "Files changed" section, then follow the commit skill's procedure. Cherry-pick to main when done.

Respond with:

## Commit Completion

**Issue:** <issue ID from summary>
**Commit SHA:** <short SHA>
**Cherry-pick:** <success / failure>

Details:
- Committed: <subject line>
- Files staged: <list of files>
- Cherry-picked to: main (or reason for failure)

---

Mid-Task Escalation Triggers

Applies to code-forge:editor-haiku-agent only. The Sonnet editor does not escalate via NEEDS_STRONGER_MODEL.

Emit NEEDS_STRONGER_MODEL immediately when any of the following signals appear mid-implementation:

Signal	Example
Tests not converging	Same test failures after 2 fix attempts
Wrong entry points	Implementation requires files not in the brief's file list
Cross-cutting changes	A single fix touches 3+ modules or layers
Unfamiliar invariants	Code path has comments warning of subtle ordering requirements or security constraints

Escalation ladder: Haiku → Sonnet → human. One model escalation per run. After escalating to Sonnet, the Sonnet editor may emit HUMAN_ESCALATION but not NEEDS_STRONGER_MODEL.