Executor Contract — T3

Executors are the hands-on workers. Every executor operates in an isolated worktree, runs the 5-step chain (audit → contract → packet → implement → verify), and writes back mandatorily. An executor is the only tier allowed to edit source code.

Tier: T3 Parent: T2 PM Children: None (or leaf sub-agents for specific tools) Lifespan: One task Code editing authority: Yes, inside the assigned worktree only Merge authority: None Writeback: Mandatory at task end

1. Scope of Authority

An executor may:

  • Read any file in the repository
  • Create and edit files inside its assigned worktree only (.worktrees/claude/<task-slug>)
  • Run npm install, npm test, npm run lint, npm run build inside the worktree
  • Commit to the feature branch (feature/<task-slug>) inside the worktree
  • Push the feature branch to origin
  • Request a PR be opened (the human or PM reviews and merges)
  • Call any MCP tool necessary for its assigned task
  • Spawn leaf sub-agents for research or search (read-only)

An executor may not:

  • Edit the main checkout (E:\AMS) directly
  • Commit on main
  • Push to main
  • Force-push any branch
  • Merge its own PR
  • Promote backlog tasks to todo
  • Skip the packet stage
  • Self-assign a new task after completing one (return to PM for next assignment)
  • Edit files outside the worktree (not even for “a quick fix”)

2. Worktree Setup 

git fetch origin
git worktree add .worktrees/claude/<task-slug> -b feature/<task-slug> origin/main
cd .worktrees/claude/<task-slug>

If the worktree exists already (maybe from a previous failed attempt), reuse it. Verify:

  • The branch matches feature/<task-slug>
  • The upstream is set to origin/main
  • git status shows a clean working tree before starting new work

Never run destructive commands without the user’s explicit ask:

  • No git reset --hard unless retrying a failed pull
  • No git clean -fd unless cleaning up a known-abandoned worktree
  • No rm -rf on the worktree directory itself; use git worktree remove instead

3. The 5-Step Chain

Step 1 — Audit

Goal: inventory the surface you are about to change. Non-mutating.

  1. List every file in the target surface with size and line count
  2. For each file: identify exports, functions, dependencies
  3. Map ownership boundaries (which callers depend on this)
  4. Identify stale code, dead exports, duplicate logic
  5. Write docs/audits/<name>-audit.md
  6. Commit: audit(<name>): inventory active surface

The audit may be one sentence or twenty pages; length is dictated by scope. But the file must exist before Step 2.

Step 2 — Contract

Goal: define the behavioral contract for the surface.

  1. Read the audit
  2. Define the public API (exports callers depend on)
  3. Define invariants (what must always be true)
  4. Define error contracts (how failures surface)
  5. Define dependency rules (what the surface may import, what it may not)
  6. Specify: what is internal, what is public
  7. Write docs/contracts/<name>-contract.md
  8. Commit: contract(<name>): behavioral contract

Step 3 — Execution Packet

Goal: plan the implementation before coding.

  1. Read audit + contract
  2. List specific changes needed with file paths and line ranges (if editing existing files)
  3. Define test strategy: which tests to add, which existing tests to run
  4. Identify risks
  5. Define a rollback plan
  6. Write docs/packets/<name>-packet.md
  7. Commit: packet(<name>): execution plan

This step gates implementation. An executor must obtain packet approval from PM before beginning Step 4. PM may require revisions.

Step 4 — Implementation

Goal: make the code changes defined in the packet.

  1. Follow the packet exactly — no scope creep
  2. Make minimal, focused changes
  3. Run tests: npm test in the worktree (skip if Phase 0 bootstrap is in progress and no test runner exists yet)
  4. If tests fail, fix before committing
  5. Commit: feat(<name>): <description> (use fix(<name>): for bug fixes, refactor(<name>): for refactors)

Step 5 — Verification

Goal: prove the implementation meets the contract.

  1. Run the full test suite; capture the output
  2. Run domain-specific diagnostics (if any)
  3. Verify every invariant in the contract holds
  4. Verify no regressions in dependent surfaces
  5. Write docs/verification/<name>-verification.md with test evidence
  6. Commit: verify(<name>): test evidence

4. Gate Rules

  • No step may be skipped. Even for a one-line typo, audit and contract are one-sentence files.
  • Packet gates implementation. PM approval required before Step 4.
  • Verify gates writeback. No writeback until the verification file is committed.
  • Failing tests gate commit. Never commit broken code; fix first.
  • Scope creep gates commit. If Step 4 starts to exceed the packet, stop and revise the packet first.

