@cluesmith/codev 2.0.3 → 2.0.7

package/skeleton/protocols/tick/consult-types/impl-review.md

@@ -0,0 +1,72 @@
+# Implementation Review Prompt
+
+## Context
+You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+
+## CRITICAL: Verify Before Flagging
+
+Before requesting changes for missing configuration, incorrect patterns, or framework issues:
+1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
+2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
+3. **Do not assume** your training data reflects the version in use — verify against project files
+4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
+
+## Focus Areas
+
+1. **Spec Adherence**
+   - Does the implementation fulfill the spec requirements for this phase?
+   - Are acceptance criteria met?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - Are there plan items skipped or partially completed?
+
+5. **UX Verification** (if spec has UX requirements)
+   - Does the actual user experience match what the spec describes?
+   - If spec says "async" or "non-blocking", is it actually async?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Phase is complete, builder can proceed
+- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
+- `COMMENT`: Minor suggestions, can proceed but note feedback
+
+## Scoping (Multi-Phase Plans)
+
+When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
+- **ONLY review work belonging to the current plan phase**
+- The query will specify which phase you are reviewing
+- Do NOT request changes for functionality scheduled in later phases
+- Do NOT flag missing features that are out of scope for this phase
+- If unsure whether something belongs to this phase, check the plan file
+
+## Notes
+
+- This is a phase-level review, not the final PR review
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

package/skeleton/protocols/tick/consult-types/plan-review.md

@@ -0,0 +1,59 @@
+# Plan Review Prompt
+
+## Context
+You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
+
+## Focus Areas
+
+1. **Spec Coverage**
+   - Does the plan address all requirements in the spec?
+   - Are there spec requirements not covered by any phase?
+   - Are there phases that go beyond the spec scope?
+
+2. **Phase Breakdown**
+   - Are phases appropriately sized (not too large or too small)?
+   - Is the sequence logical (dependencies respected)?
+   - Can each phase be completed and committed independently?
+
+3. **Technical Approach**
+   - Is the implementation approach sound?
+   - Are the right files/modules being modified?
+   - Are there obvious better approaches being missed?
+
+4. **Testability**
+   - Does each phase have clear test criteria?
+   - Will the Defend step (writing tests) be feasible?
+   - Are edge cases from the spec addressable?
+
+5. **Risk Assessment**
+   - Are there potential blockers not addressed?
+   - Are dependencies on other systems identified?
+   - Is the plan realistic given constraints?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Plan is ready for human review
+- `REQUEST_CHANGES`: Significant issues with approach or coverage
+- `COMMENT`: Minor suggestions, plan is workable but could improve
+
+## Notes
+
+- The spec has already been approved - don't re-litigate spec decisions
+- Focus on the quality of the plan as a guide for builders
+- Consider: Would a builder be able to follow this plan successfully?
+- If referencing existing code, verify file paths seem accurate

package/skeleton/protocols/tick/consult-types/pr-review.md

