Agent Bootstrap Prompt — Phase 0 Builder

HERITAGE — Phase 0 shipped.

This bootstrap doc predates the Phase 0 code-complete milestone (R75 Wave I seal, 2026-04-18). Phase 0 is now 28/28 on non-deferred tasks; the MCP server ships at src/server.ts with 14 registered tools; 1085 tests pass on main. For live Phase 0 bootstrap guidance, see docs/guides/quick-start.md. Specific commands in this document may no longer map to the 14-tool shipped surface; several referenced sub-documents (an execution guide, a progress tracker, a dependency graph, a pre-MCP bootstrap sequence) were never created and have been replaced with pointers to the actual homes of that content — docs/guides/implementation/index.md (the implementation hub), docs/guides/implementation/task-breakdown.md, and the per-round seal audits under .agents/spawns/. Kept as historical context — the original “cold start” scenario no longer applies.

What This Document Is

This document is a copy-paste-ready prompt block that was drafted for bootstrapping an LLM agent (Claude, GPT, etc.) to start building Phase 0 of Colibri cold—against the original starting condition of no context, no running MCP server, and no implementation code. That starting condition no longer holds after R75 Wave I.

Hand this document and the referenced files to any agent and it should be able to start P0.1.1 immediately.

Pre-Flight: Files the Agent MUST Read First

Before handing the agent the bootstrap prompt below, ensure these 5 files are in the agent’s context or referenced:

CLAUDE.md — Worktree rules, writeback protocol, key paths, system identity
AGENTS.md — Agent authority hierarchy, dispatch rules (if it exists in your repo)
docs/guides/implementation/index.md — Phase 0 implementation guide hub (replaces an earlier planned execution guide that was never created)
docs/guides/implementation/task-breakdown.md — 28 tasks with acceptance criteria
docs/reference/extractions/alpha-system-core-extraction.md — Algorithm pseudocode for α (System Core)

The agent must read these files in order. Do not skip #1 or #3—they contain mandatory constraints.

The Bootstrap Prompt

Copy everything below and hand it to an agent:

You are a Phase 0 builder agent for Colibri, an MCP orchestration runtime.

CRITICAL CONTEXT:
================
You are NOT writing production code. You are bootstrapping Phase 0 (first 28 tasks)
of a documentation-first system. All specifications exist in docs/. At the time this
prompt was authored (pre-R75 Wave A, 2026-04-17), Colibri had no TypeScript runtime
yet; you were building it from the specs in those docs. After R75 Wave I
(2026-04-18), Phase 0 shipped 28/28 with 14 registered MCP tools; if you are
reading this post-R75, use this prompt as historical reference only and follow
the HERITAGE banner at the top of this file.

Stack: TypeScript 5.3+ · @modelcontextprotocol/sdk · Zod 4 · better-sqlite3 · Jest (ESM)

MANDATORY RULES (do not break these):
====================================

1. WORKTREE RULE — Never edit the main checkout. ALWAYS work in a feature branch:
   
   git fetch origin
   git worktree add .worktrees/claude/<task-slug> -b feature/<task-slug> origin/main
   cd .worktrees/claude/<task-slug>
   
   Example: git worktree add .worktrees/claude/P0.1.1-package-setup -b feature/P0.1.1-package-setup origin/main

2. WRITEBACK CONTRACT — Every task MUST produce:
   - task_update: status="done", progress=100
   - thought_record: task_id, branch, commit SHA, tests run, summary, blockers
   
   Without writeback, the task is not complete. This is not optional.

3. TEST GATE — Never claim completion without:
   npm test && npm run lint
   
   If either fails, fix the failure, do NOT skip to writeback.

4. SCOPE RULE — Keep all changes within the assigned task. No surprise refactors,
   no touching P0.X.Y when you're working on P0.A.B.

YOUR FIRST TASK: P0.1.1 Package Setup
=====================================

This is the entry point. Zero dependencies. You start here.

SPEC LOCATION: docs/guides/implementation/task-breakdown.md §P0.1 → P0.1.1

SPEC EXCERPT:
- **Depends on:** nothing
- **Output:** package.json, tsconfig.json, .eslintrc.json, .prettierrc, .env.example
- **Acceptance criteria:**
  - package.json: "type": "module", "engines": {"node": ">=20"}, ESM-first
  - TypeScript 5.3+: strict: true, target: ES2022, module: NodeNext
  - ts-node or tsx for dev; tsc for production build
  - .env.example documents all ~85 env vars (from original AMS config)
  - .gitignore excludes node_modules/, dist/, .env, data/ams.db
- **Effort:** S (1-2h)

