Colibri master flow

One chart, 15 steps, four tiers. Every piece of work in Colibri — whether a one-line typo fix or a full Phase 0 domain — follows the same shape. Memorise this flow and you can answer “what happens next?” at any point in a round without looking anything up.

0. Who is on the field

Tier Role What they write What they cannot do
T0 Human (owner) Intent, acceptance Nothing in the code paths — only merge and veto
T1 Sigma orchestrator Round plans, round seals, writeback audits Write code, promote tasks, merge PRs
T2 PM Task promotions, wave dispatch, gate decisions Write code, merge PRs
T3 Executor Audit/contract/packet/implement/verify artifacts, commits, thought records Merge PRs, promote backlog, plan rounds
T4 Model Token-level completions inside T3’s chain Reach outside T3’s prompt — no independent state

Full contracts: agents/sigma-orchestrator.md, agents/pm-contract.md, agents/executor-contract.md.

1. The 15 steps

Step 1 — Intent (T0)

What happens. The human states what they want: “finish the how-it-works folder”, “wire the R74 palette”, “ship P0.1 bootstrap”. Intent enters the system as prose in a conversation or a GitHub issue.

Tool fired. None. The intent is raw English.

Output. An idea in the owner’s head or in a chat log. Not yet tracked.

Next step waits on. Sigma seeing the intent (manual handoff).

Step 2 — Phase A: round plan (T1 Sigma)

What happens. Sigma opens a round (R<n>), decomposes the intent into backlog tasks, chooses an axis (execution / intelligence / legitimacy), and writes a one-page round plan under docs/roadmap/R<n>-<theme>.md. Sigma does NOT assign executors yet.

Tool fired. task_create for each new backlog task, with status="backlog", round tag, axis tag, and dependency edges. thought_record(thought_type="plan") for the decomposition rationale.

Output. N new mcp_tasks rows in backlog. One markdown round plan. One thought in ζ.

Next step waits on. PM promoting at least one task into todo.

Full protocol: agents/sigma-orchestrator.md §2.

Step 3 — Promotion (T2 PM)

What happens. PM walks the backlog, selects the next ready task (all dependencies done, no blockers), and calls task_update(status="todo"). Only PM is allowed to do this — see agents/pm-contract.md §3.

Tool fired. task_update(id=<task>, status="todo").

Output. The task row flips from backlog → todo. Downstream tools like task_next_actions now return it.

Next step waits on. An idle executor picking the task up.

Step 4 — Pick-up (T3 Executor)

What happens. An executor runs the Chain 0 Bootstrap (CLAUDE.md §4): reads CLAUDE.md, AGENTS.md, colibri-system.md, runs unified_init, unified_vitals, unified_set_project, then task_next_actions to see the todo list. It picks the first unblocked task.

Tool fired. unified_init · unified_vitals · unified_set_project · task_next_actions · task_update(status="in_progress").

Output. The task row flips todo → in_progress. A new audit session may start here for proof-grade tasks (audit_session_start).

Next step waits on. The executor entering a worktree.

Step 5 — Worktree creation

What happens. The executor creates or reuses a git worktree at .worktrees/claude/<task-slug> on a fresh branch off origin/main. Main checkout is NEVER edited directly — see surfaces.md §2.

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

Output. A new filesystem path under .worktrees/claude/ ready for edits. A new local branch feature/<task-slug>.

Next step waits on. The executor beginning the 5-step chain.

Step 6 — Audit (5-step chain, step 1)

What happens. The executor inventories the current state of the area they are about to change. “What files exist? What contracts bind them? What tests cover them today?” Writes docs/audits/<name>-audit.md.

Tool fired. Editor writes, plus an optional thought_record(thought_type="observation").

Output. One markdown audit file. One commit audit(<name>): inventory surface.

Next step waits on. Contract write-up.

Step 7 — Contract (5-step chain, step 2)

What happens. The executor writes the behavioural contract the change must honour: inputs, outputs, failure modes, invariants. Writes docs/contracts/<name>-contract.md.

Tool fired. Editor writes.

Output. One markdown contract file. One commit contract(<name>): behavioral contract.

Next step waits on. Packet approval.

Step 8 — Packet (5-step chain, step 3)