@@ -0,0 +1,72 @@
+# PR Ready Review Prompt
+
+## Context
+You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
+
+## Focus Areas
+
+1. **Completeness**
+   - Are all spec requirements implemented?
+   - Are all plan phases complete?
+   - Is the review document written (`codev/reviews/XXXX-name.md`)?
+   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
+
+2. **Test Status**
+   - Do all tests pass?
+   - Is test coverage adequate for the changes?
+   - Are there any skipped or flaky tests?
+
+3. **Code Cleanliness**
+   - Is there any debug code left in?
+   - Are there any TODO comments that should be resolved?
+   - Are there any `// REVIEW:` comments that weren't addressed?
+   - Is the code properly formatted?
+
+4. **Documentation**
+   - Are inline comments clear where needed?
+   - Is the review document comprehensive?
+   - Are any new APIs documented?
+
+5. **PR Readiness**
+   - Is the branch up to date with main?
+   - Are commits atomic and well-described?
+   - Is the change diff reasonable in size?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+
+PR_SUMMARY: |
+  ## Summary
+  [2-3 sentences describing what this PR does]
+
+  ## Key Changes
+  - [Change 1]
+  - [Change 2]
+
+  ## Test Plan
+  - [How to test]
+```
+
+**Verdict meanings:**
+- `APPROVE`: Ready to create PR
+- `REQUEST_CHANGES`: Issues to fix before PR creation
+- `COMMENT`: Minor items, can create PR but note feedback
+
+## Notes
+
+- This is the builder's final self-review before hand-off
+- The PR_SUMMARY in your output can be used as the PR description
+- Focus on "is this ready for someone else to review" not "is this perfect"
+- Any issues found here are cheaper to fix than during integration review

package/skeleton/protocols/tick/consult-types/spec-review.md

@@ -0,0 +1,55 @@
+# Specification Review Prompt
+
+## Context
+You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval.
+
+## Focus Areas
+
+1. **Completeness**
+   - Are all requirements clearly stated?
+   - Are success criteria defined?
+   - Are edge cases considered?
+   - Is scope well-bounded (not too broad or vague)?
+
+2. **Correctness**
+   - Do requirements make sense technically?
+   - Are there contradictions?
+   - Is the problem statement accurate?
+
+3. **Feasibility**
+   - Can this be implemented with available tools/constraints?
+   - Are there obvious technical blockers?
+   - Is the scope realistic for a single spec?
+
+4. **Clarity**
+   - Would a builder understand what to build?
+   - Are acceptance criteria testable?
+   - Is terminology consistent?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Spec is ready for human review
+- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding
+- `COMMENT`: Minor suggestions, can proceed but consider feedback
+
+## Notes
+
+- You are NOT reviewing code - you are reviewing the specification document
+- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review)
+- Be constructive - identify issues AND suggest solutions
+- If the spec references other specs, note if context seems missing

package/skeleton/protocols/tick/protocol.json

@@ -119,16 +119,11 @@
       "consultation": {
         "on": "review",
         "models": ["gemini", "codex"],
-        "type": "impl-review",
+        "type": "impl",
         "parallel": true,
         "max_rounds": 1
       },
-      "gate": {
-        "name": "pr-ready",
-        "description": "Amendment ready for PR",
-        "requires": ["tests_pass", "review_complete"],
-        "next": null
-      }
+      "gate": "pr"
     }
   ],
   "signals": {

package/skeleton/protocols/tick/protocol.md

@@ -50,7 +50,7 @@ TICK is an **amendment workflow** for existing SPIR specifications. Rather than
 **Example**:
 ```
 User: "Use TICK to add password reset to the auth system"
-Agent finds: specs/0002-user-authentication.md (status: integrated)
+Agent finds: specs/2-user-authentication.md (status: integrated)
 Agent determines: Next TICK is TICK-001 (first amendment)
 ```
 
@@ -58,7 +58,7 @@ Agent determines: Next TICK is TICK-001 (first amendment)
 
 **Agent Actions**:
 1. Analyze what needs to change in the spec
-2. Update relevant sections of `specs/####-name.md`:
+2. Update relevant sections of `specs/NNN-name.md`:
    - Problem Statement (if scope expands)
    - Success Criteria (if new criteria added)
    - Solution Approaches (if design changes)
@@ -78,14 +78,14 @@ Agent determines: Next TICK is TICK-001 (first amendment)
    **Plan Changes**:
    - [Phase/steps]: [What was added/modified]
 
