@cluesmith/codev 2.0.3 → 2.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "2.0.3",
+  "version": "2.0.7",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -36,10 +36,13 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.41",
     "@google/genai": "^1.0.0",
+    "@openai/codex-sdk": "^0.101.0",
+    "@types/http-proxy": "^1.17.17",
     "better-sqlite3": "^12.5.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "glob": "^11.0.0",
+    "http-proxy": "^1.18.1",
     "js-yaml": "^4.1.0",
     "node-pty": "^1.1.0",
     "open": "^10.1.0",

package/skeleton/.claude/skills/af/SKILL.md

@@ -28,13 +28,13 @@ af dash open               # Open dashboard in browser
 ## Builder Management
 
 ```bash
-af spawn -p 0003           # Spawn builder for spec (strict mode, default)
-af spawn --soft -p 0003    # Spawn builder (soft mode)
-af spawn --issue 42        # Spawn builder for a bugfix
-af spawn -p 0003 --resume  # Resume builder in existing worktree
-af status                  # Check all builder status
-af cleanup --project 0003  # Clean up builder worktree (safe)
-af cleanup --project 0003 -f  # Force cleanup
+af spawn 3 --protocol spir     # Spawn builder for SPIR project
+af spawn 3 --protocol spir --soft  # Spawn builder (soft mode)
+af spawn 3 --protocol bugfix   # Spawn builder for a bugfix
+af spawn 3 --resume            # Resume builder in existing worktree
+af status                      # Check all builder status
+af cleanup --project 3         # Clean up builder worktree (safe)
+af cleanup --project 3 -f      # Force cleanup
 ```
 
 ### Resuming Builders
@@ -43,13 +43,13 @@ When a builder's Claude process dies but the worktree and porch state survive,
 use `--resume` to restart it without recreating the worktree:
 
 ```bash
-af spawn -p 0003 --resume
+af spawn 3 --resume
 ```
 
-This reuses the existing `.builders/0003` worktree, creates a fresh terminal
+This reuses the existing `.builders/3` worktree, creates a fresh terminal
 session registered with the Tower (so it appears in the dashboard), and lets
 porch pick up from whatever phase the builder was in. Works with all spawn
-modes: `-p`, `--issue`, `--task`, `--protocol`, `--worktree`.
+modes: positional issue number, `--task`, `--protocol`, `--worktree`.
 
 ## Utility
 

package/skeleton/.claude/skills/consult/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: consult
-description: AI consultation CLI quick reference. Use when running consult commands to check syntax for PR reviews, spec reviews, plan reviews, and general queries across Gemini, Codex, and Claude.
+description: AI consultation CLI quick reference. Use when running consult commands to check syntax for general queries, protocol reviews, and stats across Gemini, Codex, and Claude.
 disable-model-invocation: false
 ---
 
@@ -9,73 +9,90 @@ disable-model-invocation: false
 ## Synopsis
 
 ```bash
-consult -m <model> <subcommand> [args] [options]
+consult -m <model> [options]
+consult stats [options]
 ```
 
-The `-m` / `--model` flag is **always required**.
+The `-m` / `--model` flag is **always required** (except for stats).
 
 ## Models
 
 | Model | Alias | Speed | Approach |
 |-------|-------|-------|----------|
-| `gemini` | `pro` | ~120-150s | Pure text analysis, fast |
+| `gemini` | `pro` | ~120-150s | File access via --yolo, fast |
 | `codex` | `gpt` | ~200-250s | Shell command exploration, thorough |
-| `claude` | `opus` | ~60-120s | Balanced tool use |
+| `claude` | `opus` | ~60-120s | Agent SDK with tool use |
 
-## Subcommands
+## Modes
 
+### General Mode
 ```bash
-consult -m gemini pr 42              # Review a pull request
-consult -m codex spec 42             # Review a specification
-consult -m gemini plan 42            # Review an implementation plan
-consult -m claude general "query"    # General question (quoted string)
+consult -m gemini --prompt "What's the best way to structure auth?"
+consult -m codex --prompt-file review-checklist.md
+```
+
+### Protocol Mode
+```bash
+consult -m gemini --protocol spir --type spec       # Review a specification
+consult -m codex --protocol spir --type plan        # Review a plan
+consult -m claude --protocol spir --type impl       # Review implementation
+consult -m gemini --protocol spir --type pr         # Review a PR
+consult -m codex --protocol spir --type phase       # Phase-scoped review
+consult -m gemini --type integration                # Integration review
+```
+
+### Stats Mode
+```bash
+consult stats                     # 30-day summary
+consult stats --days 7 --json     # Last 7 days as JSON
 ```
 
 ## Options
 
 ```bash
--n, --dry-run              # Show command without running
--t, --type <type>          # Review type (spec-review, plan-review, impl-review, pr-ready, integration-review)
--r, --role <role>          # Custom role from codev/roles/ (without .md extension)
+-m, --model <model>         # Model to use (required except stats)
+--prompt <text>              # Inline prompt (general mode)
+--prompt-file <path>         # Prompt from file (general mode)
+--protocol <name>            # Protocol: spir, bugfix, tick, maintain
+-t, --type <type>            # Review type: spec, plan, impl, pr, phase, integration
+--issue <number>             # Issue number (architect context)
 ```
 
