P0.3 — β Task Pipeline — Agent Prompts

Copy-paste-ready prompts for agents tackling each task in this group. Canonical spec: task-breakdown.md §P0.3 Master bootstrap prompt: agent-bootstrap.md

Group summary

Task ID	Title	Depends on	Effort	Unblocks
P0.3.1	GSD State Machine	P0.2.2	S	P0.3.2
P0.3.2	Task CRUD	P0.3.1	M	P0.3.3
P0.3.3	Writeback Contract Enforcement	P0.3.2	S	P0.3.4
P0.3.4	Task Tools (MCP surface)	P0.3.3, P0.2.1	M	P0.5.1, P0.6.x

---

P0.3.1 — GSD State Machine

Spec source: task-breakdown.md §P0.3.1
Extraction reference: docs/reference/extractions/beta-task-pipeline-extraction.md
Worktree: feature/p0-3-1-state-machine
Branch command: git worktree add .worktrees/claude/p0-3-1-state-machine -b feature/p0-3-1-state-machine origin/main
Estimated effort: S (Small — 1-2 hours)
Depends on: P0.2.2 (Database initialized)
Unblocks: P0.3.2 (Task CRUD requires valid state transitions)

Files to create

• src/domains/tasks/state-machine.ts — Core FSM with 7 states and transition logic
• tests/domains/tasks/state-machine.test.ts — Full branch coverage + invalid transition tests

Acceptance criteria

• 7 states defined: backlog | todo | in_progress | blocked | review | done | cancelled
• Valid transitions map enforced (e.g., backlog → todo, todo → in_progress)
• Invalid transition throws InvalidTransitionError with {from, to, taskId}
• transition(task, newState) returns updated task or throws
• canTransition(from, to) pure boolean with no side effects
• 100% branch coverage (all valid + invalid transitions tested)

Pre-flight reading

• CLAUDE.md — worktree rules and writeback protocol
• docs/guides/implementation/task-breakdown.md §P0.3.1 — full spec
• docs/reference/extractions/beta-task-pipeline-extraction.md — state machine algorithm
• docs/guides/implementation/p0.3-beta-task-pipeline.md — sibling task specs (P0.3.2, P0.3.3, P0.3.4)

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

TASK: P0.3.1 — GSD State Machine
Create the task state machine with 7 states and transition validation.

FILES TO READ FIRST:
1. CLAUDE.md (worktree rules, writeback protocol)
2. docs/guides/implementation/task-breakdown.md §P0.3.1
3. docs/reference/extractions/beta-task-pipeline-extraction.md (state machine section)

WORKTREE SETUP:
git fetch origin
git worktree add .worktrees/claude/p0-3-1-state-machine -b feature/p0-3-1-state-machine origin/main
cd .worktrees/claude/p0-3-1-state-machine

FILES TO CREATE:
- src/domains/tasks/state-machine.ts
  * Export 7 states as const enum: backlog, todo, in_progress, blocked, review, done, cancelled
  * Freeze transition map object (not a function) for type narrowing
  * transition(task, newState) → updated task or throws InvalidTransitionError
  * canTransition(from, to) → boolean (pure, no side effects)
  * Define InvalidTransitionError with {from, to, taskId} in error message

- tests/domains/tasks/state-machine.test.ts
  * Test all valid transitions from each state
  * Test all invalid transitions → verify InvalidTransitionError thrown
  * Test canTransition returns correct boolean
  * Test transition returns mutated task object with new state
  * Verify 100% branch coverage

ACCEPTANCE CRITERIA (headline):
✓ 7 states defined, transitions frozen as object
✓ Invalid → InvalidTransitionError with {from,to,taskId}
✓ transition() returns updated task; canTransition() pure
✓ 100% branch coverage

SUCCESS CHECK:
cd .worktrees/claude/p0-3-1-state-machine && npm test && npm run lint

WRITEBACK (after success):
task_update(task_id="P0.3.1", status="done", progress=100)
thought_record(task_id="P0.3.1", branch="feature/p0-3-1-state-machine", 
  commit_sha=<your-sha>, tests_run=["npm test","npm run lint"], 
  summary="Implemented 7-state FSM with frozen transition map, all valid/invalid paths tested")

FORBIDDENS:
✗ Do not use function-based transitions (breaks type narrowing)
✗ Do not hardcode task status anywhere else yet (only state-machine.ts)
✗ Do not edit main checkout directly; always use worktree

NEXT:
P0.3.2 — Task CRUD (depends on this state machine being solid)

