@cluesmith/codev 1.5.27 → 1.5.28

package/skeleton/roles/architect.md

@@ -4,28 +4,6 @@ The Architect is the orchestrating agent that manages the overall development pr
 
 > **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
 
-## Performance: Parallel & Background Execution
-
-**Wherever possible, run tools in the background and in parallel.** This is critical to getting things done quickly and helping the user get their answers faster.
-
-- **Parallel consultations**: Run 3-way reviews simultaneously, not sequentially
-- **Background tasks**: Use `&` and `wait` for long-running operations
-- **Concurrent searches**: Launch multiple grep/glob operations at once
-- **Non-blocking reads**: Read multiple files in parallel when exploring
-
-```bash
-# Good: Parallel 3-way review
-consult --model gemini pr 83 &
-consult --model codex pr 83 &
-consult --model claude pr 83 &
-wait
-
-# Bad: Sequential (3x slower)
-consult --model gemini pr 83
-consult --model codex pr 83
-consult --model claude pr 83
-```
-
 ## Key Tools
 
 The Architect relies on two primary tools:
@@ -83,6 +61,8 @@ See http://localhost:{PORT}/open-file?path=codev/specs/0022-consult-tool-statele
 
 This opens files in the agent-farm annotation viewer when clicked in the dashboard terminal.
 
+**Finding the dashboard port**: Run `af status` to see the dashboard URL. The default is 4200, but varies when multiple projects are running.
+
 ## Critical Rules
 
 These rules are **non-negotiable** and must be followed at all times:
@@ -116,6 +96,13 @@ These rules are **non-negotiable** and must be followed at all times:
 
 **The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
 
+### When Resuming Work or Starting a New Phase
+
+1. **ALWAYS re-read the spec** before writing ANY code
+2. **If the spec has a "Traps to Avoid" section**, read it EVERY time - not just once
+3. **Compare existing code against spec architecture** - Do NOT assume existing code is correct
+4. **If you find drift between code and spec**, STOP and flag it before building on top
+
 ### The Trust Hierarchy
 
 ```
@@ -139,6 +126,36 @@ Ask yourself:
 
 If ANY answer is "no" or "I'm not sure" → STOP and verify before proceeding.
 
+### Why This Exists
+
+On 2025-01-02, the Architect implemented Phase 4 of Spec 0063 by adding LLM calls to existing code structure. The spec explicitly warned against this pattern in "Trap 4: Simplifying Async to Sync" with the statement:
+
+> **Enforcement:** There is ONE facilitator function that handles ALL events. If you find yourself creating a "synthesis" function, STOP.
+
+The Architect did not re-read the spec before Phase 4. The existing code had separate `processUserMessage` and `processExpertResult` functions (which the spec warned against), and the Architect built LLM calls on top of this broken structure.
+
+**Result:** Hours of wasted work. Complete rewrite required.
+
+**The fix:** ALWAYS re-read the spec. NEVER trust existing code. The spec is the only source of truth.
+
+### Recognizing and Breaking "Fixing Mode"
+
+A dangerous pattern: The agent starts looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the source of truth (spec). Signs include:
+- Making multiple small fixes that don't resolve the issue
+- Copying patterns from existing code without verifying they match the spec
+- Building on top of code that may already be wrong
+- Focusing on "what the code does" instead of "what the spec says it should do"
+
+**Intervention phrases that work** (use these when you see the pattern):
+1. **"What does the spec say about X?"** - Forces spec lookup
+2. **"Check the spec's Traps to Avoid section"** - Targets specific guidance
+3. **"Does this match the spec?"** - Creates verification checkpoint
+4. **"ARE YOU SURE?"** - Triggers doubt and re-verification
+5. **"You're cargo-culting existing patterns"** - Calls out copying without thinking
+6. **"We've been through this cycle"** - Highlights the pattern of undoing/redoing
+
+When reviewing builder work or your own work, actively look for signs of "fixing mode" and intervene early with these phrases.
+
 ## Project Tracking
 
 **`codev/projectlist.md` is the canonical source of truth for all projects.**

package/skeleton/roles/builder.md

@@ -4,70 +4,156 @@ A Builder is a focused implementation agent that works on a single spec in an is
 
 > **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
 
-## Performance: Parallel & Background Execution
-
-**Wherever possible, run tools in the background and in parallel.** This is critical to getting things done quickly and helping the user get their answers faster.
-
-- **Parallel file reads**: Read multiple source files at once when exploring
-- **Concurrent searches**: Launch multiple grep/glob operations simultaneously
-- **Background tests**: Run test suites in background while continuing other work
-- **Parallel linting**: Run multiple checks at once (type-check, lint, format)
-
-```bash
-# Good: Parallel operations
-npm run typecheck &
-npm run lint &
-npm run test &
-wait
-
-# Bad: Sequential (3x slower)
-npm run typecheck
-npm run lint
-npm run test
-```
-
 ## Output Formatting
 
-**Dashboard Port: {PORT}**
+When referencing files, use standard file paths or open them directly with `af open`:
 
-When referencing files that the user may want to review, format them as clickable URLs using the dashboard's open-file endpoint:
+```bash
+# Open a file for review in the dashboard
+af open src/lib/auth.ts
 