-## Review Types (--type)
+## Review Types (--type with --protocol)
+
+| Type | Use Case |
+|------|----------|
+| `spec` | Review specification completeness |
+| `plan` | Review implementation plan |
+| `impl` | Review code implementation |
+| `pr` | Review pull request before merge |
+| `phase` | Phase-scoped review (builder only) |
+| `integration` | Architect's integration review |
 
-| Type | Stage | Use Case |
-|------|-------|----------|
-| `spec-review` | conceived | Review spec 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 |
+Protocol-specific prompts live in `codev/protocols/<protocol>/consult-types/`.
 
-Review type prompts live in `codev/consult-types/` and can be customized.
+## Context Resolution
+
+- **Builder context** (cwd in `.builders/`): auto-detects project from porch state
+- **Architect context** (cwd outside `.builders/`): requires `--issue <N>`
 
 ## Parallel Consultation (3-Way / cmap)
 
 Run all three models in parallel for thorough reviews:
 
 ```bash
-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
 ```
 
 Or from Claude Code, use **cmap** pattern: three parallel background Bash calls.
 
-## Custom Roles
-
-```bash
-consult -m gemini --role security-reviewer pr 42
-consult -m codex --role architect general "Review this design"
-```
-
-Roles are markdown files in `codev/roles/`. Create your own by adding `.md` files there.
-
 ## Common Mistakes
 
-- The `-m` flag is **required** — `consult pr 42` will fail without it
-- PR numbers are GitHub PR numbers, not spec numbers
-- Spec/plan numbers match the `0042` prefix in filenames (pass just `42`, not `0042`)
-- General queries must be **quoted**: `consult -m gemini general "your question here"`
+- The `-m` flag is **required** — `consult --type spec` will fail without it
+- Cannot combine `--prompt` with `--type` (mode conflict)
+- Cannot use `--prompt` and `--prompt-file` together
+- `--protocol` requires `--type` — cannot use alone
+- General mode: `--prompt` text is passed directly, not as a positional arg

package/skeleton/.claude/skills/porch/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: porch
+description: Protocol orchestrator CLI quick reference. Use when running porch commands to check correct syntax for status, run, done, approve, next, and pending.
+disable-model-invocation: false
+---
+
+# porch - Protocol Orchestrator
+
+## Synopsis
+
+```bash
+porch <command> [project-id]
+```
+
+Porch drives SPIR, TICK, and BUGFIX protocols via a state machine with phase transitions, gates, and multi-agent consultations.
+
+## Commands
+
+```bash
+porch status [id]          # Show project status (auto-detects in worktree)
+porch run [id]             # Run the protocol loop (strict mode)
+porch next [id]            # Get next tasks for a project
+porch done [id]            # Signal current phase work is complete
+porch approve <id> <gate>  # Approve a gate (human only)
+porch pending              # List all pending gates across projects
+```
+
+## Gates
+
+Gates are human approval checkpoints. Builders STOP at gates and wait.
+
+| Gate | Protocol | When |
+|------|----------|------|
+| `spec-approval` | SPIR | After spec is written |
+| `plan-approval` | SPIR | After plan is written |
+| `pr` | SPIR, TICK | After PR is created |
+
+```bash
+porch approve 42 spec-approval    # Approve spec gate
+porch approve 42 plan-approval    # Approve plan gate
+porch approve 42 pr               # Approve PR gate
+```
+
+## Project State
+
+State is stored in `codev/projects/<id>/status.yaml`, managed automatically by porch. **Never edit status.yaml directly.**
+
+## Common Mistakes
+
+- **Never call `porch approve` as a builder** - Only humans approve gates
+- **Never edit status.yaml directly** - Only porch modifies state
+- Builders should use `porch done` to signal phase completion, not `porch approve`
+- `porch run` is for strict mode only - soft mode builders follow the protocol manually

package/skeleton/DEPENDENCIES.md

@@ -120,7 +120,7 @@ claude --version
 **Installation:**
 
 ```bash
-npm install -g @anthropic-ai/gemini-cli
+npm install -g @google/gemini-cli
 
 # Verify
 gemini --version
@@ -218,7 +218,7 @@ Ensure no firewall is blocking the ports (default: 4200-4299):
 lsof -i :4200
 
 # Clean up stale port allocations
-./codev/bin/agent-farm ports cleanup
+af ports cleanup
 ```
 
 ### gh authentication issues