Verification checklist (for reviewer agent)

• Transition map is frozen object, not function
• 7 states all defined as const enum or string literal type
• InvalidTransitionError includes {from, to, taskId}
• canTransition is pure (no DB calls, no side effects)
• Test coverage >= 100% on state-machine.ts
• npm test and npm run lint pass

Writeback template

task_update:
  task_id: P0.3.1
  status: done
  progress: 100

thought_record:
  task_id: P0.3.1
  branch: feature/p0-3-1-state-machine
  commit_sha: <sha>
  tests_run: ["npm test", "npm run lint"]
  summary: "Implemented GSD state machine with 7 states (backlog/todo/in_progress/blocked/review/done/cancelled), frozen transition map for type safety, InvalidTransitionError on invalid transitions. All valid and invalid transition paths tested with 100% branch coverage."
  blockers: []

Common gotchas

• FSM transitions must be frozen object, not function — TypeScript narrowing relies on the transition map being a literal object so the compiler can prove a state is valid. A function breaks that guarantee. Use as const on the transitions object.
• canTransition must have zero side effects — it’s called during UI rendering and data validation before any database operation. If it hits the DB, you’ll have race conditions.
• State names are cargo-culted from AMS donor code — verify these 7 states match the donor extraction. If donor has additional states, check with PM before adding them (backlog scope).

---

P0.3.2 — Task CRUD

Spec source: task-breakdown.md §P0.3.2
Extraction reference: docs/reference/extractions/beta-task-pipeline-extraction.md
Worktree: feature/p0-3-2-task-crud
Branch command: git worktree add .worktrees/claude/p0-3-2-task-crud -b feature/p0-3-2-task-crud origin/main
Estimated effort: M (Medium — 2-3 hours)
Depends on: P0.3.1 (State machine must be solid)
Unblocks: P0.3.3 (Writeback enforcement needs CRUD to update tasks)

Files to create

• src/domains/tasks/repository.ts — Task table CRUD with better-sqlite3 prepared statements
• tests/domains/tasks/repository.test.ts — Full CRUD roundtrip tests

Acceptance criteria

• createTask(input) inserts into tasks table, returns task with UUID v4 id
• getTask(id) returns task or null
• updateTask(id, patch) partial update, returns updated task
• deleteTask(id) soft delete (sets deleted_at timestamp)
• listTasks({ status?, project_id?, limit?, offset? }) filtered + paginated
• All operations use better-sqlite3 prepared statements (NO string interpolation)
• Test: CRUD roundtrip with all fields

Pre-flight reading

• CLAUDE.md — worktree rules
• docs/guides/implementation/task-breakdown.md §P0.3.2 — full spec
• docs/reference/extractions/beta-task-pipeline-extraction.md (CRUD section)
• src/db/schema.sql — verify task table schema

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

TASK: P0.3.2 — Task CRUD
Implement createTask, getTask, updateTask, deleteTask, listTasks using better-sqlite3.

FILES TO READ FIRST:
1. CLAUDE.md (worktree rules)
2. docs/guides/implementation/task-breakdown.md §P0.3.2
3. docs/reference/extractions/beta-task-pipeline-extraction.md (CRUD section)
4. src/db/schema.sql (task table schema)

WORKTREE SETUP:
git fetch origin
git worktree add .worktrees/claude/p0-3-2-task-crud -b feature/p0-3-2-task-crud origin/main
cd .worktrees/claude/p0-3-2-task-crud

FILES TO CREATE:
- src/domains/tasks/repository.ts
  * createTask(input): insert, return task with UUID v4 id
  * getTask(id): return task or null
  * updateTask(id, patch): partial update, return updated
  * deleteTask(id): soft delete (set deleted_at), return void
  * listTasks(filters): filtered + paginated
  * All DB calls use prepared statements (db.prepare())
  * No string interpolation in SQL

- tests/domains/tasks/repository.test.ts
  * Test create → get roundtrip
  * Test partial update preserves unmodified fields
  * Test soft delete (deleted_at set, not removed)
  * Test listTasks filters by status + project_id
  * Test pagination (limit, offset)
  * Test all CRUD in one transaction scenario

ACCEPTANCE CRITERIA (headline):
✓ createTask returns task with UUID v4 id
✓ CRUD roundtrip complete: create → get → update → delete
✓ All DB calls prepared statements (no string interpolation)
✓ listTasks supports status, project_id, limit, offset filters
✓ deleteTask soft deletes (sets deleted_at)

