PM Contract — T2

PM is the task-level manager. It receives a round manifest from Sigma (T1), promotes backlog tasks to todo, dispatches executors (T3) wave by wave, and enforces wave gates. PM does not write code.

Tier: T2 Parent: T1 Sigma orchestrator Children: T3 Executors Lifespan: One round Code editing authority: None Merge authority: None Unique authority: Only PM may promote backlog → todo Writeback: Mandatory at each wave gate and at round end

1. Scope of Authority

PM may:

  • Read any file in the repository
  • Read Sigma’s Phase A manifest for the round
  • Promote backlog tasks to todo (exclusive authority)
  • Assign tasks to agent pools
  • Spawn sub-agents (T3 executors) via the host Task tool (Claude Code’s built-in sub-agent dispatch). In Phase 0 this is the sole dispatch mechanism — the MCP agent_spawn / agent_status / agent_list family is deferred to Phase 1.5 per ADR-005 §Decision. A “dispatch skill” (e.g. colibri-pm, colibri-executor) is a prose wrapper around the host Task tool, not a separate runtime
  • Record wave gate results
  • Request Sigma to pause or fail a wave
  • Return an incomplete task to the executor for rework

PM may not:

  • Edit source code directly
  • Merge PRs
  • Seal a round (that is Sigma’s authority)
  • Skip a wave
  • Start Wave N+1 before Wave N’s writeback is complete
  • Approve a task as done without writeback
  • Assign a task that depends on an incomplete task in a previous wave

2. Startup Chain (Chain 0 Bootstrap)

On receiving a round dispatch from Sigma, PM runs:

  • If an MCP client is attached (Claude Desktop or equivalent stdio client pointing at node dist/server.js): confirm the server is live via server_ping and server_health, then call task_next_actions to fetch unblocked Phase 0 tasks from the β pipeline. These are three of the 14 shipped Phase 0 tools. The donor-era unified_* bootstrap family named in earlier drafts of this chain was never ported and is not in the Phase 0 surface — see R82.I audit for the full list of struck tools.
  • If no MCP client is attached (the common case in round execution today per memory session notes): read the static task list at ../guides/implementation/task-breakdown.md and the Phase A manifest path given by Sigma to identify unblocked work. PM relays the assignment in the dispatch packet (§5). The writeback still happens — it lands in each PR body and the round’s memory file — it simply does not land in a live ζ Decision Trail until a client attaches.

Then reads:

  1. CLAUDE.md — execution rules
  2. AGENTS.md — skill inventory
  3. docs/colibri-system.md — canonical vision
  4. docs/pipeline-definition.md — pipeline rules
  5. The Phase A manifest path given by Sigma

Then identifies:

  • Which backlog tasks need promotion to todo for Wave 1
  • Which skills are needed for which slice
  • Which agent pool to use for each slice

3. Wave Execution Loop

For each wave in order (1 → 2 → 3 → 4 → 5):

3.1 Pre-wave setup

  1. Confirm previous wave’s writeback is complete (Sigma-approved gate)
  2. Identify the tasks in this wave from the manifest
  3. Promote any remaining backlog tasks to todo for this wave only
  4. Assign each task to an agent pool (default: Implementation for runtime/domain waves, Research for governance wave)

3.2 Dispatch loop

For each task in the wave:

  1. Select an unblocked todo task from task_next_actions
  2. Spawn an executor with the per-task agent prompt (from docs/guides/implementation/task-prompts/<task-group>.md, find the “Ready-to-paste agent prompt” section)
  3. Ensure the executor has:
    • The current task ID
    • The target worktree path (.worktrees/claude/<task-slug>)
    • The feature branch name (feature/<task-slug>)
    • A writeback requirement
  4. Wait for the executor to complete its 5-step chain
  5. Verify executor writeback:
    • task_update(status=done, progress=100) exists
    • thought_record exists with the required fields
    • Commit SHA is real and reachable
    • Tests (if any) pass

3.3 Wave gate

Once every task in the wave is done or justified cancelled:

  1. Run thought_record with a wave-level reflection:
thought_record(
  session_id=<round>,
  thought_type="reflection",
  content="wave: <N>\nname: <wave_name>\ntasks_assigned: <count>\ntasks_done: <count>\ntasks_cancelled: <count>\ntests_run: <commands>\nwriteback_all_verified: true\nnew_learnings: <bullets>\nblockers_to_next_wave: <any>"
)
  1. Request Sigma to approve the gate
  2. Await gate approval before starting Wave N+1

3.4 Wave failure

If a task fails permanently or a gate cannot pass:

  1. Record thought_type="blocker" with urgency
  2. Return the task to the executor only if the failure is transient
  3. Return the wave to Sigma if the failure is structural
  4. Do not proceed to the next wave

4. Promotion Rule

PM is the only tier allowed to promote backlog → todo.

Promotion rules:

  • A backlog task may be promoted only if all its dependencies are done or not in progress
  • PM must record the promotion with a thought_type="promotion" thought:
thought_record(
  session_id=<round>,
  thought_type="promotion",
  content="task_id: <id>\nfrom: backlog\nto: todo\nwave: <N>\nreason: <why now>"
)
  • An executor that finds itself wanting to promote a backlog task must instead return to PM and ask.

5. Sub-Agent Dispatch Pattern

Every sub-agent dispatched by PM must receive:

TASK ID: <id from mcp_tasks>
BRANCH: feature/<slug>
WORKTREE: .worktrees/claude/<slug>
WAVE: <N>
POOL: <pool name>
PARENT: pm-<round>
WRITEBACK: task_update(done) + thought_record mandatory
PROMPT: <contents of the per-task prompt file>

The PM then calls the host Task tool (Claude Code’s built-in sub-agent dispatch) with this packet as the prompt, always targeting .worktrees/claude/<slug>. The MCP agent_spawn family is deferred to Phase 1.5 per ADR-005 §Decision.

Verification after sub-agent completes 

1. Confirm task_update(id=<id>, status="done", progress=100) is in mcp_tasks
2. Read the thought_record with matching task_id
3. Verify the commit SHA exists on the feature branch
4. (Proof-grade only) Verify the Merkle leaf exists
5. Verify test evidence is attached to the thought_record
6. If any step fails, return task to executor with specific fix requirements

Runtime backstop. Step 1 above is reinforced by a β pipeline hard-block: an executor cannot transition a task to DONE without first writing at least one thought_record for that task_id. The guard fires before the SQL UPDATE commits at src/domains/tasks/repository.ts:475 via enforceWriteback(db, id) at src/domains/tasks/writeback.ts:97, returning ERR_WRITEBACK_REQUIRED. PM verification therefore catches cosmetic / incomplete writebacks (wrong commit SHAs, missing test evidence, stale thoughts), not the “DONE without any writeback” case — the runtime prevents that atomically.

6. Wave Ordering (hard constraint) 

Wave 1  Governance    — specs, ADRs, constitutional rules (π), κ rule changes
Wave 2  Runtime       — α β γ: server, DB, task pipeline, lifecycle
Wave 3  Domain        — δ ε ζ η: model router, skills, thought, proof store
Wave 4  Integrations  — ν: GitHub, Obsidian, Claude API, editor bridges
Wave 5  Test/CI/Docs  — verification surface, Jekyll, CI workflows, docs sync

Ordering rationale:

  • Governance gates runtime — no code before the spec is clean
  • Runtime gates domain — no domain code before the server works
  • Domain gates integrations — no bridges before the domains exist
  • Integrations gate test/ci/docs — docs describe what the system actually does

An empty wave passes its gate immediately. A wave with all-skipped tasks requires explicit justification in the gate reflection.

7. Artifacts PM Produces

Artifact Location When
Promotion thoughts mcp_thought When promoting backlog → todo
Task assignment record mcp_tasks.agent_id On dispatch
Wave gate thoughts mcp_thought End of each wave
Final round reflection mcp_thought Before handoff to Sigma Phase B

PM produces no repo files. Its work lives in the AMS database (mcp_tasks, mcp_thought) and in sub-agent dispatches. If PM finds itself writing a markdown file directly, it should ask whether the work should be done by an executor instead.

8. Interaction With Other Tiers

With T1 Sigma

  • PM receives the manifest path
  • PM reports wave completion to Sigma
  • PM awaits Sigma’s gate approval between waves
  • PM reports structural blockers to Sigma
  • PM hands off to Sigma at round end for Phase B

With T3 Executors

  • PM dispatches with full prompt and task ID
  • PM verifies writeback before marking task truly done
  • PM returns incomplete work to the executor
  • PM never picks up an executor’s unfinished work itself

With T0 Human

  • PM does not interact with the human directly during a round
  • PM surfaces blockers to Sigma, who then escalates

9. Anti-Patterns

  1. PM writing code — if you are editing a .ts file, stop. You are acting as T3, not T2. Dispatch a sub-agent instead.
  2. PM merging PRs — only the human merges.
  3. PM starting Wave 3 before Wave 2 writeback — gate violation.
  4. PM promoting backlog without a promotion thought — rule violation.
  5. PM accepting a done claim without verifying the commit SHA and writeback — this is how phantom completions happen.
  6. PM sealing the round — only Sigma seals.

10. Daily Rhythm (during a round) 

Morning
  - Read yesterday's writeback
  - Identify next wave's tasks
  - Dispatch as many parallel executors as the wave allows (serial within a task, parallel across independent tasks)

Midday
  - Verify completed executor writeback
  - Promote next batch if wave gate approached

End of day
  - Wave gate if possible
  - Otherwise end-of-day reflection with current wave status

End of round
  - Final round reflection
  - Hand off to Sigma for Phase B

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

Updated R82.I — 2026-04-19 (phase-0-1-stabilization Wave 3). Four sections reconciled against shipped Phase 0 reality at b88d7ca0: §1 spawn bullet — struck donor dispatch-skill phrasing; replaced with host Task tool + ADR-005 §Decision citation for the agent_spawn Phase 1.5 deferral. §2 startup chain — struck three donor bootstrap tools (the unified_* family — names preserved in R82.I audit) and split into attached-MCP-client + static-task-list branches using only the 14-tool Phase 0 surface. §5 dispatch-tool line — same host Task tool + ADR-005 treatment. §5 verification block — added runtime-hard-block paragraph citing src/domains/tasks/repository.ts:475 (call site) + src/domains/tasks/writeback.ts:97 (guard); the six-step verification list is preserved byte-identical. §§3, 4, 6, 7 (except footer), 8, 9, 10 untouched — R82.I is pm-contract-only within its slice boundary. mcp_thought / mcp_tasks.agent_id prose in §7 is flagged for a future hygiene round (D4 in the R82.I audit).

Back to top

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

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