package/skeleton/builders.md

@@ -1,30 +1,19 @@
 # Active Builders
 
-Track active builder agents here. Update manually or via `architect status`.
+> **Note**: Builder status is now tracked automatically via SQLite database and the Tower dashboard. Use `af status` to check all builders. This file is retained as a reference for status values only.
 
 ## Status Values
 
 - **spawning**: Worktree being created, terminal starting
 - **implementing**: Builder is working
 - **blocked**: Builder waiting for architect input
-- **pr-ready**: Builder has created a PR
-- **reviewing**: Architect is reviewing the PR
+- **pr**: Builder has created a PR
 - **complete**: PR merged, ready for cleanup
 
----
+## Commands
 
-## Builders
-
-<!-- Add builders below as they are spawned -->
-
-<!-- Example:
-## Builder 0003: Feature Name
-- **Branch**: builder/0003-feature-name
-- **Port**: 7681
-- **Status**: implementing
-- **Phase**: 2/4
-- **Started**: 2025-12-02 11:30
-- **PR**: (none yet)
--->
-
-(No active builders)
+```bash
+af status              # Check all builder statuses
+af spawn <id>          # Spawn a new builder
+af cleanup -p <id>     # Clean up a completed builder
+```

package/skeleton/maintain/.gitkeep

@@ -1,2 +1,2 @@
 # Maintenance run files go here
-# Files are numbered: 0001-maintenance.md, 0002-maintenance.md, etc.
+# Files are numbered: 1-maintenance.md, 2-maintenance.md, etc.

package/skeleton/porch/prompts/specify.md

@@ -10,7 +10,7 @@ Write a detailed specification for the assigned project. The spec must be comple
 
 Read these files to understand the task:
 1. `codev/status/{project-id}-*.md` - Current project state and any notes
-2. `codev/projectlist.md` - Project entry with initial description
+2. The GitHub Issue for this project (if available)
 3. Any existing context files mentioned in the project entry
 
 ## Output Requirements

package/skeleton/protocol-schema.json

