@cluesmith/codev 1.5.26 → 1.5.28

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/`.*

package/skeleton/templates/lifecycle.md

@@ -0,0 +1,147 @@
+# Codev Project Lifecycle
+
+Every project in Codev flows through a series of stages from idea to production. This document explains each stage and how projects progress through the lifecycle.
+
+## Lifecycle Overview
+
+```
+conceived → specified → planned → implementing → implemented → committed → integrated
+```
+
+## Stages
+
+### 1. Conceived
+
+**What it means:** An idea has been captured. A spec file may exist but hasn't been approved yet.
+
+**Who does it:** Anyone can conceive a project by describing what they want to build.
+
+**What happens next:** The Architect (AI) writes a specification. The human reviews and approves it.
+
+**Artifact:** Draft specification in `codev/specs/NNNN-name.md`
+
+---
+
+### 2. Specified
+
+**What it means:** The specification has been approved by a human.
+
+**Who does it:** Only a human can approve a specification and mark it as specified.
+
+**What happens next:** The Architect creates an implementation plan.
+
+**Artifact:** Approved specification in `codev/specs/NNNN-name.md`
+
+---
+
+### 3. Planned
+
+**What it means:** An implementation plan exists that describes how to build the feature.
+
+**Who does it:** The Architect (AI) creates the plan, human reviews it.
+
+**What happens next:** A Builder is spawned to implement the plan.
+
+**Artifact:** Implementation plan in `codev/plans/NNNN-name.md`
+
+---
+
+### 4. Implementing
+
+**What it means:** Active development is in progress. A Builder is working on the code.
+
+**Who does it:** A Builder (AI agent) in an isolated git worktree.
+
+**What happens next:** Builder completes implementation and creates a PR.
+
+**Artifact:** Code changes in a builder worktree, work in progress
+
+---
+
+### 5. Implemented
+
+**What it means:** Code is complete, tests pass, and a Pull Request has been created.
+
+**Who does it:** The Builder creates the PR after completing implementation.
+
+**What happens next:** The Architect reviews the PR, Builder addresses feedback, then merges.
+
+**Artifact:** Open Pull Request ready for review
+
+---
+
+### 6. Committed
+
+**What it means:** The PR has been merged to the main branch.
+
+**Who does it:** The Builder merges after approval from the Architect's review.
+
+**What happens next:** Human validates in production and marks as integrated.
+
+**Artifact:** Merged PR, code on main branch
+
+---
+
+### 7. Integrated
+
+**What it means:** The feature has been validated in production and the project is complete.
+
+**Who does it:** Only a human can mark a project as integrated after validating it works.
+
+**What happens next:** Nothing - the project is complete! A review document captures lessons learned.
+
+**Artifact:** Review document in `codev/reviews/NNNN-name.md`
+
+---
+
+## Terminal States
+
+Projects can also end up in terminal states if they won't be completed:
+
+### Abandoned
+
+The project was canceled or rejected. It will not be implemented. The notes field in `projectlist.md` should explain why.
+
+### On-Hold
+
+The project is temporarily paused but may resume later. The notes field should explain the reason and any conditions for resuming.
+
+---
+
+## Human Approval Gates
+
+Two stages require explicit human approval - AI agents cannot bypass these:
+
+| Gate | Transition | Why |
+|------|------------|-----|
+| **Spec Approval** | conceived → specified | Humans must approve what gets built |
+| **Production Validation** | committed → integrated | Humans must verify it works in production |
+
+```
+conceived → [HUMAN APPROVES] → specified → planned → implementing → implemented → committed → [HUMAN VALIDATES] → integrated
+```
+
+---
+
+## Managing Projects
+
+All project tracking happens in `codev/projectlist.md`. To manage projects:
+
+- **Add a project:** Tell the Architect what you want to build
+- **Update status:** Ask the Architect to update the project status
+- **Approve stages:** Review the spec/plan and tell the Architect to mark it approved
+- **View progress:** Check the Projects tab in the dashboard or read `projectlist.md`
+
+---
+
+## Quick Reference
+
+| Stage | Artifact | Who Advances |
+|-------|----------|--------------|
+| Conceived | Draft spec | AI writes, human approves |
+| Specified | Approved spec | AI creates plan |
+| Planned | Implementation plan | AI spawns builder |
+| Implementing | WIP code | Builder completes |
+| Implemented | Open PR | Architect reviews, Builder merges |
+| Committed | Merged PR | Human validates |
+| Integrated | Review doc | Complete |

package/templates/dashboard/css/layout.css

@@ -43,6 +43,15 @@
   background: rgba(239, 68, 68, 0.1);
 }
 
+.btn-primary {
+  border-color: var(--accent);
+  color: var(--accent);
+}
+
+.btn-primary:hover {
+  background: rgba(59, 130, 246, 0.1);
+}
+
 /* Main content area */
 .main {
   display: flex;