ADR-004: Tool Surface — Phase 0 ships 14 tools (amended after R75 Wave H)

Status: Accepted, amended R75 Wave H (implementation reconciliation) Date: 2026-04-09 (R73 original), 2026-04-10 (R74.5 revision), 2026-04-18 (R75 Wave H amendment) Round: R74.5 (original) · R75 Wave H (amendment) Supersedes: None Superseded by: None

R75 Wave H amendment. The R74.5 revision locked a 19-tool Phase 0 target. Implementation through Waves A–G shipped 14 tools — 5 tools in the R74.5 table were never implemented (task_transition, task_delete, task_depends_on, server_info, server_shutdown, audit_session_end) and 1 shipping tool was omitted from the R74.5 table (thought_record_list). The decision to merge task_transition behavior into task_update was made during P0.3.4 implementation — task_update accepts a status field and routes transitions through the β state machine (src/domains/tasks/state-machine.ts). See the “Phase 0 shipped surface (R75 Wave H)” section below for the locked 14-tool inventory. The earlier R74.5 19-tool table is preserved in the genealogy section as the planned target. This is an amendment, not a supersession — ADR-004 remains Accepted.

R74.5 revision. The R73 original of this ADR set the long-term target at 60–80 tools across 10 domains. R74.5 tightened Phase 0 specifically to Option C: exactly 19 tools over stdio, matching S17 §1. The full 60–80 target remains the long-term Phase 1+ ceiling; Phase 0 is the minimum-viable subset. The 14 tools that actually shipped are a strict subset of the R74.5 plan except for thought_record_list, which was earned during P0.7.1.

Context

The AMS donor codebase (src/ before deletion in R53) exposed 484 MCP tools across 10+ domains. This number is accurate as an inventory of AMS history — it was AMS’s actual surface when running. After src/ was deleted in R53, the 484-tool claim persisted in docs/colibri-master-context.md, docs/reference/extractions/mcp-tools-complete-extraction.md, and MEMORY.md. In R73 the human asked: “там 484 тулза зачем то???” (“there are 484 tools why??”).

The honest answer: 484 is an AMS donor fact, not a Colibri target. Colibri is a clean rewrite. It needs its own target tool surface, planned from first principles.

Why 484 got so large in AMS

  • Legacy accretion — AMS grew over years, each domain adding tools without retirement
  • Ergonomic helpers — many tools were thin convenience wrappers around two or three underlying operations
  • Per-project variants — some tools had 3–5 variants differing only in default arguments
  • Debug and ops tools — many tools existed to support runtime diagnostics, monitoring, introspection
  • Historical experiments — several domains had tools that were created during experiments and never removed

None of this is wrong. It’s what happens when a real system runs for years. But Colibri’s clean rewrite gets to plan the surface rather than inherit it.

Decision

Colibri Phase 0 ships 14 tools over stdio (amended R75 Wave H — was a 19-tool plan; 5 planned tools were not implemented, 1 non-planned tool was added).

The long-term Phase 1+ ceiling remains 60–80 tools across 10 domains (the original R73 target). Phase 0 is a strict, minimum-viable subset of that surface — just enough to run the β Task Pipeline, the ζ/η proof chain, ε discovery, and a health-check boundary. Everything else is deferred.

Phase 0 shipped surface (R75 Wave H locked — 14 tools)

# Tool Concept Category Notes
1 task_create β Task Initial state INIT
2 task_list β Task Filters + pagination
3 task_get β Task Full detail
4 task_update β Task Partial mutable update; accepts status and routes through src/domains/tasks/state-machine.ts for FSM validation. No separate task_transition tool in Phase 0 — see §”task_update vs task_transition” below.
5 task_next_actions β Task Unblocked queue
6 audit_session_start ζ Audit Open proof-grade session
7 thought_record ζ Audit Hash-chained append
8 thought_record_list ζ Audit Read thought chain (earned during P0.7.1, not in original R74.5 table)
9 audit_verify_chain ζ Audit SHA-256 chain walk (shipped Wave G, P0.7.3)
10 merkle_finalize η Proof Build tree (MUST come after final reflection)
11 merkle_root η Proof Return root hash
12 skill_list ε Skill Read-only discovery of .agents/skills/
13 server_ping α/γ System <100 ms round-trip
14 server_health α/γ System DB open, middleware registered, runtime mode

Counts by category: 5 β Task · 4 ζ Audit · 2 η Proof · 1 ε (skill_list) · 2 System. Total = 14.