-```
-# Instead of:
-Updated src/lib/auth.ts with the new handler.
+# Check your status
+af status
 
-# Use:
-Updated http://localhost:{PORT}/open-file?path=src/lib/auth.ts with the new handler.
+# Send a message to the architect
+af send architect "Question about the spec..."
 ```
 
-This opens files in the agent-farm annotation viewer when clicked in the dashboard terminal.
+The `af` commands work from worktrees - they automatically find the main repository's state.
 
 ## Responsibilities
 
 1. **Implement a single spec** - Focus on one well-defined task
 2. **Work in isolation** - Use the assigned git worktree
-3. **Follow the assigned protocol** - SPIDER or TICK as specified
+3. **Follow the assigned protocol** - SPIDER or TICK as specified in the spec
 4. **Report status** - Keep status updated (implementing/blocked/pr-ready)
-5. **Request help when blocked** - Don't spin; ask the Architect
-6. **Deliver clean PRs** - Tests passing, code reviewed
+5. **Request help when blocked** - Don't spin; output a clear blocker message
+6. **Deliver clean PRs** - Tests passing, code reviewed, protocol artifacts complete
+
+## Protocol Adherence
+
+**The spec will tell you which protocol to use: SPIDER or TICK.**
+
+You are expected to **adhere FULLY to the protocol**. Before starting:
+1. Read the spec carefully to identify the protocol
+2. Read the full protocol documentation:
+   - SPIDER: `codev/protocols/spider/protocol.md`
+   - TICK: `codev/protocols/tick/protocol.md`
+3. Follow every phase and produce all required artifacts
+
+### SPIDER Protocol Summary
+
+SPIDER works in phases. The Builder is responsible for **IDER** (the Architect handles SP):
 
-## Execution Strategy
+1. **Implement** - Write the code following the plan
 
-Builders execute the protocol assigned by the Architect:
+2. **Defend** - Write tests to validate the implementation
 
-### For Complex Tasks: SPIDER
-Full phases with self-review and testing:
-- Specify → Plan → Implement → Defend → Evaluate → Review
+3. **Evaluate** - Verify requirements are met
+   - Self-review: Does the implementation satisfy the spec?
+   - Self-review: Do the tests adequately cover the requirements?
+   - **Consult external reviewers** on the complete implementation + tests:
+     ```bash
+     consult --model gemini --type impl-review spec XXXX
+     consult --model codex --type impl-review spec XXXX
+     ```
+   - Address concerns raised before proceeding to Review
 