@@ -145,7 +145,7 @@
         "type": {
           "type": "string",
           "description": "Review type (maps to consult --type)",
-          "enum": ["spec-review", "plan-review", "impl-review", "pr-ready", "integration-review"]
+          "enum": ["spec", "plan", "impl", "pr", "phase", "integration"]
         },
         "models": {
           "type": "array",

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -47,28 +47,39 @@ EOF
 Run 3-way parallel consultation on the PR:
 
 ```bash
-consult --model gemini pr <PR_NUMBER> &
-consult --model codex pr <PR_NUMBER> &
-consult --model claude pr <PR_NUMBER> &
+consult -m gemini --protocol bugfix --type pr &
+consult -m codex --protocol bugfix --type pr &
+consult -m claude --protocol bugfix --type pr &
 ```
 
 All three should run in the background (`run_in_background: true`).
 
-### 3. Address Feedback
+### 3. Wait for Results and Address Feedback
 
-Review the consultation results:
+**DO NOT proceed to step 4 until ALL THREE consultations have returned results.**
+
+Wait for each background consultation to complete, then read the results:
+- Use `TaskOutput` (with `block: true`) to retrieve each consultation result
+- Record each model's verdict (APPROVE or REQUEST_CHANGES)
 - Fix any issues identified by reviewers
 - Push updates to the PR branch
 - Re-run CMAP if substantial changes were made
 
+You must have three concrete verdicts (e.g., "gemini: APPROVE, codex: APPROVE, claude: APPROVE") before continuing.
+
 ### 4. Notify Architect
 
-After CMAP review is complete and feedback is addressed, notify the architect:
+**DO NOT send this notification until you have all three CMAP verdicts from step 3.**
+
+Send a **single** notification that includes the PR link and each model's verdict:
 
 ```bash
-af send architect "PR #<number> ready for review (fixes issue #{{issue.number}})"
+af send architect "PR #<number> ready for review (fixes issue #{{issue.number}}). CMAP: gemini=<APPROVE|REQUEST_CHANGES>, codex=<APPROVE|REQUEST_CHANGES>, claude=<APPROVE|REQUEST_CHANGES>"
 ```
 
+**This is the only notification you send.** After this, your work is done — the architect
+takes it from here (reviews, merges, cleans up).
+
 ## Signals
 
 When PR is created and reviews are complete:

package/skeleton/protocols/bugfix/protocol.json

@@ -76,7 +76,7 @@
       "consultation": {
         "on": "review",
         "models": ["gemini", "codex"],
-        "type": "impl-review",
+        "type": "impl",
         "parallel": true,
         "max_rounds": 1
       },

package/skeleton/protocols/experiment/protocol.md

@@ -16,13 +16,13 @@ Disciplined experimentation: Each experiment gets its own directory with `notes.
 
 ```
 experiments/
-├── 0001_descriptive_name/
+├── 1_descriptive_name/
 │   ├── notes.md           # Goal, code, results
 │   ├── experiment.py      # Your experiment code
 │   └── data/
 │       ├── input/         # Input data
 │       └── output/        # Results, plots, etc.
-└── 0002_another_experiment/
+└── 2_another_experiment/
     ├── notes.md
     └── ...
 ```
@@ -33,8 +33,8 @@ experiments/
 
 ```bash
 # Create numbered directory
-mkdir -p experiments/0001_experiment_name
-cd experiments/0001_experiment_name
+mkdir -p experiments/1_experiment_name
+cd experiments/1_experiment_name
 
 # Initialize notes.md from template
 cp codev/protocols/experiment/templates/notes.md notes.md
@@ -81,8 +81,8 @@ Update `notes.md` with:
 ### 6. Commit
 
 ```bash
-git add experiments/0001_experiment_name/
-git commit -m "[Experiment 0001] Brief description of findings"
+git add experiments/1_experiment_name/
+git commit -m "[Experiment 1] Brief description of findings"
 ```
 
 ## notes.md Template
@@ -152,8 +152,8 @@ Example spec reference:
 ```markdown
 ## Background
 
-Experiment 0005 validated that [approach] achieves [results].
-See: experiments/0005_validation_test/notes.md
+Experiment 5 validated that [approach] achieves [results].
+See: experiments/5_validation_test/notes.md
 ```
 
 ### Experiment → TICK
@@ -164,22 +164,22 @@ For small, validated changes discovered during experimentation:
 ## Numbering Convention
 
 Use four-digit sequential numbering (consistent with project list):
-- `0001_`, `0002_`, `0003_`...
+- `1_`, `2_`, `3_`...
 - Shared sequence across all experiments
 - Descriptive name after the number (snake_case)
 
 Examples:
-- `0001_api_response_caching`
-- `0002_model_comparison`
-- `0003_performance_baseline`
+- `1_api_response_caching`
+- `2_model_comparison`
+- `3_performance_baseline`
 
 ## Git Workflow
 
 ### Commits
 ```
-[Experiment 0001] Initial setup and goal
-[Experiment 0001] Add baseline measurements
-[Experiment 0001] Complete - caching improves latency 40%
+[Experiment 1] Initial setup and goal
+[Experiment 1] Add baseline measurements
+[Experiment 1] Complete - caching improves latency 40%
 ```
 
 ### When to Commit
@@ -196,7 +196,7 @@ Examples:
 ## Example Experiment
 
 ```
-experiments/0001_caching_strategy/
+experiments/1_caching_strategy/
 ├── notes.md
 ├── benchmark.py
 ├── cache_test.py
@@ -210,7 +210,7 @@ experiments/0001_caching_strategy/
 
 **notes.md excerpt:**
 ```markdown
-# Experiment 0001: Caching Strategy Evaluation
+# Experiment 1: Caching Strategy Evaluation
 
 **Status**: Complete
 

package/skeleton/protocols/maintain/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/maintain/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/maintain/prompts/audit.md

@@ -56,7 +56,7 @@ grep -E "src/|packages/" codev/resources/arch.md | head -20
 
 ### 5. Create Audit Report
 
-Create a maintenance run file: `codev/maintain/NNNN.md`
+Create a maintenance run file: `codev/maintain/NNN.md`
 
 Document:
 - Dead code identified (with file paths)
@@ -66,7 +66,7 @@ Document:
 
 Use the template structure:
 ```markdown
-# Maintenance Run NNNN
+# Maintenance Run NNN
 
 **Date**: YYYY-MM-DD
 **Base Commit**: <commit-hash>

package/skeleton/protocols/maintain/prompts/sync.md

@@ -47,7 +47,7 @@ Extract actionable lessons:
 Format:
 ```markdown
 ## [Topic]
-- [From NNNN] Lesson description
+- [From NNN] Lesson description
 ```
 
 ### 3. Sync CLAUDE.md with AGENTS.md

package/skeleton/protocols/maintain/prompts/verify.md

@@ -63,7 +63,7 @@ Recommended focus areas for next run:
 ```bash
 git push origin HEAD
 
-gh pr create --title "[Maintain] Codebase maintenance run NNNN" --body "$(cat <<'EOF'
+gh pr create --title "[Maintain] Codebase maintenance run NNN" --body "$(cat <<'EOF'
 ## Summary
 
 - Dead code removal