Tools from the R74.5 19-tool plan that did NOT ship in Phase 0

Planned tool Why not shipped Decision
task_transition Merged into task_update during P0.3.4 (state writes accepted; FSM enforced via state-machine.ts) Closed — behavior preserved in a simpler API
task_delete Not implemented in Wave C/D/E task tool set; CANCELLED state reachable via task_update { status: "CANCELLED" } Deferred — revisit in Phase 1 if cascade semantics are needed
task_depends_on Dependencies live in the schema (task_dependencies table), but no MCP tool surfaces them in Phase 0 Deferred to Phase 1
audit_session_end Sessions close implicitly when merkle_finalize runs; no explicit end tool implemented Closed — merkle_finalize is the session-close signal
server_info Not implemented. Capabilities and COLIBRI_MODE are reported by server_health Struck — server_info is a phantom tool; references in other docs are being removed
server_shutdown Shutdown is process-level (SIGTERM/SIGINT); no MCP-exposed shutdown tool Struck from Phase 0 — donor-era feature, revisit in Phase 1

task_update vs task_transition — behavioral spec (R75 Wave H amendment)

task_update accepts a status field and routes transitions through the β state machine (src/domains/tasks/state-machine.ts). A separate task_transition tool is NOT exposed in Phase 0 — the two were merged during P0.3.4 implementation. State-machine enforcement is preserved; the API surface is simpler.

Callers invoke task_update({ task_id, status: "GATHER" }) and the middleware:

  1. Loads the current task row.
  2. Calls transition(current_status, new_status, now) from state-machine.ts.
  3. Rejects illegal transitions with ERR_INVALID_TRANSITION.
  4. Commits the row if legal.

Direct status writes that would bypass the FSM are impossible because the state-machine call is inside the repository layer, not optional middleware.

What was dropped from the R73 target for Phase 0

Category Dropped tools Where they went
Skills hot-reload + registration path Deferred to Phase 1 (skill_get, skill_invoke, skill_register, skill_unregister are not in Phase 0)
Router all δ tools Deferred to Phase 1.5 per ADR-005. Phase 0 is Claude-only.
Integration all ν tools Deferred to P0.9 target implementation — ν exists as docs/ integration bridges, not as MCP tool names
Integrity μ verify/report/scan Deferred to Phase 4
Memory all memory_* tools Deferred entirely; reasoning state lives in the 6-tool ζ/η chain
Admin backup/metrics Merged into server_health (R75 Wave H: the R74.5 plan also merged some admin surface into server_info, which was later struck).
Tasks (extras) task_add_dependency (merged into task_depends_on), task_promote (replaced by task_transition), task_assign, task_block, task_unblock, task_cancel (replaced by task_transition { to: "CANCELLED" }), task_status_transition (renamed task_transition), task_comment Consolidated into the 8-tool β surface

This is less than 4% of the AMS donor surface — and it still covers every function the Phase 0 pipeline needs.

R73 original decision (preserved for genealogy)

Colibri Phase 0 targets 60–80 tools across 10 domains: System (4–6), Tasks (10–14), Skills (5–7), Thought (6–8), Merkle (5–7), Router (4–6), Integration (6–10), Integrity (3–5), Memory (4–6), Admin (3–5). Target range 50–74 tools at Phase 0 end, plus 10–20 for Phase 1–2 proof-grade extensions. Total long-term target 60–100 tools.

The R73 decision is kept as the Phase 1+ ceiling. The R74.5 revision narrows Phase 0 only to the 19-tool Option C subset above.

Consequences

Positive

  • Cognitive fit. A 60-tool surface is small enough that a new executor can read the whole reference in a sitting.
  • Easier testing. Fewer tools means fewer integration surfaces and fewer edge cases to cover.
  • Clearer ownership. Each tool maps to exactly one domain and one concept.
  • Scope discipline. If a new feature proposal requires more than two new tools, the feature probably needs its own ADR.
  • Security surface shrinks. Each tool is an attack surface; fewer tools is a smaller surface.

Negative

  • Migration surface is narrower. If a user of the AMS donor system relied on one of the 400+ tools we are not porting, they lose that functionality. Mitigation: AMS runtime (data/ams.db) continues to run during Phase 0 bootstrap as the task store, so the human’s PM session workflow is preserved.
  • Convenience helpers removed. Some flows will take two or three tool calls where AMS had one. Mitigation: Tier-1 chains in colibri-tier1-chains skill provide canonical sequences.
  • Re-extraction effort. Some AMS tools encapsulated nontrivial logic that must now be re-planned. Mitigation: the 49 extractions in docs/reference/extractions/ preserve every algorithm as pseudocode; nothing is lost, only re-organized.