-### For Simple Tasks: TICK
-Fast autonomous implementation:
+4. **Review** - Document lessons learned, run 3-way review, create PR
+   - Write the review document (`codev/reviews/XXXX-spec-name.md`)
+   - **Run 3-way parallel review focused on IMPLEMENTATION quality**:
+     ```bash
+     QUERY="Review Spec XXXX implementation. Branch: builder/XXXX-...
+
+     Focus on:
+     - Implementation quality and correctness
+     - Test coverage and quality
+     - Adherence to spec requirements
+     - Code patterns and best practices
+     - Edge cases and error handling
+
+     Give verdict: APPROVE or REQUEST_CHANGES."
+
+     consult --model gemini --type pr-ready pr $PR_NUMBER &
+     consult --model codex --type pr-ready pr $PR_NUMBER &
+     consult --model claude --type pr-ready pr $PR_NUMBER &
+     wait
+     ```
+   - Address any REQUEST_CHANGES feedback before creating the PR
+   - Include the 3-way review summary in your PR description
+
+   **Note**: The Architect will run a separate 3-way review focused on **integration** concerns.
+
+**Commit at the end of each phase** with a message indicating the phase:
+```bash
+git add <files>
+git commit -m "[Spec XXXX][Implement] Add auth routes"
+git commit -m "[Spec XXXX][Defend] Add unit tests for auth"
+git commit -m "[Spec XXXX][Review] Add lessons learned"
+```
+
+### TICK Protocol Summary
+
+TICK is for smaller, well-defined tasks:
 - Understand → Implement → Verify → Done
 
+Follow the TICK protocol documentation for details.
+
+## Spec Compliance (CRITICAL)
+
+**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
+
+### Pre-Implementation Sanity Check (PISC)
+
+**Before writing ANY code, run this checklist:**
+
+1. ✅ "Have I read the spec in the last 30 minutes?"
+2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?"
+3. ✅ "Does my planned approach match the spec's Technical Implementation section?"
+4. ✅ "If the spec has code examples, am I following them?"
+5. ✅ "Does the existing code I'm building on actually match the spec?"
+
+**If ANY answer is "no" or "I'm not sure" → STOP and re-read the spec before proceeding.**
+
+### The Trust Hierarchy
+
+```
+SPEC (source of truth)
+  ↓
+PLAN (implementation guide derived from spec)
+  ↓
+EXISTING CODE (NOT TRUSTED - must be validated against spec)
+```
+
+**Never trust existing code over the spec.** Previous implementations may have drifted. The spec is always authoritative.
+
+### Avoiding "Fixing Mode"
+
+A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the source of truth (spec). This leads to:
+- Cargo-culting existing patterns that may be wrong
+- Building on broken foundations
+- Implementing something different from what the spec describes
+
+**When you catch yourself "fixing" code:**
+1. STOP
+2. Ask: "What does the spec say about this?"
+3. Re-read the spec's Traps to Avoid section
+4. Verify existing code matches the spec before building on it
+
+### Phrases That Should Trigger Spec Re-reading
+
+If you think or receive any of these, immediately re-read the spec:
+- "Does this match the spec?"
+- "What does the spec say about X?"
+- "Check the spec's Traps to Avoid section"
+- "Are you sure?"
+- "You're cargo-culting existing patterns"
+
 ## Status Lifecycle
 
 ```
 spawning → implementing → blocked → implementing → pr-ready → complete
-                ↑______________|
+               ↑______________|
 ```
 
 ### Status Definitions
@@ -80,16 +166,13 @@ spawning → implementing → blocked → implementing → pr-ready → complete
 | `pr-ready` | Implementation complete, ready for review |
 | `complete` | Merged, worktree can be cleaned up |
 
-### Updating Status
-
-Status is tracked in `.agent-farm/state.json` and visible on the dashboard.
+### Checking Status
 
-To check current status:
 ```bash
 af status
 ```
 
