@cluesmith/codev 2.0.6 → 2.0.8

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/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., `42`)
 - `--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 42
-af spawn -p 42
+# 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 42 --files "src/auth.ts,tests/auth.test.ts"
+af spawn 42 --files "src/auth.ts,tests/auth.test.ts"
 ```
 
 ---
@@ -199,7 +201,7 @@ Displays the current state of all builders and the architect:
 ├────────┼──────────────┼─────────────┼─────────┤
 │ arch   │ Architect    │ running     │ main    │
 │ 42   │ auth-feature │ implementing│ builder/42-auth │
-│ 43   │ api-refactor │ pr-ready    │ builder/43-api  │
+│ 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
 
 ---
@@ -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 42 --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 42 --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

@@ -94,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)
 
@@ -121,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
@@ -171,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

package/skeleton/resources/commands/consult.md

@@ -1,277 +1,139 @@
 # consult - AI Consultation CLI
 
-The `consult` command provides a unified interface for AI consultation with external models (Gemini, Codex, Claude). Use it for code reviews, spec reviews, and general questions.
+The `consult` command provides a unified interface for AI consultation with external models (Gemini, Codex, Claude). It operates in three modes: general (ad-hoc prompts), protocol-based (structured reviews), and stats.
 
 ## Synopsis
 
 ```
-consult -m <model> <subcommand> [args] [options]
+consult -m <model> [options]
+consult stats [options]
 ```
 
 ## Required Option
 
 ```
--m, --model <model>    Model to use (required)
+-m, --model <model>    Model to use (required for all modes except stats)
 ```
 
 ## Models
 
-| Model | Alias | CLI Used | Notes |
-|-------|-------|----------|-------|
-| `gemini` | `pro` | gemini-cli | Pure text analysis, fast |
-| `codex` | `gpt` | @openai/codex | Shell command exploration, thorough |
-| `claude` | `opus` | @anthropic-ai/claude-code | Balanced analysis |
+| Model | Alias | Backend | Notes |
+|-------|-------|---------|-------|
+| `gemini` | `pro` | gemini-cli | File access via --yolo, fast |
+| `codex` | `gpt` | @openai/codex | Read-only sandbox, thorough |
+| `claude` | `opus` | Claude Agent SDK | Balanced analysis with tool use |
 
-## Options
+## Modes
 
-```
--n, --dry-run           Show what would execute without running
--t, --type <type>       Review type (see Review Types below)
--r, --role <role>       Custom role from codev/roles/ (see Custom Roles below)
-```
-
-## Subcommands
-
-### consult pr
-
-Review a pull request.
-
-```bash
-consult -m <model> pr <number>
-```
-
-**Arguments:**
-- `number` - PR number to review
-
-**Description:**
-
-Reviews a GitHub pull request. The consultant reads:
-- PR info and description
-- Comments and discussions
-- Diff of all changes
-- File metadata
-
-Outputs a structured review with verdict: APPROVE, REQUEST_CHANGES, or COMMENT.
-
-**Examples:**
-
-```bash
-# Review PR #42 with Gemini
-consult -m gemini pr 42
-
-# Review with Codex (more thorough, slower)
-consult -m codex pr 42
-
-# Dry run to see command
-consult -m gemini pr 42 --dry-run
-```
+### General Mode
 
----
-
-### consult spec
-
-Review a specification.
-
-```bash
-consult -m <model> spec <number>
-```
-
-**Arguments:**
-- `number` - Spec number to review (e.g., `42` for `codev/specs/42-*.md`)
-
-**Description:**
-
-Reviews a specification file for:
-- Clarity and completeness
-- Technical feasibility
-- Edge cases and error scenarios
-- Security considerations
-- Testing strategy
-
-If a matching plan exists, it's included for context.
-
-**Examples:**
+Send an ad-hoc prompt to a model.
 
 ```bash
-# Review spec 42
-consult -m gemini spec 42
+# Inline prompt
+consult -m gemini --prompt "What's the best way to structure auth middleware?"
 
-# With specific review type
-consult -m gemini spec 42 --type spec-review
+# Prompt from file
+consult -m codex --prompt-file review-checklist.md
 ```
 
----
-
-### consult plan
-
-Review an implementation plan.
-
-```bash
-consult -m <model> plan <number>
-```
-
-**Arguments:**
-- `number` - Plan number to review (e.g., `42` for `codev/plans/42-*.md`)
-
-**Description:**
-
-Reviews an implementation plan for:
-- Alignment with specification
-- Implementation approach
-- Task breakdown and ordering
-- Risk identification
-- Testing strategy
+**Options:**
+- `--prompt <text>` — Inline prompt text
+- `--prompt-file <path>` — Read prompt from a file
 
-If a matching spec exists, it's included for context.
+Cannot combine `--prompt` with `--prompt-file` or `--type`.
 
