Implement

---
description: "Implement a spec: read, plan, test-first, build, verify, deploy."
---

# Implement — Spec Workflow

Single entry point for implementing specs against the CP CLI codebase.

## User Input

```text
$ARGUMENTS

Parse the input:

• Shard ID — e.g. pf-c70f10 to implement a specific shard
• Spec file path — e.g. specs/cp-cli/SPEC-9-test-coverage.md or just SPEC-9
• Specific phase — e.g. SPEC-9 phase 2 to resume at a phase
• If no arguments, show assigned work:

  cxp shard list --type bug,task --assigned-to agent-steve
  

Configuration

AGENT_NAME: agent-steve
PROJECT: penfold
DB_CONN: "host=dev02.brown.chat dbname=contextpalace user=penfold sslmode=verify-full"
REPO_ROOT: ~/github/otherjamesbrown/context-palace

CRITICAL: You Write Code Directly

Unlike mycroft (who orchestrates sub-agents), you implement directly. You read the spec, write the code, run the tests. No delegation. This means:

• You own every file you touch — no conflicts
• You must manage your own context budget — if a spec has 4 phases, don't spend 80% on phase 1
• If you're running low on context, checkpoint and stop. Do NOT rush to finish.

Phase Flow

Phase 1:  READ      — Parse spec, identify deliverables, check what exists
Phase 2:  PLAN      — Break work into ordered deliverables, estimate scope per item
Phase 3:  TEST      — Write failing tests for current deliverable (test-first)
Phase 4:  BUILD     — Implement until tests pass
Phase 5:  VERIFY    — go test, go vet, go build, coverage check
Phase 6:  REPORT    — Checkpoint + message to penfold with results
Phase 7:  DEPLOY    — Build binary, install, verify (after ALL deliverables complete)

Phases 3-6 repeat for each deliverable. Do NOT implement everything then test everything. One deliverable at a time: test → build → verify → next.

Phase 7 runs once, after the last deliverable.

Phase 1: READ

1. Read the spec file completely
2. Read every source file referenced in the spec
3. Read pf-rules for project conventions:

   SELECT content FROM shards WHERE id = 'pf-rules';
   

4. Identify:
   • Deliverables — numbered items in "What to Build"
   • Dependencies — which deliverables must come first
   • Success criteria — what "done" looks like per deliverable
   • Test cases — specific tests listed in the spec
5. Check for existing work:

   git status
   git log --oneline -10
   

Output: Mental model of the work. No code written yet.

Phase 2: PLAN

1. Order deliverables by dependency (spec usually defines this)
2. For each deliverable, list:
   • Files to create or modify
   • Test file and test function names
   • Estimated lines of code
3. Check total scope against context budget:
   • < 500 LOC total: proceed with all deliverables
   • 500-1000 LOC: proceed but checkpoint between deliverables
   • > 1000 LOC: implement only the first N deliverables, checkpoint, tell penfold what remains
4. Log plan to the work shard:

   cxp shard append <shard-id> --body "Implementation plan: [SPEC-N]. Deliverables: [count]. Estimated: [LOC]. Order: [list]. Starting with: [first]."
   

CHECKPOINT after Phase 2.

Phase 3: TEST (per deliverable)

For the current deliverable:

1. Read the spec's test cases for this deliverable
2. Write the test file with all tests that will fail (functions exist but implementation is stub/missing)
3. Run the tests to confirm they fail:

   cd ~/github/otherjamesbrown/context-palace/cp && go test ./[package]/... -run "TestName" -v 2>&1 | head -50
   

4. If tests don't compile (missing types/functions), add minimal stubs to make them compile but fail

Do NOT skip this phase. Test-first catches spec misunderstandings before you write implementation.

Phase 4: BUILD (per deliverable)

1. Implement the deliverable — add/modify source files
2. Run the specific tests frequently:

   cd ~/github/otherjamesbrown/context-palace/cp && go test ./[package]/... -run "TestName" -v
   

3. Fix until all tests for this deliverable pass
4. Run the full package tests to check for regressions:

   cd ~/github/otherjamesbrown/context-palace/cp && go test ./[package]/...
   

API stability rule: Do NOT change existing function signatures. If you need a different interface, add a new function. Changing signatures cascades across the codebase.

Phase 5: VERIFY (per deliverable)

Run all three checks:

# 1. All tests pass (not just this deliverable)
cd ~/github/otherjamesbrown/context-palace/cp && go test ./...

# 2. No vet issues
cd ~/github/otherjamesbrown/context-palace/cp && go vet ./...

# 3. Clean build
cd ~/github/otherjamesbrown/context-palace/cp && go build ./...

If the spec has coverage targets:

cd ~/github/otherjamesbrown/context-palace/cp && go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out

If ANY check fails: fix it before proceeding. Do NOT move to the next deliverable with a broken build.

Phase 6: REPORT (per deliverable)

1. Write a checkpoint:

   cxp session checkpoint "$(cat <<'CKPT'
   ## Deliverable [N] complete: [name]
   
   **Files created/modified:** [list]
   **Tests:** [count] passing
   **Coverage:** [if applicable]
   **Next:** deliverable [N+1] — [name]
   CKPT
   )"
   

2. If more deliverables remain → repeat Phases 3-6 for the next one
3. If this is the last deliverable → proceed to Phase 7 (DEPLOY)

Phase 7: DEPLOY (once, after all deliverables)

All deliverables are verified. Now build, install, and confirm the binary works.

Step 1: Final full verification

cd ~/github/otherjamesbrown/context-palace/cp && go test ./... && go vet ./... && go build ./...