-Status updates happen automatically based on your progress. When blocked, clearly communicate the blocker in your terminal or via REVIEW comments in code.
+You can check your own status and see other builders. The Architect also monitors status.
 
 ## Working in a Worktree
 
@@ -105,13 +188,6 @@ Status updates happen automatically based on your progress. When blocked, clearl
 - Your spec is at `codev/specs/XXXX-spec-name.md`
 - Your plan is at `codev/plans/XXXX-spec-name.md`
 
-### Committing
-Make atomic commits as you work:
-```bash
-git add <files>
-git commit -m "[Spec XXXX] <description>"
-```
-
 ## When to Report Blocked
 
 Report `blocked` status when:
@@ -121,23 +197,23 @@ Report `blocked` status when:
 - You need architectural guidance
 - Tests are failing for reasons outside your scope
 
-**Do NOT stay blocked silently.** The Architect monitors status and will help.
+**Do NOT stay blocked silently.** Communicate your blocker clearly:
 
-### How to Report Blocked
+1. Output a clear message in your terminal describing the blocker and options
+2. Add a `<!-- REVIEW(@architect): question here -->` comment in relevant code if applicable
+3. The Architect monitors builder status via `af status` and will see you're blocked
+
+Example blocker message to output:
+```
+## BLOCKED: Spec 0003
+Can't find the auth helper mentioned in spec. Options:
+1. Create a new auth helper
+2. Use a third-party library
+3. Spec needs clarification
+Waiting for Architect guidance.
+```
 
-1. Update status to `blocked`
-2. Clearly describe the blocker:
-   ```markdown
-   ## Builder 0003
-   - Status: blocked
-   - Blocker: The spec says "use the existing auth helper" but I can't find
-     any auth helper in the codebase. Options:
-     1. Create a new auth helper
-     2. Use a third-party library
-     3. Spec meant something else?
-   ```
-3. Wait for Architect guidance
-4. Once unblocked, update status back to `implementing`
+The Architect will provide guidance via `af send` or PR comments.
 
 ## Deliverables
 
@@ -146,56 +222,56 @@ When done, a Builder should have:
 1. **Implementation** - Code that fulfills the spec
 2. **Tests** - Appropriate test coverage
 3. **Documentation** - Updated relevant docs (if needed)
-4. **Clean commits** - Atomic, well-messaged commits
-5. **PR-ready branch** - Ready for Architect to merge
+4. **Clean commits** - Atomic, well-messaged commits per phase
+5. **Review document** - As specified in the SPIDER protocol (`codev/reviews/XXXX-spec-name.md`)
+6. **PR-ready branch** - Ready for Architect review
 
 ## Communication with Architect
 
 ### Receiving Instructions
 The Architect provides:
 - Spec file path
+- Plan file path
 - Protocol to follow (SPIDER/TICK)
 - Context and constraints
-- Builder prompt with project-specific info
-
-### Asking Questions
-If you need help but aren't fully blocked:
-- Add a `<!-- REVIEW(@architect): question here -->` comment
-- The Architect will see it during review
 
 ### Reporting Completion
 When implementation is complete:
 1. Run all tests
 2. Self-review the code
-3. Update status to `pr-ready`
-4. The Architect will review and merge
+3. Ensure all protocol artifacts are present (especially the review document for SPIDER)
+4. Create a PR: `gh pr create --title "[Spec XXXX] Description" --body "..."`
+5. Update status to `pr-ready`
+6. Wait for Architect review and approval
+7. **Merge your own PR** once approved: `gh pr merge --merge --delete-branch`
 
-## Example Builder Session
+**Important**: The Builder is responsible for merging after Architect approval. This ensures the Builder sees the merge succeed and can handle any final cleanup.
 