Neutral

  • The “484” number is now explicitly a donor artifact and documented as such in docs/colibri-master-context.md (deprecation header) and docs/reference/extractions/mcp-tools-complete-extraction.md (marked as genealogy).

Implementation

Phase 0 tool reference

The authoritative Phase 0 target is docs/reference/mcp-tools-phase-0.md. That file must list every tool with:

  • Name and domain
  • Concept letter
  • TypeScript Zod schema
  • Preconditions and postconditions
  • Example invocation

Any tool not in that file is not in Phase 0. If a task needs a tool not listed, the task is blocked and Sigma is notified.

Running AMS donor runtime during bootstrap

The AMS donor runtime is still available at data/ams.db and its server binary. During Phase 0 bootstrap (P0.1 – P0.2), the following AMS tools are used by PM and executors for task store and writeback:

  • unified_init, unified_vitals, unified_set_project, task_next_actions
  • task_update, task_create, thought_record
  • audit_session_start, audit_verify_chain, merkle_finalize, merkle_root

These are the same names Colibri will expose, which allows a seamless switchover once P0.2 + P0.3 land. This is the one case where Colibri shares a namespace with AMS: the task store.

When does the switchover happen?

Once P0.3.4 (β Task Pipeline binding) is complete, Colibri’s own task tools are wired up. PM tests both runtimes side-by-side, then switches writeback from data/ams.db to data/colibri.db. AMS becomes read-only historical archive.

Alternatives Considered

Alternative A — Port all 484 AMS tools verbatim

Rejected. The whole point of the R53 deletion was to escape AMS’s legacy accretion. Re-porting everything throws away the clean slate.

Alternative B — Start with 20 tools and grow

Rejected as too minimal. The pipeline requires task + skill + thought + merkle + router + integration + system tools from day one. Below 50 total tools, the pipeline can’t run at all.

Alternative C — Different tool count per domain

Considered. The per-domain numbers above were chosen to match the minimum coverage the pipeline needs, not a uniform split. Some domains (Tasks, Integration) need more tools; others (Admin, Integrity) can be lean.

Alternative D — Defer the router until Phase 1.5

Accepted in a separate ADR (ADR-005). R75 Wave I update: Phase 0 shipped δ Model Router as library-only stubs (src/domains/router/scoring.ts + src/domains/router/fallback.ts — constant-returns-claude scoring + single-member fallback chain). No router_* MCP tools are registered in the 14-tool Phase 0 surface — δ is consulted internally by β’s dispatch layer. The MCP tool surface for δ lands in Phase 1.5 alongside real multi-model scoring. See ADR-005 §R75 Wave I.

Verification

This decision is verified if and only if (R75 Wave H amendment):

  • docs/reference/mcp-tools-phase-0.md lists the 14 tools that actually shipped in Phase 0 (the R75 Wave H inventory in §”Phase 0 shipped surface” above). The R73 figure of “50–80 tools” refers to the long-term Phase 1+ ceiling and is not the Phase 0 verification gate. The R74.5 figure of 19 tools was the plan; 14 are what shipped.
  • Each listed tool maps to exactly one concept letter.
  • Each listed tool has shipping src/ code (verified by live stdio boot at 09d462f8 — 14 tools returned).
  • docs/reference/extractions/mcp-tools-complete-extraction.md is explicitly marked “AMS donor genealogy — not a Colibri target”.

Verification is performed by Sigma at R80 Phase B (Phase 0 completion round).

References

  • docs/reference/extractions/mcp-tools-complete-extraction.md — AMS donor tool inventory (484)
  • docs/reference/mcp-tools-phase-0.md — Phase 0 target tool reference (60–80)
  • docs/concepts/α-system-core.md — System tools
  • docs/concepts/β-task-pipeline.md — Task tools
  • docs/concepts/ζ-decision-trail.md — Thought/audit tools
  • docs/concepts/η-proof-store.md — Merkle tools
  • docs/colibri-system.md §2 — Ground-truth counts

R73 unification corpus. Answers the “484 tools, why?” question raised by the human at R73 kickoff. Amended R75 Wave H to reflect that Phase 0 shipped 14 tools (not 19) — 5 planned tools were closed, struck, or deferred; 1 tool (thought_record_list) was added during implementation. See the R75 Wave H amendment note at the top of this ADR.

Back to top

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

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