SUCCESS CHECK:
cd .worktrees/claude/p0-3-2-task-crud && npm test && npm run lint

WRITEBACK (after success):
task_update(task_id="P0.3.2", status="done", progress=100)
thought_record(task_id="P0.3.2", branch="feature/p0-3-2-task-crud",
  commit_sha=<your-sha>, tests_run=["npm test","npm run lint"],
  summary="Implemented CRUD repository with prepared statements, soft delete, pagination. Full roundtrip tested.")

FORBIDDENS:
✗ No string interpolation in SQL (use ? placeholders)
✗ Do not hardcode database path (use injected db instance)
✗ Do not commit state validation here (that's P0.3.3)
✗ Do not edit main checkout

NEXT:
P0.3.3 — Writeback Contract Enforcement (verifies tasks are marked done with thought records)

Verification checklist (for reviewer agent)

• All SQL uses prepared statements with ? placeholders
• UUID v4 generation (use crypto.randomUUID() or uuid package)
• Soft delete only sets deleted_at, doesn’t remove row
• listTasks pagination works (limit, offset)
• Test coverage includes CRUD roundtrip
• npm test and npm run lint pass

Writeback template

task_update:
  task_id: P0.3.2
  status: done
  progress: 100

thought_record:
  task_id: P0.3.2
  branch: feature/p0-3-2-task-crud
  commit_sha: <sha>
  tests_run: ["npm test", "npm run lint"]
  summary: "Implemented Task CRUD repository with createTask, getTask, updateTask, deleteTask, listTasks. All queries use better-sqlite3 prepared statements. Soft delete sets deleted_at timestamp. Pagination and filtering (status, project_id) tested. Full CRUD roundtrip verified."
  blockers: []

Common gotchas

• Prepared statements must use ? placeholders — better-sqlite3 caches prepared statements by exact SQL text. If you use string interpolation, every unique ID creates a new statement and defeats the cache.
• UUID v4 generation — Node.js has crypto.randomUUID() built-in since 15.7.0. Alternatively use uuid package. Just don’t leave IDs uninitialized.
• Soft delete vs. hard delete — the spec says soft delete. Don’t physically remove rows. This preserves audit trails and foreign key integrity.

---

P0.3.3 — Writeback Contract Enforcement

Spec source: task-breakdown.md §P0.3.3
Extraction reference: docs/reference/extractions/beta-task-pipeline-extraction.md
Worktree: feature/p0-3-3-writeback
Branch command: git worktree add .worktrees/claude/p0-3-3-writeback -b feature/p0-3-3-writeback origin/main
Estimated effort: S (Small — 1-2 hours)
Depends on: P0.3.2 (Need Task CRUD to mark tasks done)
Unblocks: P0.3.4 (Task tools enforce writeback before returning)

Files to create

• src/domains/tasks/writeback.ts — Writeback contract validation logic
• tests/domains/tasks/writeback.test.ts — Tests for required vs. satisfied contracts

Acceptance criteria

• writebackRequired(taskId) returns true if task is done but lacks thought_record
• enforceWriteback(taskId) throws WritebackRequiredError if contract not satisfied
• Runtime blocking: any tool that moves task to done MUST call enforceWriteback before returning
• WritebackRequiredError includes taskId, missing_fields[]
• Test: marking task done without thought_record → error; with thought_record → success

Pre-flight reading

• CLAUDE.md — worktree rules
• docs/guides/implementation/task-breakdown.md §P0.3.3 — full spec
• docs/reference/extractions/beta-task-pipeline-extraction.md (writeback section)

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

TASK: P0.3.3 — Writeback Contract Enforcement
Block tasks from being marked "done" without a thought_record.

FILES TO READ FIRST:
1. CLAUDE.md (execution rules, writeback requirement)
2. docs/guides/implementation/task-breakdown.md §P0.3.3
3. docs/reference/extractions/beta-task-pipeline-extraction.md (writeback section)

WORKTREE SETUP:
git fetch origin
git worktree add .worktrees/claude/p0-3-3-writeback -b feature/p0-3-3-writeback origin/main
cd .worktrees/claude/p0-3-3-writeback

FILES TO CREATE:
- src/domains/tasks/writeback.ts
  * writebackRequired(taskId: string): boolean
    - Return true if task.status == "done" AND no thought_record exists
    - Return false otherwise
  * enforceWriteback(taskId: string): void
    - If writebackRequired(taskId) is true, throw WritebackRequiredError
    - WritebackRequiredError must include {taskId, missing_fields: ["thought_record"]}
  * Export WritebackRequiredError class extending Error

- tests/domains/tasks/writeback.test.ts
  * Test writebackRequired(id) returns true for done task without thought_record
  * Test writebackRequired(id) returns false for done task with thought_record
  * Test enforceWriteback(id) throws on missing writeback
  * Test enforceWriteback(id) succeeds when writeback present
  * Test error message includes taskId and missing_fields

ACCEPTANCE CRITERIA (headline):
✓ writebackRequired identifies tasks needing writeback
✓ enforceWriteback throws WritebackRequiredError with {taskId, missing_fields}
✓ Runtime blocking: P0.3.4 tools call enforceWriteback before returning
✓ Test marks done without thought_record → error

SUCCESS CHECK:
cd .worktrees/claude/p0-3-3-writeback && npm test && npm run lint

WRITEBACK (after success):
task_update(task_id="P0.3.3", status="done", progress=100)
thought_record(task_id="P0.3.3", branch="feature/p0-3-3-writeback",
  commit_sha=<your-sha>, tests_run=["npm test","npm run lint"],
  summary="Implemented writeback contract enforcement. writebackRequired() identifies tasks needing thought_record. enforceWriteback() blocks completion without writeback.")

FORBIDDENS:
✗ Do not query thought records directly here (that's P0.7); trust writebackRequired input
✗ Do not silently succeed when writeback missing (must throw)
✗ Do not edit main checkout

NEXT:
P0.3.4 — Task Tools (integrates this enforcement into MCP surface)

Verification checklist (for reviewer agent)

• WritebackRequiredError is custom Error class
• Error message includes taskId and missing_fields array
• writebackRequired is pure (no side effects)
• enforceWriteback throws on contract violation
• Test covers both success and error paths
• npm test and npm run lint pass

Writeback template

task_update:
  task_id: P0.3.3
  status: done
  progress: 100

thought_record:
  task_id: P0.3.3
  branch: feature/p0-3-3-writeback
  commit_sha: <sha>
  tests_run: ["npm test", "npm run lint"]
  summary: "Implemented writeback contract enforcement. writebackRequired(taskId) checks if done task lacks thought_record. enforceWriteback(taskId) throws WritebackRequiredError if contract not satisfied. Runtime blocking ensures tools cannot mark tasks done without proof of work."
  blockers: []

Common gotchas

• Don’t query thought records here directly — this module is domain-agnostic. It returns a boolean for “is writeback required” and lets the caller (P0.3.4 tools) decide whether to call the thought_record endpoint or database query.
• Error must include missing_fields array — plural, even if only one field. Agents need to know which fields are missing.
• Writeback is REQUIRED, not optional — this is the legitimacy axis. No silent passes.

---

P0.3.4 — Task Tools (MCP surface)

Spec source: task-breakdown.md §P0.3.4
Extraction reference: docs/reference/extractions/beta-task-pipeline-extraction.md
Worktree: feature/p0-3-4-task-tools
Branch command: git worktree add .worktrees/claude/p0-3-4-task-tools -b feature/p0-3-4-task-tools origin/main
Estimated effort: M (Medium — 2-3 hours)
Depends on: P0.3.3 (Writeback enforcement), P0.2.1 (MCP server)
Unblocks: P0.5.1, P0.6.x, and agents spawn with task orchestration

Files to create

• src/tools/tasks.ts — MCP tool definitions and handlers
• tests/tools/tasks.test.ts — Tool input validation + FSM + writeback tests

Acceptance criteria

• task_create tool: Zod input schema, calls createTask, returns task
• task_get tool: returns task or { error: "not_found" }
• task_update tool: partial update with FSM validation on state change
• task_list tool: supports status, limit, offset filters
• task_next_actions tool: returns unblocked todo tasks sorted by priority
• task_update with status: "done" triggers writeback enforcement
• All tools have Zod input validation (invalid input → structured error, not crash)

Pre-flight reading

• CLAUDE.md — worktree rules
• docs/guides/implementation/task-breakdown.md §P0.3.4 — full spec
• docs/reference/extractions/beta-task-pipeline-extraction.md (tools section)
• src/server.ts — how to register tools with registerTool helper

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

TASK: P0.3.4 — Task Tools (MCP surface)
Expose CRUD + FSM + writeback enforcement as MCP tools.

FILES TO READ FIRST:
1. CLAUDE.md (execution rules)
2. docs/guides/implementation/task-breakdown.md §P0.3.4
3. docs/reference/extractions/beta-task-pipeline-extraction.md (tools section)
4. src/server.ts (registerTool pattern)
5. src/domains/tasks/ (state-machine.ts, repository.ts, writeback.ts)

WORKTREE SETUP:
git fetch origin
git worktree add .worktrees/claude/p0-3-4-task-tools -b feature/p0-3-4-task-tools origin/main
cd .worktrees/claude/p0-3-4-task-tools

FILES TO CREATE:
- src/tools/tasks.ts
  * task_create(input): Zod schema with title, description, status, project_id
    - Call repository.createTask(), return task
  * task_get(input): Zod schema with id
    - Call repository.getTask(), return task or {error:"not_found"}
  * task_update(input): Zod schema with id, status?, title?, ...
    - Validate new status via state-machine.canTransition()
    - Call repository.updateTask()
    - If status="done", call writeback.enforceWriteback(id)
    - Return updated task or error
  * task_list(input): Zod schema with status?, limit, offset
    - Call repository.listTasks(filters)
    - Return {tasks[], total_count}
  * task_next_actions(input): no parameters
    - Call repository.listTasks({status: "todo"})
    - Sort by priority (assume task.priority field exists)
    - Return unblocked tasks only

- tests/tools/tasks.test.ts
  * Test task_create with Zod validation (invalid input fails gracefully)
  * Test task_update with invalid state transition → FSM error
  * Test task_update with status="done" without writeback → WritebackRequiredError
  * Test task_list filters + pagination
  * Test task_next_actions returns only todo (sorted by priority)
  * Test all tools have Zod error handling (structured errors)

ACCEPTANCE CRITERIA (headline):
✓ 5 tools: task_create, task_get, task_update, task_list, task_next_actions
✓ task_update validates FSM transitions
✓ task_update status="done" enforces writeback
✓ All tools have Zod input validation (no unvalidated input)
✓ All tools return structured errors (never crash)

SUCCESS CHECK:
cd .worktrees/claude/p0-3-4-task-tools && npm test && npm run lint

WRITEBACK (after success):
task_update(task_id="P0.3.4", status="done", progress=100)
thought_record(task_id="P0.3.4", branch="feature/p0-3-4-task-tools",
  commit_sha=<your-sha>, tests_run=["npm test","npm run lint"],
  summary="Implemented 5 MCP tools for task CRUD + FSM + writeback. task_update validates state transitions and enforces writeback for done status.")

FORBIDDENS:
✗ Do not skip FSM validation on state changes
✗ Do not skip writeback enforcement for status="done"
✗ Do not use unvalidated input (all tools need Zod schema)
✗ Do not edit main checkout

NEXT:
P0.5.1 — Intent Scoring Matrix (uses task priority for routing decisions)
P0.6.1 — Skill Schema (agents use task_next_actions to spawn work)

Verification checklist (for reviewer agent)

• All 5 tools registered with server.registerTool()
• All tools have Zod input schema
• task_update calls state-machine.canTransition() before state change
• task_update status=”done” calls writeback.enforceWriteback()
• task_list supports status, limit, offset filters
• task_next_actions returns todo tasks sorted by priority
• Test covers Zod validation errors (input validation)
• npm test and npm run lint pass

Writeback template

task_update:
  task_id: P0.3.4
  status: done
  progress: 100

thought_record:
  task_id: P0.3.4
  branch: feature/p0-3-4-task-tools
  commit_sha: <sha>
  tests_run: ["npm test", "npm run lint"]
  summary: "Implemented 5 MCP tools: task_create (Zod validated), task_get, task_update (FSM validation + writeback enforcement), task_list (filtered + paginated), task_next_actions (unblocked todos sorted by priority). All tools have Zod input validation; all tools return structured errors."
  blockers: []

Common gotchas

• FSM validation before state change — task_update must call canTransition BEFORE updating the database. If the state is invalid, throw InvalidTransitionError before any DB write.
• Writeback enforcement is blocking — when task_update gets status: "done", call enforceWriteback(id) before returning success. If it throws, propagate the error to the client.
• task_next_actions assumes priority field — the task schema must include a priority field. If it doesn’t exist yet, define it in P0.2.2’s schema.sql. Fallback: sort by created_at if priority is missing.
• Zod error handling — Zod parse errors are thrown as ZodError. Catch them and return a structured error response (not a 500 crash). Example: { error: "invalid_input", details: error.issues }

---

Next group

p0.4-gamma-lifecycle.md — γ Server Lifecycle (2 tasks: Runtime Mode Enum, Graceful Shutdown)

Back to task-prompts index