What happens. The executor drafts the implementation packet: “here is the plan, file by file, commit by commit, with test hooks”. The packet gates the implementation — it must be approved (by PM or the human owner in solo mode) before the executor touches code. See round.md §5.2.

Tool fired. Editor writes.

Output. One markdown packet file. One commit packet(<name>): execution plan. One approval from PM.

Next step waits on. The approval signal. If not approved, the executor iterates on the packet before proceeding.

Step 9 — Implement (5-step chain, step 4)

What happens. The executor writes the actual code changes, one commit per coherent step, following the packet. No scope creep — anything outside the packet is a separate task.

Tool fired. File edits. git commit -m "feat(<name>): <change>" for each coherent chunk. thought_record(thought_type="observation") for non-obvious design calls.

Output. N source code commits on the feature branch.

Next step waits on. The verification step confirming green tests.

Step 10 — Verify (5-step chain, step 5)

What happens. The executor runs the test suite, lint, and any verification scripts required by the packet. Writes docs/verification/<name>-verification.md with evidence (command output, test counts, coverage deltas).

Tool fired. npm test && npm run lint (once Phase 0 bootstrap is done; until then, the gate is a dry-run note). Editor writes the verification file. git commit -m "verify(<name>): test evidence".

Output. One markdown verification file. One commit.

Next step waits on. Writeback.

Step 11 — Writeback: thought record

What happens. The executor writes the mandatory reflection into ζ. This MUST contain task_id, branch, worktree, commit, tests, summary, blockers. See agents/writeback-protocol.md §2.

Tool fired. thought_record(thought_type="reflection", content=...). For proof-grade tasks, audit_verify_chain(session_id=...) fires first to re-walk the hash chain.

Output. One row in mcp_thought with thought_type="reflection".

Next step waits on. The Merkle step — for proof-grade tasks only. For regular tasks, it goes straight to task close.

Step 12 — Writeback: Merkle finalise (proof-grade only)

What happens. For any task in the legitimacy axis or marked proof_grade: true, the executor calls merkle_finalize to build the Merkle tree from the session’s thoughts. The reflection MUST already be on chain — that is why step 11 fires first. See decision-trail.md §5.

Tool fired. merkle_finalize(session_id=...) → merkle_root(session_id=...).

Output. One mcp_merkle row with status="finalized" and a root hash. The root can now be used as a receipt.

Next step waits on. Task close.

Step 13 — Task close

What happens. The executor calls task_update(status="done", progress=100). The row flips to terminal state. PM sees it disappear from task_next_actions.

Tool fired. task_update(id=<task>, status="done", progress=100).

Output. mcp_tasks row at done.

Next step waits on. The pull request.

Step 14 — PR open and merge

What happens. The executor pushes the feature branch (after unset GITHUB_TOKEN — see ../memory/feedback_git_push_auth.md) and opens a PR via gh pr create. Only T0 (Human) may merge. See surfaces.md §3.

Tool fired. git push -u origin feature/<task-slug> (with GITHUB_TOKEN unset) → gh pr create → (T0) gh pr merge.

Output. One PR in GitHub. One merged commit on origin/main. GitHub Pages rebuilds if docs changed.

Next step waits on. The round sealing (only once all tasks in the round are merged) AND surface sync.

Step 15 — Phase B seal and surface sync (T1 Sigma + automation)

What happens. When every task in the round is done and merged, Sigma runs the round’s Phase B seal: audits the writeback (every task has a thought + optional Merkle), writes docs/roadmap/R<n>-seal.md, and emits a thought_type="seal" record. Meanwhile, the Obsidian vault mirror zone is synced via integration_obsidian_sync (which is hard-coded to /E /XD .git _vault — never /MIR, see 4-additions/index.md §3).

Tool fired. Sigma: thought_record(thought_type="seal"). Automation: integration_obsidian_sync(source, target).

Output. One round seal document. A Merkle root for the round (if proof-grade). Four surfaces aligned: repo, GitHub remote, GitHub Pages, Obsidian vault.

Next step waits on. The next intent. The loop begins again at step 1.

2. Visual shape 

T0 intent
   │
   ▼
T1 Sigma ──► round plan (backlog rows + thought)
   │
   ▼