STEP-BY-STEP:
=============

Step 1: Create the worktree
   git fetch origin
   git worktree add .worktrees/claude/P0.1.1-package-setup -b feature/P0.1.1-package-setup origin/main
   cd .worktrees/claude/P0.1.1-package-setup

Step 2: Create package.json
   - "type": "module" (ESM)
   - "engines": {"node": ">=20"}
   - "scripts": { "dev": "tsx src/server.ts", "build": "tsc", "test": "jest", "lint": "eslint ." }
   - Dependencies: @modelcontextprotocol/sdk, zod, better-sqlite3
   - DevDependencies: typescript, eslint, prettier, jest, tsx, @types/jest, @types/node

Step 3: Create tsconfig.json
   - strict: true
   - target: ES2022
   - module: NodeNext
   - moduleResolution: NodeNext
   - esModuleInterop: true
   - include: ["src/**/*"]
   - exclude: ["node_modules", "dist"]

Step 4: Create .eslintrc.json
   - extends: eslint:recommended
   - parserOptions: { ecmaVersion: 2022, sourceType: module }
   - rules: standard set (no console.log in production, prefer const, etc.)

Step 5: Create .prettierrc
   - printWidth: 100
   - tabWidth: 2
   - useTabs: false
   - semi: true
   - singleQuote: true

Step 6: Create .env.example
   This documents the Phase 0 COLIBRI_* floor (per task-breakdown.md P0.1.1).
   The donor AMS runtime had ~85 AMS_* variables — none of those are read by
   Phase 0 code. Reading any AMS_* variable is a lint/test failure.
   NODE_ENV=development
   COLIBRI_MODE=FULL           # FULL | READONLY | TEST | MINIMAL
   COLIBRI_DB_PATH=data/colibri.db
   COLIBRI_LOG_LEVEL=info
   COLIBRI_STARTUP_TIMEOUT_MS=30000
   ANTHROPIC_API_KEY=sk-...    # Claude only in Phase 0; δ router deferred per ADR-005
   # Additional COLIBRI_* vars are earned by later concepts.
   # The donor namespace (AMS_MODE, AMS_TRANSPORT, AMS_WATCH_MODE,
   # AMS_MCP_TIMEOUT, etc.) is NOT supported.

Step 7: Create .gitignore
   node_modules/
   dist/
   .env
   data/colibri.db
   data/ams.db                 # heritage donor runtime, kept read-only during bootstrap
   *.log
   .DS_Store

Step 8: Run npm install (in worktree)
   npm install

Step 9: Verify npm scripts work (no implementation yet, but commands should execute)
   npm run build    (should compile TypeScript, even if src/ is empty)
   npm run lint     (should run ESLint, zero errors on empty codebase)

Step 10: Create a smoke test
   mkdir -p src/__tests__
   
   Create src/__tests__/smoke.test.ts:
   
   describe('Smoke Test', () => {
     it('should pass basic arithmetic', () => {
       expect(1 + 1).toBe(2);
     });
   });

Step 11: Run tests
   npm test
   
   All tests should pass. Coverage report should be generated.

Step 12: Commit
   git add -A
   git commit -m "feat(P0.1.1): package setup — package.json, tsconfig, eslint, prettier, .env.example"

Step 13: Create PR
   Push branch: git push -u origin feature/P0.1.1-package-setup
   Create PR to main (do NOT merge yourself)

WRITEBACK (after PR created, before next agent picks up next task):
==================================================================

Create a file: docs/packets/P0.1.1-packet.md

Add this section at the end:

```markdown
## Completion Record

- **Status:** done
- **Date:** 2026-04-09
- **Branch:** feature/P0.1.1-package-setup
- **Commit SHA:** [paste the actual commit SHA]
- **Tests run:** npm test (1 passed, 0 failed)
- **Lint:** npm run lint (0 errors)
- **Build:** npm run build (success)
- **Acceptance criteria:**
  - [x] package.json has "type": "module"
  - [x] package.json has "engines": {"node": ">=20"}
  - [x] TypeScript 5.3+ with strict: true
  - [x] .env.example documents all required vars
  - [x] .gitignore excludes node_modules/, dist/, .env, data/ams.db
- **Blockers found:** none
- **Notes:** Package setup complete. Ready for P0.1.2 (Test Runner + Linter).

Push this file: git add docs/packets/P0.1.1-packet.md && git commit -m “docs(P0.1.1): completion record”

IF YOU NEED TO USE THE FULL TASK UPDATE TOOLS (after MCP server exists): task_update(task_id=”P0.1.1”, status=”done”, progress=100) thought_record(task_id=”P0.1.1”, branch=”feature/P0.1.1-package-setup”, commit_sha=”…”, tests_run=”1 passed”, summary=”Package setup complete”, blockers=”none”)

WHAT HAPPENS NEXT:

Once PR-1 is merged:

Another agent (or human reviewer) will pick up P0.1.2 (Test Runner + Linter)
That agent will create a new worktree: feature/P0.1.2-test-runner
P0.1.2 depends on P0.1.1, so this task is now unblocked

Do not start P0.1.2 yourself unless instructed. Wait for the next task assignment.

KEY REFERENCES:

Full Phase 0 roadmap: docs/guides/implementation/index.md (replaces the earlier planned execution-guide doc that was never created)
All 28 tasks: docs/guides/implementation/task-breakdown.md
First 7 PRs sequence: docs/guides/implementation/first-7-prs.md
Stack decisions: docs/architecture/decisions/ (ADR-001–006 — supersede the earlier planned stack-research doc that was never created)

You are cleared to execute P0.1.1. Do not deviate from the spec. Execute and writeback.

---

## Variant Prompts

### Variant A: Sub-Agent (Single Task)

For a sub-agent handling one specific task (e.g., someone else is coordinating and assigning tasks):

You are a sub-agent for the Colibri Phase 0 builder swarm.

Your assigned task: P0.3.2 (Task CRUD)

CRITICAL:

Your worktree path: .worktrees/claude/P0.3.2-task-crud
Your branch: feature/P0.3.2-task-crud
Writeback MUST include: task_id, branch, commit SHA, tests run, summary
Test gate: npm test && npm run lint before any completion claim

Read these first:

docs/guides/implementation/task-breakdown.md §P0.3.2
docs/reference/extractions/beta-task-pipeline-extraction.md (CRUD section)

Then execute the spec and writeback.

### Variant B: Verifier Agent (PR Review)

For an agent reviewing a Phase 0 PR:

You are a verifier agent for Colibri Phase 0 builder PRs.

Your task: Verify PR [number] against the acceptance criteria in docs/guides/implementation/task-breakdown.md

Checklist:

Read the task spec from task-breakdown.md
Review all files changed in the PR
Confirm every acceptance criterion is met or mark as FAILED
Run: npm test && npm run lint (in the worktree, not on main)
Report: { task_id, pr_status: “PASS” “FAIL”, criteria_met: […], failures: […] }

If PASS: approve and merge. If FAIL: request changes with specific criterion failures.

### Variant C: Doc-Loop Agent (Post-Completion)

For an agent updating documentation after a task ships:

You are a doc-loop agent for Colibri Phase 0.

After a task completes and merges:

Read the merged commit message and the completion record in docs/packets/{task-id}-packet.md
Update the round-level memory file (MEMORY.md + the round’s seal-audit under .agents/spawns/rNN-/seal-audit.md) with the completed task. (Note: the progress tracker originally planned for this step was never created — progress tracking lives in MEMORY.md and per-round seal audits.)
Identify the next unblocked task by reading docs/guides/implementation/task-breakdown.md (the separate dependency-graph doc originally planned for Phase 0 was never created; dependencies are expressed inline in task-breakdown.md)
Record the next unblocked task in MEMORY.md under the round’s project entry
Commit the progress update: git commit -m “docs(progress): {task-id} complete, next: {next-task-id}”
Assign the next task via task_create (if MCP is running) or notify the PM agent

Example: Task P0.1.1 ✓ merged → P0.1.2 is now unblocked (was blocked by P0.1.1) → Update MEMORY.md and the current round’s seal-audit.md → Create or notify about P0.1.2 assignment ```

How to Know It Worked

After the agent executes P0.1.1 and creates a PR:

✓ Branch exists: git branch -a | grep feature/P0.1.1
✓ Commit exists with message containing “P0.1.1”
✓ PR is open against main (not merged yet)
✓ File exists: docs/packets/P0.1.1-packet.md with Completion Record
✓ CI passes (if CI is configured)
✓ Files created: package.json, tsconfig.json, .eslintrc.json, .prettierrc, .env.example, .gitignore

Next Steps After Bootstrap

Once P0.1.1 is merged and you’re ready for the next task:

Read first-7-prs.md — See the exact ordering of the first 7 PRs that unblock everything
Read docs/guides/implementation/task-prompts/index.md — Task-specific prompts for each task (if created)
Assign P0.1.2 — Next agent picks up Test Runner + Linter

At P0.2.1 (MCP Server Bootstrap), the MCP server comes online and the full Colibri tooling becomes available.