-**Example:**
+### Protocol Mode
 
-```bash
-consult -m gemini plan 42
-```
-
----
-
-### consult general
-
-General AI consultation.
+Run structured reviews tied to a development protocol (SPIR, TICK, bugfix, maintain).
 
 ```bash
-consult -m <model> general "<query>"
-```
-
-**Arguments:**
-- `query` - Question or request (quoted string)
+# Review a spec (auto-detects project context in builder worktrees)
+consult -m gemini --protocol spir --type spec
 
-**Description:**
+# Review a plan
+consult -m codex --protocol spir --type plan
 
-Sends a free-form query to the consultant. The consultant role is still loaded, so responses follow the consultant guidelines.
+# Review implementation
+consult -m claude --protocol spir --type impl
 
-**Examples:**
+# Review a PR
+consult -m gemini --protocol spir --type pr
 
-```bash
-# Ask about code design
-consult -m gemini general "What's the best way to structure auth middleware?"
+# Phase-scoped review (builder context only)
+consult -m codex --protocol spir --type phase
 
-# Get architecture advice
-consult -m codex general "Review src/lib/database.ts for potential issues"
+# Integration review
+consult -m gemini --type integration
 ```
 
----
-
-## Review Types
+**Options:**
+- `--protocol <name>` — Protocol: spir, bugfix, tick, maintain
+- `-t, --type <type>` — Review type: spec, plan, impl, pr, phase, integration
+- `--issue <number>` — Issue number (required from architect context)
 
-Use `--type` to load stage-specific review prompts:
+**Context resolution:**
+- **Builder context** (cwd inside `.builders/`): auto-detects project ID, spec, plan, and PR from porch state
+- **Architect context** (cwd outside `.builders/` or `--issue` provided): requires `--issue <N>` to identify the project
 
-| Type | Stage | Use Case |
-|------|-------|----------|
-| `spec-review` | conceived | Review specification completeness |
-| `plan-review` | specified | Review implementation plan |
-| `impl-review` | implementing | Review code implementation |
-| `pr-ready` | implemented | Final check before PR |
-| `integration-review` | committed | Architect's integration review |
+**Prompt templates:**
+Protocol-specific prompts are loaded from `codev/protocols/<protocol>/consult-types/<type>-review.md`. The `integration` type uses the shared `codev/consult-types/integration-review.md`.
 
-**Location:** Review type prompts are stored in `codev/consult-types/`. You can customize existing prompts or add your own by creating new `.md` files in this directory.
+### Stats Mode
 
-> **Migration Note (v1.4.0+)**: Review types moved from `codev/roles/review-types/` to `codev/consult-types/`. The old location still works with a deprecation warning. To migrate:
-> ```bash
-> mkdir -p codev/consult-types
-> mv codev/roles/review-types/* codev/consult-types/
-> rm -r codev/roles/review-types
-> ```
-
-**Example:**
+View consultation statistics and history.
 
 ```bash
-consult -m gemini spec 42 --type spec-review
-consult -m codex pr 68 --type integration-review
+consult stats
+consult stats --days 7
+consult stats --project 42
+consult stats --last 10
+consult stats --json
 ```
 
----
+**Options:**
+- `--days <n>` — Limit to last N days (default: 30)
+- `--project <id>` — Filter by project ID
+- `--last <n>` — Show last N individual invocations
+- `--json` — Output as JSON
 
-## Custom Roles
+## Porch Integration Options
 
-Use `--role` to load a custom role instead of the default consultant:
+These flags are used by porch (the protocol orchestrator) when generating consult commands. They're not typically used directly.
 
-```bash
-consult -m gemini --role security-reviewer general "Audit this API endpoint"
-consult -m codex --role gtm-specialist general "Review our landing page copy"
 ```
-
-**Arguments:**
-- `role` - Name of role file in `codev/roles/` (without `.md` extension)
-
-**Available roles** depend on your project. Common ones include:
-- `architect` - System design perspective
-- `builder` - Implementation-focused review
-- `consultant` - Default balanced review (used when no `--role` specified)
-
-**Creating custom roles:**
-
-1. Create a markdown file in `codev/roles/`:
-   ```bash
-   # codev/roles/security-reviewer.md
-   # Role: Security Reviewer
-
-   You are a security-focused code reviewer...
-   ```
-
-2. Use it with `--role`:
-   ```bash
-   consult -m gemini --role security-reviewer pr 42
-   ```
-
-**Role name restrictions:**
-- Only letters, numbers, hyphens, and underscores
-- No path separators (security: prevents directory traversal)
-- Falls back to embedded skeleton if not found locally
-
-**Example:**
-
-```bash
-# Use the architect role for high-level review
-consult -m gemini --role architect general "Review this system design"
-
-# Use a custom GTM specialist role
-consult -m codex --role gtm-specialist general "Analyze our pricing page"
+--output <path>         Write output to file
+--plan-phase <phase>    Scope review to a specific plan phase
+--context <path>        Context file with previous iteration feedback
+--project-id <id>       Project ID for metrics
 ```
 