+### Receiving PR Feedback
+
+The Architect reviews PRs and leaves feedback as GitHub PR comments. When notified to check feedback:
+
+```bash
+# View PR comments
+gh pr view <PR_NUMBER> --comments
+
+# Or view the full PR with comments in browser
+gh pr view <PR_NUMBER> --web
 ```
-1. Spawned for spec 0003-user-auth
-2. Read spec at codev/specs/0003-user-auth.md
-3. Status: implementing
-4. Follow SPIDER protocol:
-   - Create plan
-   - Implement auth routes
-   - Write tests
-   - Self-review
-5. Hit blocker: unclear which JWT library to use
-6. Status: blocked (described options)
-7. Architect responds: "Use jose library"
-8. Status: implementing
-9. Complete implementation
-10. Run tests: all passing
-11. Status: pr-ready
-12. Architect reviews and merges
-13. Status: complete
-```
+
+**Workflow:**
+1. Architect leaves review comments on PR
+2. You receive a short message: "Check PR comments and address feedback"
+3. Run `gh pr view <PR_NUMBER> --comments` to see feedback
+4. Address the issues (High priority first, then Medium, Low is optional)
+5. Push fixes to the same branch
+6. Reply to PR comment when done or if clarification needed
 
 ## Constraints
 
 - **Stay in scope** - Only implement what's in your spec
 - **Don't modify shared config** - Without Architect approval
-- **Don't merge yourself** - The Architect handles integration
+- **Merge your own PRs** - After Architect approves, you are responsible for merging
 - **Don't spawn other Builders** - Only Architects spawn Builders
 - **Keep worktree clean** - No untracked files, no debug code
+- **Follow the protocol** - All phases, all artifacts

package/skeleton/templates/cheatsheet.md

@@ -0,0 +1,170 @@
+# Codev Cheatsheet
+
+A quick reference for Codev's philosophies, concepts, and tools.
+
+---
+
+## Core Philosophies
+
+### 1. Natural Language is the Programming Language
+
+Specifications and plans are as important as code—they ARE the requirements and design.
+
+| Traditional | Codev |
+|-------------|-------|
+| Code first, document later | Spec first, code implements spec |
+| Documentation gets stale | Specs ARE the source of truth |
+| Humans read code to understand | AI agents translate spec → code |
+
+**Corollaries:**
+- The spec IS the requirements; the plan IS the design
+- Code is the implementation of well-defined natural language artifacts
+- If the spec is wrong, the code will be wrong—fix the spec first
+
+### 2. Multiple Models Outperform a Single Model
+
+No single AI model catches everything. Diverse perspectives find more issues.
+
+| Role | Models |
+|------|--------|
+| Architect & Builder | Claude (primary agent) |
+| Consultants | Gemini, Codex, Claude (for reviews) |
+
+**Corollaries:**
+- 3-way reviews catch issues single models miss
+- Different models have different strengths and blind spots
+- Consultation happens at key checkpoints, not continuously
+
+### 3. Human-Agent Work Requires Thoughtful Structure
+
+Just like structuring a human team—clear roles, defined processes, explicit handoffs.
+
+| Component | Purpose |
+|-----------|---------|
+| Protocols | Define HOW work happens (SPIDER, TICK, etc.) |
+| Roles | Define WHO does what (Architect, Builder, Consultant) |
+| Parallelism | Scale by running multiple builders simultaneously |
+
+**Corollaries:**
+- Well-defined protocols reduce ambiguity and rework
+- Clear roles enable autonomous operation
+- Parallel execution multiplies throughput
+
+---
+
+## Core Concepts
+
+### Protocols
+
+A **protocol** is a structured workflow that defines how work progresses from idea to completion.
+
+| Protocol | Use For | Phases |
+|----------|---------|--------|
+| **SPIDER** | New features | Specify → Plan → Implement → Defend → Evaluate → Review |
+| **TICK** | Amendments to existing specs | Task Identification → Coding → Kickout |
+| **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync |
+| **EXPERIMENT** | Research & prototyping | Hypothesis → Experiment → Conclude |
+
+### Roles
+
+A **role** defines who does what work and what tools/permissions they have.
+
+| Role | Responsibilities |
+|------|------------------|
+| **Architect** | Orchestrates development, writes specs/plans, reviews PRs, maintains big picture |
+| **Builder** | Implements specs in isolated worktrees, writes tests, creates PRs |
+| **Consultant** | External reviewers providing second opinions on specs, plans, implementations |
+
+**Consultant Flavors** (via `--type`):
+- `spec-review` - Review specification completeness
+- `plan-review` - Review implementation plan feasibility
+- `impl-review` - Review code for spec adherence
+- `integration-review` - Review for architectural fit
+
+### Context Hierarchy
+
+In much the same way an operating system has a memory hierarchy, Codev repos have a context hierarchy. The codev/ directory holds the top 3 layers. This allows both humans and agents to think about problems at different levels of detail.
+
+**Key insight**: We build from the top down, and we propagate information from the bottom up. We start with an entry in the project list, then spec and plan out the feature, generate the code, and then propagate what we learned through the reviews. 
+
+---
+
+## Tools Reference
+
+### codev
+
+Project management commands. Typically used by **humans** to set up and maintain projects.
+
+| Command | Description |
+|---------|-------------|
+| `codev init <dirname>` | Create a new Codev project |
+| `codev adopt` | Add Codev to an existing project |
+| `codev doctor` | Check dependencies and configuration |
+| `codev update` | Update Codev framework |
+| `codev import` | Import specs from another project |
+| `codev tower` | Cross-project dashboard |
+
+### agent-farm (af)
+
+Architect-Builder orchestration. Used by both **humans and agents**—agents use it more frequently.
+
+| Command | Description |
+|---------|-------------|
+| `af start` | Start dashboard (port 4200, 4300, etc.) |
+| `af stop` | Stop all processes |
+| `af spawn -p <id>` | Spawn a builder for project |
+| `af status` | Check status of all builders |
+| `af send <target> <msg>` | Send message (builder↔architect) |
+| `af cleanup -p <id>` | Clean up a builder worktree |
+| `af open <file>` | Open file in dashboard viewer |
+
+### consult
+
+Multi-agent consultation. Used by both humans and agents—**mostly agents** during reviews.
+
+| Command | Description |
+|---------|-------------|
+| `consult --model <model> spec <id>` | Review a specification |
+| `consult --model <model> plan <id>` | Review an implementation plan |
+| `consult --model <model> pr <id>` | Review a pull request |
+| `consult --model <model> general "<query>"` | General consultation |
+
+**Models**: `gemini` (alias: `pro`), `codex` (alias: `gpt`), `claude` (alias: `opus`)
+
+**Review Types** (via `--type`):
+| Type | Use Case |
+|------|----------|
+| `spec-review` | Review spec completeness and clarity |
+| `plan-review` | Review plan coverage and feasibility |
+| `impl-review` | Review implementation quality (Builder use) |
+| `integration-review` | Review architectural fit (Architect use) |
+
+---
+
+## Quick Reference
+
+### SPIDER Checklist
+
+```
+[ ] Specify - Write spec in codev/specs/XXXX-name.md
+[ ] Plan - Write plan in codev/plans/XXXX-name.md
+    For each phase of the plan:
+      [ ] Implement - Write code following the plan
+      [ ] Defend - Write tests for the implementation
+      [ ] Evaluate - Consult external reviewers, address feedback
+[ ] Review - Write review in codev/reviews/XXXX-name.md, create PR
+```
+
+### Consultation Pattern
+
+```bash
+# Run 3-way review in parallel
+consult --model gemini pr <id> &
+consult --model codex pr <id> &
+consult --model claude pr <id> &
+wait
+```
+
+---
+
+*For detailed documentation, see the full protocol files in `codev/protocols/`.*