-   **Review**: See `reviews/####-name-tick-001.md`
+   **Review**: See `reviews/NNN-name-tick-001.md`
    ```
-4. **COMMIT**: `[TICK ####-NNN] Spec: [description]`
+4. **COMMIT**: `[TICK NNN-NNN] Spec: [description]`
 
 ### Phase 3: Planning Amendment (Autonomous)
 
 **Agent Actions**:
-1. Update `plans/####-name.md` with new implementation steps
+1. Update `plans/NNN-name.md` with new implementation steps
 2. Add/modify phases as needed
 3. Add entry to "Amendment History" section at bottom:
    ```markdown
@@ -95,9 +95,9 @@ Agent determines: Next TICK is TICK-001 (first amendment)
    - [Phase added]: [Description]
    - [Implementation steps]: [What was updated]
 
-   **Review**: See `reviews/####-name-tick-001.md`
+   **Review**: See `reviews/NNN-name-tick-001.md`
    ```
-4. **COMMIT**: `[TICK ####-NNN] Plan: [description]`
+4. **COMMIT**: `[TICK NNN-NNN] Plan: [description]`
 
 ### Phase 4: Implementation (Autonomous)
 
@@ -105,12 +105,12 @@ Agent determines: Next TICK is TICK-001 (first amendment)
 1. Execute implementation steps from the plan
 2. Write code following fail-fast principles
 3. Test functionality
-4. **COMMIT**: `[TICK ####-NNN] Impl: [description]`
+4. **COMMIT**: `[TICK NNN-NNN] Impl: [description]`
 
 ### Phase 5: Review (User Checkpoint)
 
 **Agent Actions**:
-1. Create review document: `reviews/####-name-tick-NNN.md`
+1. Create review document: `reviews/NNN-name-tick-NNN.md`
    - What was amended and why
    - Changes made to spec and plan
    - Implementation challenges
@@ -120,7 +120,7 @@ Agent determines: Next TICK is TICK-001 (first amendment)
    - Focus: Code quality, missed issues, improvements
    - Update review with consultation feedback
 3. **Update Architecture Documentation** (if applicable)
-4. **COMMIT**: `[TICK ####-NNN] Review: [description]`
+4. **COMMIT**: `[TICK NNN-NNN] Review: [description]`
 5. **PRESENT TO USER**: Show summary with consultation insights
 
 **User Actions**:
@@ -130,7 +130,7 @@ Agent determines: Next TICK is TICK-001 (first amendment)
 
 **If Changes Requested**:
 - Agent makes changes
-- Commits: `[TICK ####-NNN] Fixes: [description]`
+- Commits: `[TICK NNN-NNN] Fixes: [description]`
 - Updates review document
 - Repeats until user approval
 
@@ -140,9 +140,9 @@ TICK amendments modify existing files and create new review files:
 
 | File Type | Pattern | Example |
 |-----------|---------|---------|
-| Spec (modified) | `specs/####-name.md` | `specs/0002-user-authentication.md` |
-| Plan (modified) | `plans/####-name.md` | `plans/0002-user-authentication.md` |
-| Review (new) | `reviews/####-name-tick-NNN.md` | `reviews/0002-user-authentication-tick-001.md` |
+| Spec (modified) | `specs/NNN-name.md` | `specs/2-user-authentication.md` |
+| Plan (modified) | `plans/NNN-name.md` | `plans/2-user-authentication.md` |
+| Review (new) | `reviews/NNN-name-tick-NNN.md` | `reviews/2-user-authentication-tick-001.md` |
 
 **Note**: Spec and plan files are modified in-place. Only the review file is new.
 
@@ -151,16 +151,16 @@ TICK amendments modify existing files and create new review files:
 **TICK commits reference the parent spec and TICK number**:
 
 ```
-[TICK 0002-001] Spec: Add password reset feature
-[TICK 0002-001] Plan: Add password reset implementation
-[TICK 0002-001] Impl: Add password reset feature
-[TICK 0002-001] Review: Password reset implementation
-[TICK 0002-001] Fixes: Address review feedback
+[TICK 2-001] Spec: Add password reset feature
+[TICK 2-001] Plan: Add password reset implementation
+[TICK 2-001] Impl: Add password reset feature
+[TICK 2-001] Review: Password reset implementation
+[TICK 2-001] Fixes: Address review feedback
 ```
 
-The format `[TICK ####-NNN]` identifies:
-- `####`: Parent spec number (e.g., 0002)
-- `NNN`: TICK amendment number (e.g., 001, 002, 003)
+The format `[TICK <parent>-<tick>]` identifies:
+- `<parent>`: Parent spec number (e.g., 2)
+- `<tick>`: TICK amendment number (e.g., 001, 002, 003)
 
 ## Key Differences from SPIR
 
@@ -168,7 +168,7 @@ The format `[TICK ####-NNN]` identifies:
 |--------|--------|------|
 | Purpose | Create new features | Amend existing features |
 | File creation | Creates new spec/plan/review | Modifies spec/plan, creates review |
-| Sequential numbering | Gets new number (0001, 0002) | Uses parent's number (0002-001) |
+| Sequential numbering | Gets new number (1, 2) | Uses parent's number (2-001) |
 | Scope | Any size | < 300 lines typically |
 | Prerequisites | None | Existing integrated spec required |
 | User checkpoints | Multiple (spec, plan, phases) | Two (start, end) |
@@ -195,24 +195,24 @@ Is there an existing spec to amend?
 **User**: "Add password reset to the user authentication system"
 
 **Agent**:
-1. **Identify**: Finds `specs/0002-user-authentication.md` (integrated)
+1. **Identify**: Finds `specs/2-user-authentication.md` (integrated)
 2. **Amend Spec** (30 seconds):
    - Updates Success Criteria with password reset requirements
    - Adds TICK-001 entry to Amendments section
-   - Commit: `[TICK 0002-001] Spec: Add password reset feature`
+   - Commit: `[TICK 2-001] Spec: Add password reset feature`
 3. **Amend Plan** (30 seconds):
    - Adds Phase 4: Password Reset Email Service
    - Adds TICK-001 entry to Amendment History
-   - Commit: `[TICK 0002-001] Plan: Add password reset implementation`
+   - Commit: `[TICK 2-001] Plan: Add password reset implementation`
 4. **Implement** (2 minutes):
    - Creates password reset endpoint
    - Implements email service
    - Tests functionality
-   - Commit: `[TICK 0002-001] Impl: Add password reset feature`
+   - Commit: `[TICK 2-001] Impl: Add password reset feature`
 5. **Review** (1 minute):
-   - Creates `reviews/0002-user-authentication-tick-001.md`
+   - Creates `reviews/2-user-authentication-tick-001.md`
    - Runs 3-way consultation (Gemini, Codex, Claude)
-   - Commit: `[TICK 0002-001] Review: Password reset implementation`
+   - Commit: `[TICK 2-001] Review: Password reset implementation`
    - Shows user the completed work
 
 **Total Time**: ~4 minutes for simple amendment
@@ -243,8 +243,8 @@ Existing standalone TICK projects (created before this protocol change) are gran
 **Optional Migration** (if desired):
 1. Identify the "parent spec" the TICK logically extends
 2. Move TICK content into an amendment entry in the parent spec
-3. Archive the standalone files with a note: "Migrated to spec #### as TICK-NNN"
-4. Update projectlist.md to reflect the change
+3. Archive the standalone files with a note: "Migrated to spec NNN as TICK-NNN"
+4. Update the GitHub Issue to reflect the change
 
 ## Benefits
 

package/skeleton/resources/commands/agent-farm.md

@@ -144,11 +144,13 @@ Does NOT clean up worktrees - use `af cleanup` for that.
 Spawn a new builder.
 
 ```bash
-af spawn [options]
+af spawn [issue-number] [options]
 ```
 
+**Arguments:**
+- `issue-number` - Issue number to build (positional, e.g., `42`)
+
 **Options:**
-- `-p, --project <id>` - Spawn builder for a spec (e.g., `0042`)
 - `--task <text>` - Spawn builder with a task description
 - `--protocol <name>` - Spawn builder to run a protocol
 - `--shell` - Spawn a bare Claude session
@@ -166,8 +168,8 @@ Creates a new builder in an isolated git worktree. The builder gets:
 **Examples:**
 
 ```bash
-# Spawn builder for spec 0042
-af spawn -p 0042
+# Spawn builder for issue #42
+af spawn 42
 
 # Spawn with task description
 af spawn --task "Fix login bug in auth module"
@@ -176,7 +178,7 @@ af spawn --task "Fix login bug in auth module"
 af spawn --shell
 
 # Spawn with context files
-af spawn -p 0042 --files "src/auth.ts,tests/auth.test.ts"
+af spawn 42 --files "src/auth.ts,tests/auth.test.ts"
 ```
 
 ---
@@ -198,8 +200,8 @@ Displays the current state of all builders and the architect:
 │ ID     │ Name         │ Status      │ Branch  │
 ├────────┼──────────────┼─────────────┼─────────┤
 │ arch   │ Architect    │ running     │ main    │
-│ 0042   │ auth-feature │ implementing│ builder/0042-auth │
-│ 0043   │ api-refactor │ pr-ready    │ builder/0043-api  │
+│ 42   │ auth-feature │ implementing│ builder/42-auth │
+│ 43   │ api-refactor │ pr    │ builder/43-api  │
 └────────┴──────────────┴─────────────┴─────────┘
 ```
 
@@ -207,7 +209,7 @@ Status values:
 - `spawning` - Worktree created, builder starting
 - `implementing` - Actively working
 - `blocked` - Stuck, needs architect help
-- `pr-ready` - Implementation complete
+- `pr` - Implementation complete
 - `complete` - Merged, can be cleaned up
 
 ---
@@ -232,10 +234,10 @@ Removes a builder's worktree and associated resources. By default, refuses to de
 
 ```bash
 # Clean up completed builder
-af cleanup -p 0042
+af cleanup -p 42
 
 # Force cleanup (may lose work)
-af cleanup -p 0042 --force
+af cleanup -p 42 --force
 ```
 
 ---
@@ -249,7 +251,7 @@ af send [builder] [message] [options]
 ```
 
 **Arguments:**
-- `builder` - Builder ID (e.g., `0042`)
+- `builder` - Builder ID (e.g., `42`)
 - `message` - Message to send
 
 **Options:**
@@ -270,16 +272,16 @@ Sends text to a builder's terminal. Useful for:
 
 ```bash
 # Send message to builder
-af send 0042 "Focus on the auth module first"
+af send 42 "Focus on the auth module first"
 
 # Interrupt and send new instructions
-af send 0042 --interrupt "Stop that. Try a different approach."
+af send 42 --interrupt "Stop that. Try a different approach."
 
 # Send to all builders
 af send --all "Time to wrap up, create PRs"
 
 # Include file content
-af send 0042 --file src/api.ts "Review this implementation"
+af send 42 --file src/api.ts "Review this implementation"
 ```
 
 ---
@@ -352,7 +354,7 @@ af rename <id> <name>
 **Example:**
 
 ```bash
-af rename 0042 "auth-rework"
+af rename 42 "auth-rework"
 ```
 
 ---
@@ -527,8 +529,8 @@ Customize commands via `af-config.json` at the project root:
 Or override via CLI flags:
 
 ```bash
-af start --architect-cmd "claude --model opus"
-af spawn -p 0042 --builder-cmd "claude --model haiku"
+af dash start --architect-cmd "claude --model opus"
+af spawn 42 --builder-cmd "claude --model haiku"
 ```
 
 ---
@@ -537,8 +539,8 @@ af spawn -p 0042 --builder-cmd "claude --model haiku"
 
 | File | Description |
 |------|-------------|
-| `.agent-farm/state.json` | Project runtime state |
-| `~/.agent-farm/ports.json` | Global port registry |
+| `.agent-farm/state.db` | Project runtime state (SQLite) |
+| `~/.agent-farm/global.db` | Global port registry (SQLite) |
 | `af-config.json` | Agent Farm configuration (project root) |
 
 ---

package/skeleton/resources/commands/codev.md

@@ -30,7 +30,6 @@ Creates a minimal codev project structure:
 - `codev/specs/` - Specification files
 - `codev/plans/` - Implementation plans
 - `codev/reviews/` - Review documents
-- `codev/projectlist.md` - Project tracking
 - `CLAUDE.md` / `AGENTS.md` - AI agent instructions
 - `.gitignore` - Standard ignores
 
@@ -95,7 +94,6 @@ Verifies that all required dependencies are installed and properly configured:
 
 **Core Dependencies (required):**
 - Node.js (>= 18.0.0)
-- ttyd (>= 1.7.0)
 - git (>= 2.5.0)
 - gh (GitHub CLI, authenticated)
 
@@ -122,7 +120,6 @@ Codev Doctor - Checking your environment
 Core Dependencies (required for Agent Farm)
 
   ✓ Node.js      20.10.0
-  ✓ ttyd         1.7.4
   ✓ git          2.42.0
   ✓ gh           authenticated
   ✓ @cluesmith/codev  1.0.0
@@ -172,39 +169,6 @@ codev update --force
 
 ---
 
-### codev tower
-
-Cross-project dashboard showing all agent-farm instances.
-
-```bash
-codev tower [options]
-```
-
-**Options:**
-- `-p, --port <port>` - Port to run on (default: 4100)
-- `--stop` - Stop the tower dashboard
-
-**Description:**
-
-Starts a web-based dashboard that shows all running agent-farm instances across different projects. Useful when working on multiple codev projects simultaneously.
-
-The tower aggregates status from the global port registry at `~/.agent-farm/ports.json`.
-
-**Examples:**
-
-```bash
-# Start tower dashboard
-codev tower
-
-# Start on custom port
-codev tower -p 4200
-
-# Stop the dashboard
-codev tower --stop
-```
-
----
-
 ## See Also
 
 - [af](agent-farm.md) - Agent Farm commands