----
-
 ## Parallel Consultation (3-Way Reviews)
 
 For thorough reviews, run multiple models in parallel:
 
 ```bash
-# Using background processes
-consult -m gemini spec 42 &
-consult -m codex spec 42 &
-consult -m claude spec 42 &
+# 3-way spec review
+consult -m gemini --protocol spir --type spec &
+consult -m codex --protocol spir --type spec &
+consult -m claude --protocol spir --type spec &
 wait
 ```
 
-Or with separate terminal sessions for better output separation.
-
----
-
 ## Performance
 
 | Model | Typical Time | Approach |
 |-------|--------------|----------|
-| Gemini | ~120-150s | Pure text analysis |
-| Codex | ~200-250s | Shell command exploration |
-| Claude | ~60-120s | Balanced tool use |
-
-Codex is slower because it executes shell commands (git show, rg, etc.) sequentially. It's more thorough but takes ~2x longer than Gemini.
-
----
+| Gemini | ~120-150s | File access via --yolo, pure text output |
+| Codex | ~200-250s | Shell command exploration, read-only sandbox |
+| Claude | ~60-120s | Agent SDK with Read/Glob/Grep tools |
 
 ## Prerequisites
 
 Install the model CLIs you plan to use:
 
 ```bash
-# Claude
+# Claude Agent SDK
 npm install -g @anthropic-ai/claude-code
 
 # Codex
@@ -286,58 +148,50 @@ Configure API keys:
 - Codex: `OPENAI_API_KEY`
 - Gemini: `GOOGLE_API_KEY` or `GEMINI_API_KEY`
 
----
-
 ## The Consultant Role
 
 The consultant role (`codev/roles/consultant.md`) defines behavior:
 - Provides second perspectives on decisions
 - Offers alternatives and considerations
 - Works constructively (not adversarial, not a rubber stamp)
-- Uses `git show <branch>:<file>` for PR reviews
-
-Customize by copying to your local codev/ directory:
-
-```bash
-mkdir -p codev/roles
-cp $(npm root -g)/@cluesmith/codev/skeleton/roles/consultant.md codev/roles/
-```
 
----
+Customize by editing your local `codev/roles/consultant.md`.
 
 ## Query Logging
 
 All consultations are logged to `.consult/history.log`:
 
 ```
-2024-01-15T10:30:00.000Z model=gemini duration=142.3s query=Review spec 42...
+2026-02-16T10:30:00.000Z model=gemini duration=142.3s query=Review spec...
 ```
 
----
-
 ## Examples
 
 ```bash
-# Quick spec review
-consult -m gemini spec 42
+# General: ask a question
+consult -m gemini --prompt "How should I structure the caching layer?"
+
+# General: from file
+consult -m codex --prompt-file design-question.md
 
-# Thorough PR review
-consult -m codex pr 68
+# Protocol: spec review (builder context, auto-detected)
+consult -m gemini --protocol spir --type spec
 
-# Architecture question
-consult -m claude general "How should I structure the caching layer?"
+# Protocol: PR review (architect context)
+consult -m codex --protocol spir --type pr --issue 42
 
-# Dry run to see command
-consult -m gemini pr 42 --dry-run
+# Protocol: implementation review with bugfix protocol
+consult -m claude --protocol bugfix --type impl
 
 # 3-way parallel review
-consult -m gemini spec 42 &
-consult -m codex spec 42 &
-consult -m claude spec 42 &
+consult -m gemini --protocol spir --type spec &
+consult -m codex --protocol spir --type spec &
+consult -m claude --protocol spir --type spec &
 wait
-```
 
----
+# Stats
+consult stats --days 7 --json
+```
 
 ## See Also
 

package/skeleton/resources/commands/overview.md

@@ -24,7 +24,7 @@ codev doctor
 af dash start
 
 # Consult an AI model about a spec
-consult -m gemini spec 42
+consult -m gemini --protocol spir --type spec
 ```
 
 ## Installation
@@ -67,12 +67,11 @@ See [agent-farm.md](agent-farm.md) for full documentation.
 
 ### consult - AI Consultation
 
-| Subcommand | Description |
-|------------|-------------|
-| `consult pr <num>` | Review a pull request |
-| `consult spec <num>` | Review a specification |
-| `consult plan <num>` | Review an implementation plan |
-| `consult general "<query>"` | General consultation |
+| Command | Description |
+|---------|-------------|
+| `consult -m <model> --prompt "text"` | General consultation |
+| `consult -m <model> --protocol spir --type spec` | Protocol-based review |
+| `consult stats` | View consultation statistics |
 
 See [consult.md](consult.md) for full documentation.