T2 PM    ──► promote (backlog → todo)
   │
   ▼
T3 Executor
   │   ┌── pick up
   │   ├── worktree
   │   ├── audit
   │   ├── contract
   │   ├── packet  ◄── approval gate (PM/T0)
   │   ├── implement
   │   ├── verify
   │   ├── thought_record (reflection)
   │   ├── merkle_finalize   [proof-grade only]
   │   ├── task_update(done)
   │   └── PR open
   │
   ▼
T0 merge
   │
   ▼
T1 Sigma ──► Phase B seal + Obsidian sync
   │
   ▼
(loop)

Read top-to-bottom for a single task. Read the loop back to “intent” for round-over-round progress.

3. What each step produces, at a glance

Step Writer Output Location
1 Intent T0 Prose Chat / issue
2 Round plan T1 Markdown + backlog rows + plan thought docs/roadmap/ + mcp_tasks + mcp_thought
3 Promotion T2 Row state change mcp_tasks
4 Pick-up T3 Row state change + init thought mcp_tasks + mcp_thought
5 Worktree T3 Filesystem path + branch .worktrees/claude/ + local git
6 Audit T3 Markdown docs/audits/
7 Contract T3 Markdown docs/contracts/
8 Packet T3 Markdown + approval docs/packets/ + PM acknowledgment
9 Implement T3 Source commits Feature branch
10 Verify T3 Markdown + test run docs/verification/
11 Reflection T3 Thought row mcp_thought
12 Merkle T3 Merkle rows mcp_merkle · mcp_merkle_leaf · mcp_merkle_node
13 Close T3 Row state change mcp_tasks
14 PR/merge T3 open, T0 merge PR + merge commit GitHub
15 Seal + sync T1 + automation Seal doc + seal thought + vault sync docs/roadmap/ + mcp_thought + Obsidian vault

4. Gates that can stop the flow

These are the points where work can legitimately halt, not bugs:

  • Step 2 → 3: PM may refuse to promote if the backlog task is underspecified. Sigma reworks the plan.
  • Step 8 → 9 (packet gate): PM or T0 may reject the packet. The executor iterates before implementing.
  • Step 10 (verify): Tests may fail. The executor fixes them in place — no new task.
  • Step 11 ↔ 12 (ordering): If the reflection is missing when merkle_finalize fires, η rejects with ordering_violation. See proof-store.md §3.
  • Step 14 (merge): T0 may veto a PR. Executor addresses the review feedback.
  • Step 15 (seal): Sigma may fail the writeback audit (missing thoughts, missing roots). The round does NOT seal until fixed.

Each gate is a feature, not a friction point. They are the system’s way of refusing to move forward when a legitimacy invariant is not met.

5. Where the axes enter

The same 15 steps run for every task regardless of axis. The axes differ in what gets written, not in how it flows:

  • Execution-axis task: produces code and tests under src/ and tests/. Step 12 (Merkle) is optional.
  • Intelligence-axis task: produces routing / memory / context code. Same.
  • Legitimacy-axis task: Step 12 (Merkle) is MANDATORY. Step 11 MUST precede step 12. The writeback audit at step 15 inspects the Merkle root.

See world-schema.md for the axis mapping of all 15 Greek concepts.

6. What breaks if you shortcut the flow

Shortcut Immediate symptom Downstream fracture
Skip audit (step 6) Contract is uninformed; may reference non-existent files Packet has to be rewritten, burning steps 7–8
Skip contract (step 7) Packet has no invariants to check against Verification at step 10 has nothing to prove
Skip packet gate (step 8 → 9) Implementation drifts from intent PR rejected at step 14, rework from step 9
Skip reflection (step 11) No audit trail for the task Round seal fails at step 15; audit_verify_chain returns thought_missing
Reflection after Merkle Reflection is not in the Merkle root Proof does not cover the actual work; round seal fails at step 15
Merge on main directly (skip step 14) Feature branch is discarded No PR record, no review, writeback audit breaks at step 15

Every “shortcut” is really a postponement — the cost surfaces later, usually at the seal, and is more expensive to fix there than if the step had run in order.

7. Where to look next

Part of the R74 documentation finish pass. 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.