@cluesmith/codev 1.1.0 → 1.1.1

package/skeleton/docs/commands/consult.md

@@ -0,0 +1,286 @@
+# 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.
+
+## Synopsis
+
+```
+consult -m <model> <subcommand> [args] [options]
+```
+
+## Required Option
+
+```
+-m, --model <model>    Model to use (required)
+```
+
+## 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 |
+
+## Options
+
+```
+-n, --dry-run           Show what would execute without running
+-t, --type <type>       Review type (see Review Types 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
+```
+
+---
+
+### consult spec
+
+Review a specification.
+
+```bash
+consult -m <model> spec <number>
+```
+
+**Arguments:**
+- `number` - Spec number to review (e.g., `42` for `codev/specs/0042-*.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:**
+
+```bash
+# Review spec 42
+consult -m gemini spec 42
+
+# With specific review type
+consult -m gemini spec 42 --type spec-review
+```
+
+---
+
+### consult plan
+
+Review an implementation plan.
+
+```bash
+consult -m <model> plan <number>
+```
+
+**Arguments:**
+- `number` - Plan number to review (e.g., `42` for `codev/plans/0042-*.md`)
+
+**Description:**
+
+Reviews an implementation plan for:
+- Alignment with specification
+- Implementation approach
+- Task breakdown and ordering
+- Risk identification
+- Testing strategy
+
+If a matching spec exists, it's included for context.
+
+**Example:**
+
+```bash
+consult -m gemini plan 42
+```
+
+---
+
+### consult general
+
+General AI consultation.
+
+```bash
+consult -m <model> general "<query>"
+```
+
+**Arguments:**
+- `query` - Question or request (quoted string)
+
+**Description:**
+
+Sends a free-form query to the consultant. The consultant role is still loaded, so responses follow the consultant guidelines.
+
+**Examples:**
+
+```bash
+# Ask about code design
+consult -m gemini general "What's the best way to structure auth middleware?"
+
+# Get architecture advice
+consult -m codex general "Review src/lib/database.ts for potential issues"
+```
+
+---
+
+## Review Types
+
+Use `--type` to load stage-specific review prompts:
+
+| 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 |
+
+**Example:**
+
+```bash
+consult -m gemini spec 42 --type spec-review
+consult -m codex pr 68 --type integration-review
+```
+
+---
+
+## 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 &
+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.
+
+---
+
+## Prerequisites
+
+Install the model CLIs you plan to use:
+
+```bash
+# Claude
+npm install -g @anthropic-ai/claude-code
+
+# Codex
+npm install -g @openai/codex
+
+# Gemini
+# See: https://github.com/google-gemini/gemini-cli
+```
+
+Configure API keys:
+- Claude: `ANTHROPIC_API_KEY`
+- 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 ejecting and modifying:
+
+```bash
+codev eject 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 0042...
+```
+
+---
+
+## Examples
+
+```bash
+# Quick spec review
+consult -m gemini spec 42
+
+# Thorough PR review
+consult -m codex pr 68
+
+# Architecture question
+consult -m claude general "How should I structure the caching layer?"
+
+# Dry run to see command
+consult -m gemini pr 42 --dry-run
+
+# 3-way parallel review
+consult -m gemini spec 42 &
+consult -m codex spec 42 &
+consult -m claude spec 42 &
+wait
+```
+
+---
+
+## See Also
+
+- [codev](codev.md) - Project management commands
+- [af](agent-farm.md) - Agent Farm commands
+- [overview](overview.md) - CLI overview

package/skeleton/docs/commands/overview.md

@@ -0,0 +1,107 @@
+# Codev CLI Command Reference
+
+Codev provides three CLI tools for AI-assisted software development:
+
+| Tool | Description |
+|------|-------------|
+| `codev` | Project setup, maintenance, and framework commands |
+| `af` | Agent Farm - multi-agent orchestration for development |
+| `consult` | AI consultation with external models (Gemini, Codex, Claude) |
+
+## Quick Start
+
+```bash
+# Create a new project
+codev init my-project
+
+# Or add codev to an existing project
+codev adopt
+
+# Check your environment
+codev doctor
+
+# Start the architect dashboard
+af start
+
+# Consult an AI model about a spec
+consult -m gemini spec 42
+```
+
+## Installation
+
+```bash
+npm install -g @cluesmith/codev
+```
+
+This installs all three commands globally: `codev`, `af`, and `consult`.
+
+## Command Summaries
+
+### codev - Project Management
+
+| Command | Description |
+|---------|-------------|
+| `codev init [name]` | Create a new codev project |
+| `codev adopt` | Add codev to an existing project |
+| `codev doctor` | Check system dependencies |
+| `codev update` | Update codev templates and protocols |
+| `codev eject [path]` | Copy embedded files for customization |
+| `codev tower` | Cross-project dashboard |
+
+See [codev.md](codev.md) for full documentation.
+
+### af - Agent Farm
+
+| Command | Description |
+|---------|-------------|
+| `af start` | Start the architect dashboard |
+| `af stop` | Stop all agent farm processes |
+| `af spawn` | Spawn a new builder |
+| `af status` | Show status of all agents |
+| `af cleanup` | Clean up a builder worktree |
+| `af send` | Send instructions to a builder |
+| `af open` | Open file annotation viewer |
+| `af util` | Spawn a utility shell |
+
+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 |
+
+See [consult.md](consult.md) for full documentation.
+
+## Global Options
+
+All codev commands support:
+
+```bash
+--version    Show version number
+--help       Show help for any command
+```
+
+## Configuration
+
+Customize agent-farm commands via `codev/config.json`:
+
+```json
+{
+  "shell": {
+    "architect": "claude --model opus",
+    "builder": "claude --model sonnet",
+    "shell": "bash"
+  }
+}
+```
+
+## Related Documentation
+
+- [SPIDER Protocol](../protocols/spider/protocol.md) - Multi-phase development workflow
+- [TICK Protocol](../protocols/tick/protocol.md) - Fast amendment workflow
+- [Architect Role](../roles/architect.md) - Architect responsibilities
+- [Builder Role](../roles/builder.md) - Builder responsibilities

package/{templates → skeleton}/protocols/experiment/protocol.md

@@ -10,7 +10,7 @@ Disciplined experimentation: Each experiment gets its own directory with `notes.
 
 **Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes
 
-**Skip for**: Production code (use SPIDER/SPIDER-SOLO), simple one-off scripts, well-understood implementations (use TICK)
+**Skip for**: Production code (use SPIDER), simple one-off scripts, well-understood implementations (use TICK)
 
 ## Structure
 
@@ -141,7 +141,7 @@ What should be done based on findings?
 
 ## Integration with Other Protocols
 
-### Experiment → SPIDER/SPIDER-SOLO
+### Experiment → SPIDER
 When an experiment validates an approach for production use:
 
 1. Create a specification referencing the experiment

package/{templates → skeleton}/protocols/spider/protocol.md

@@ -1,13 +1,13 @@
 # SPIDER Protocol
 
+> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands.
+
 ## Prerequisites
 
 **Required for Multi-Agent Consultation**:
-- Zen MCP server must be installed and running
-- Check with: `mcp list` or test with `mcp__zen__version`
-- If not available:
-  - Option 1: "Would you like help installing Zen MCP server?"
-  - Option 2: "Use spider-solo protocol instead (no multi-agent consultation)"
+- The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`)
+- At least one consultation backend: `claude`, `gemini-cli`, or `codex`
+- Check with: `codev doctor` or `consult --help`
 
 ## Protocol Configuration
 
@@ -17,11 +17,11 @@
 Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIDER protocol.
 
 **DEFAULT AGENTS:**
-- **GPT-5**: Primary reviewer for architecture, feasibility, and code quality
+- **GPT-5 Codex**: Primary reviewer for architecture, feasibility, and code quality
 - **Gemini Pro**: Secondary reviewer for completeness, edge cases, and alternative approaches
 
 **DISABLING CONSULTATION:**
-For single-agent workflow, use the spider-solo protocol instead.
+To run SPIDER without consultation, say "without consultation" when starting work.
 
 **CUSTOM AGENTS:**
 The user can specify different agents by saying: "use SPIDER with consultation from [agent1] and [agent2]"

package/{templates/protocols/spider-solo → skeleton/protocols/spider}/templates/plan.md

@@ -166,4 +166,25 @@ Phase 1 ──→ Phase 2 ──→ Phase 3
 | [Date] | [What changed] | [Why] | [Who] |
 
 ## Notes
-[Additional context, assumptions, or considerations]
+[Additional context, assumptions, or considerations]
+
+---
+
+## Amendment History
+
+This section tracks all TICK amendments to this plan. TICKs modify both the spec and plan together as an atomic unit.
+
+<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
+
+<!--
+### TICK-001: [Amendment Title] (YYYY-MM-DD)
+
+**Changes**:
+- [Phase added]: [Description of new phase]
+- [Phase modified]: [What was updated]
+- [Implementation steps]: [New steps added]
+
+**Review**: See `reviews/####-name-tick-001.md`
+
+---
+-->

package/{templates/protocols/spider-solo → skeleton/protocols/spider}/templates/spec.md

@@ -137,4 +137,33 @@ Note: All consultation feedback has been incorporated directly into the relevant
 - [ ] Expert AI Consultation Complete
 
 ## Notes
-[Any additional context or considerations not covered above]
+[Any additional context or considerations not covered above]
+
+---
+
+## Amendments
+
+This section tracks all TICK amendments to this specification. TICKs are lightweight changes that refine an existing spec rather than creating a new one.
+
+<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
+
+<!--
+### TICK-001: [Amendment Title] (YYYY-MM-DD)
+
+**Summary**: [One-line description of what changed]
+
+**Problem Addressed**:
+[Why this amendment was needed - what gap or issue in the original spec]
+
+**Spec Changes**:
+- [Section modified]: [What changed and why]
+- [New section added]: [Purpose]
+
+**Plan Changes**:
+- [Phase added/modified]: [Description]
+- [Implementation steps]: [What was updated]
+
+**Review**: See `reviews/####-name-tick-001.md`
+
+---
+-->