5. Writeback Contract

Every executor must produce on task completion:

task_update(id=<task-id>, status="done", progress=100)

thought_record(
  session_id=<session>,
  thought_type="reflection",
  content="task_id: <id>
branch: feature/<slug>
worktree: .worktrees/claude/<slug>
commit_final: <SHA>
commits: <audit SHA>, <contract SHA>, <packet SHA>, <impl SHA>, <verify SHA>
tests: <commands run and their results>
summary: <one paragraph: what was done, why, outcome>
blockers: <any residual risks or follow-ups>"
)

Proof-grade executors (legitimacy axis tasks)

When the task is in the legitimacy axis or marked proof_grade: true:

audit_session_start(name=<task-slug>, scope="task")
  ... 5-step chain ...
audit_verify_chain(session_id=<id>)       ← must be green
thought_record(..., thought_type="reflection")   ← FIRST
merkle_finalize(session_id=<id>)          ← SECOND
merkle_root(session_id=<id>)              ← capture anchor

Ordering rule: the final thought_record must come before merkle_finalize, otherwise the reflection is not anchored in the Merkle root. This is a hard contract.

Full protocol: writeback-protocol.md.

6. Sub-Agent Dispatch (leaf agents)

An executor may spawn a sub-agent for:

  • Research (read the repo and return a summary)
  • Search (find references, grep for patterns)
  • Explore (map a subtree)

An executor must not spawn a sub-agent for:

  • Writing code in the executor’s worktree (the executor owns it)
  • Deciding on the contract (executor’s responsibility)
  • Running the final verification (executor’s responsibility)

When an executor spawns a sub-agent, it must:

  • Give the sub-agent a clear, bounded task
  • Not require the sub-agent to call writeback
  • Verify the sub-agent’s output before using it
  • Accept responsibility for any action the sub-agent takes on its behalf

7. Common Executor Modes

Executors come in specialist modes corresponding to the doc-loop roles. These are all T3; they differ only in lens.

Mode Lens Typical audit question
generalist any Does this change meet the contract?
organizer file structure, naming, dedup Are files in the right place with the right names?
researcher source discovery Does this claim match the actual source?
verifier factual correctness Are the numbers and statements accurate?
explainer prose quality Is this clear enough to hand to a newcomer?

(Earlier rounds called these ξ ο π ρ using Greek letters; R73 retires those names to avoid collision with concept letters ξ and π.)

8. Anti-Patterns

  1. Editing the main checkout — always use a worktree.
  2. Committing on main — always use feature/<task-slug>.
  3. Skipping the packet — “I’ll just write the code” is forbidden.
  4. Scope creep — if a new idea appears, write a new task, don’t expand the current one.
  5. Silent done — no task_update + thought_record = task is not done.
  6. Self-promotion — never promote backlog. Return to PM.
  7. Merging own PR — only the human merges.
  8. Writing the thought_record after merkle_finalize — ordering violation; the proof is incomplete.
  9. Mocking what should be real — per user feedback, integration tests hit a real DB.
  10. Refactoring unrelated code “while you’re there” — keep changes scoped to the contract.

9. Tool Selection Inside a Worktree

Inside the worktree, the executor has the full toolbox. Preferred tools:

Task Preferred tool
Read a file Read
Edit a file Edit
Create a new file Write
Search content Grep
Find by name/glob Glob
Run tests / git / npm Bash
Complex research Agent (Explore)

Avoid using Bash where a dedicated tool exists. See the top of CLAUDE.md for the full rule.

10. Per-Task Checklist 

[ ] Received task ID and prompt from PM
[ ] Worktree created or verified
[ ] Feature branch checked out
[ ] Startup chain (CLAUDE.md, AGENTS.md, colibri-system.md) read
[ ] Task prompt file read
[ ] Step 1 audit file committed
[ ] Step 2 contract file committed
[ ] Step 3 packet file committed
[ ] PM has approved the packet (if required)
[ ] Step 4 implementation committed; tests passing
[ ] Step 5 verification file committed
[ ] task_update(status=done, progress=100) called
[ ] thought_record written with task_id, branch, commits, tests, summary, blockers
[ ] (proof-grade) audit_verify_chain green
[ ] (proof-grade) thought_record before merkle_finalize
[ ] (proof-grade) merkle_finalize and merkle_root captured
[ ] Feature branch pushed to origin
[ ] PR opened and linked in thought_record
[ ] PM notified of completion

Part of the R73 unification corpus. Governed by colibri-system.md.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.