@cluesmith/codev 2.0.6 → 2.0.8

package/skeleton/resources/workflow-reference.md

@@ -26,7 +26,7 @@ Quick reference for the 7-stage project workflow. For protocol details, see `cod
 │                               IMPLEMENTATION                                        │
 ├─────────────────────────────────────────────────────────────────────────────────────┤
 │  → 4. IMPLEMENTING                                                                  │
-│         Architect spawns builder: af spawn -p XXXX                                  │
+│         Architect spawns builder: af spawn XXXX                                  │
 │         Builder reads spec and plan                                                 │
 │         For each phase: Implement → Defend → Evaluate                               │
 │         Builder commits after each phase                                            │
@@ -80,7 +80,7 @@ AI agents must stop and wait for human action at these gates.
 af dash start
 
 # Spawn a builder for a project
-af spawn -p 44
+af spawn 44 --protocol spir
 
 # Check all builder statuses
 af status
@@ -118,7 +118,7 @@ af open src/path/to/file.ts
 codev import /path/to/other-project
 
 # Import from GitHub
-codev import github:cluesmith/ansari-project
+codev import github:cluesmith/codev
 
 # Preview without running Claude
 codev import github:owner/repo --dry-run
@@ -128,29 +128,29 @@ codev import github:owner/repo --dry-run
 
 ```bash
 # Spec review (during Stage 1)
-consult --model gemini --type spec-review spec 44
-consult --model codex --type spec-review spec 44
+consult -m gemini --protocol spir --type spec
+consult -m codex --protocol spir --type spec
 
 # Plan review (during Stage 2)
-consult --model gemini --type plan-review plan 44
-consult --model codex --type plan-review plan 44
+consult -m gemini --protocol spir --type plan
+consult -m codex --protocol spir --type plan
 
 # Implementation review (during Stage 4, after each phase)
-consult --model gemini --type impl-review spec 44
-consult --model codex --type impl-review spec 44
+consult -m gemini --protocol spir --type impl
+consult -m codex --protocol spir --type impl
 
-# PR ready review (during Stage 5)
-consult --model gemini --type pr-ready pr 88
-consult --model codex --type pr-ready pr 88
+# PR review (during Stage 5)
+consult -m gemini --protocol spir --type pr
+consult -m codex --protocol spir --type pr
 
 # Integration review (during Stage 6)
-consult --model gemini --type integration-review pr 88
-consult --model codex --type integration-review pr 88
+consult -m gemini --type integration
+consult -m codex --type integration
 
 # Parallel 3-way reviews (run all three concurrently)
-consult --model gemini --type spec-review spec 44 &
-consult --model codex --type spec-review spec 44 &
-consult --model claude --type spec-review spec 44 &
+consult -m gemini --protocol spir --type spec &
+consult -m codex --protocol spir --type spec &
+consult -m claude --protocol spir --type spec &
 wait
 ```
 
@@ -158,16 +158,16 @@ wait
 
 | Type | When Used | Focus |
 |------|-----------|-------|
-| `spec-review` | Stage 1 | Requirements clarity, completeness, feasibility |
-| `plan-review` | Stage 2 | Implementation approach, phase breakdown, risk assessment |
-| `impl-review` | Stage 4 | Code quality, test coverage, spec adherence |
-| `pr-ready` | Stage 5 | Final self-check before PR creation |
-| `integration-review` | Stage 6 | System fit, architectural consistency, side effects |
+| `spec` | Stage 1 | Requirements clarity, completeness, feasibility |
+| `plan` | Stage 2 | Implementation approach, phase breakdown, risk assessment |
+| `impl` | Stage 4 | Code quality, test coverage, spec adherence |
+| `pr` | Stage 5 | Final self-check before PR creation |
+| `integration` | Stage 6 | System fit, architectural consistency, side effects |
 
 ## Builder Lifecycle
 
 ```
-spawning → implementing → blocked → implementing → pr-ready → complete
+spawning → implementing → blocked → implementing → pr → complete
                 ↑______________|
 ```
 
@@ -176,7 +176,7 @@ spawning → implementing → blocked → implementing → pr-ready → complete
 | `spawning` | Worktree created, builder starting up |
 | `implementing` | Actively working on the spec |
 | `blocked` | Stuck, needs architect help |
-| `pr-ready` | Implementation complete, ready for review |
+| `pr` | Implementation complete, ready for review |
 | `complete` | Merged, worktree can be cleaned up |
 
 ## Git Workflow

package/skeleton/roles/architect.md

@@ -16,8 +16,8 @@ Builders work autonomously in isolated git worktrees. The Architect:
 
 | Mode | Command | Use When |
 |------|---------|----------|
-| **Strict** (default) | `af spawn -p XXXX` | Porch orchestrates - runs autonomously to completion |
-| **Soft** | `af spawn --soft -p XXXX` | AI follows protocol - you verify compliance |
+| **Strict** (default) | `af spawn XXXX` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `af spawn XXXX --soft` | AI follows protocol - you verify compliance |
 
 **Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention.
 
@@ -28,16 +28,16 @@ Builders work autonomously in isolated git worktrees. The Architect:
 ### Agent Farm CLI (`af`)
 
 ```bash
-af spawn -p 1                          # Strict mode (default) - porch-driven
-af spawn -p 1 -t "feature"             # Strict mode with title (no spec yet)
-af spawn -p 1 --resume                 # Resume existing porch state
-af spawn --soft -p 1                   # Soft mode - protocol-guided
+af spawn 1                          # Strict mode (default) - porch-driven
+af spawn 1 -t "feature"             # Strict mode with title (no spec yet)
+af spawn 1 --resume                 # Resume existing porch state
+af spawn 1 --soft                   # Soft mode - protocol-guided
 af spawn --task "fix the bug"             # Ad-hoc task builder (soft mode)
 af spawn --worktree                       # Worktree with no initial prompt
 af status                                 # Check all builders
-af cleanup -p 1                        # Remove completed builder
+af cleanup -p 0001                        # Remove completed builder
 af dash start/stop                        # Dashboard management
-af send 1 "message"                    # Short message to builder
+af send 0001 "message"                    # Short message to builder
 ```
 
 **Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
@@ -45,8 +45,8 @@ af send 1 "message"                    # Short message to builder
 ### Porch CLI (for strict mode)
 
 ```bash
-porch status 1                           # Check project state
-porch approve 1 spec-approval            # Approve a gate
+porch status 0001                           # Check project state
+porch approve 0001 spec-approval            # Approve a gate
 porch pending                               # List pending gates
 ```
 
@@ -54,9 +54,9 @@ porch pending                               # List pending gates
 
 ```bash
 # 3-way parallel integration review of builder's PR
-consult --model gemini --type integration-review pr 35 &
-consult --model codex --type integration-review pr 35 &
-consult --model claude --type integration-review pr 35 &
+consult -m gemini --type integration pr 35 &
+consult -m codex --type integration pr 35 &
+consult -m claude --type integration pr 35 &
 wait
 ```
 
@@ -79,13 +79,13 @@ wait
 # 2. Spawn the builder
 
 # Default: Strict mode (porch-driven with gates)
-af spawn -p 42
+af spawn 42
 
 # With project title (if no spec exists yet)
-af spawn -p 42 -t "user-authentication"
+af spawn 42 -t "user-authentication"
 
 # Or: Soft mode (builder follows protocol independently)
-af spawn --soft -p 42
+af spawn 42 --soft
 ```
 
 ### 2. Approving Gates (Strict Mode Only)
@@ -95,26 +95,26 @@ The builder stops at gates requiring approval:
 **spec-approval** - After builder writes the spec
 ```bash
 # Review the spec in the builder's worktree
-cat worktrees/spir_42_user-authentication/codev/specs/42-user-authentication.md
+cat worktrees/spir_0042_user-authentication/codev/specs/0042-user-authentication.md
 
 # Approve if satisfactory
-porch approve 42 spec-approval
+porch approve 0042 spec-approval
 ```
 
 **plan-approval** - After builder writes the plan
 ```bash
 # Review the plan
-cat worktrees/spir_42_user-authentication/codev/plans/42-user-authentication.md
+cat worktrees/spir_0042_user-authentication/codev/plans/0042-user-authentication.md
 
 # Approve if satisfactory
-porch approve 42 plan-approval
+porch approve 0042 plan-approval
 ```
 
 ### 3. Monitoring Progress
 
 ```bash
 af status              # Overview of all builders
-porch status 42      # Detailed state for one project (strict mode)
+porch status 0042      # Detailed state for one project (strict mode)
 ```
 
 ### 4. Integration Review
@@ -123,9 +123,9 @@ When the builder creates a PR:
 
 ```bash
 # Run 3-way integration review
-consult --model gemini --type integration-review pr 83 &
-consult --model codex --type integration-review pr 83 &
-consult --model claude --type integration-review pr 83 &
+consult -m gemini --type integration pr 83 &
+consult -m codex --type integration pr 83 &
+consult -m claude --type integration pr 83 &
 wait
 
 # Post findings as PR comment
@@ -139,7 +139,7 @@ Integration looks good. No conflicts with existing modules.
 Architect integration review"
 
 # Notify builder
-af send 42 "PR approved, please merge"
+af send 0042 "PR approved, please merge"
 ```
 
 ### 5. Cleanup
@@ -147,7 +147,7 @@ af send 42 "PR approved, please merge"
 After builder merges and work is integrated:
 
 ```bash
-af cleanup -p 42
+af cleanup -p 0042
 ```
 
 ## Critical Rules
@@ -216,13 +216,13 @@ Before approving implementations with UX requirements:
 
 | Task | Command |
 |------|---------|
-| Start feature (strict, default) | `af spawn -p <id>` |
-| Start feature (soft) | `af spawn --soft -p <id>` |
+| Start feature (strict, default) | `af spawn <id>` |
+| Start feature (soft) | `af spawn <id> --soft` |
 | Check all builders | `af status` |
 | Check one project | `porch status <id>` |
 | Approve spec | `porch approve <id> spec-approval` |
 | Approve plan | `porch approve <id> plan-approval` |
 | See pending gates | `porch pending` |
-| Integration review | `consult --model X --type integration-review pr N` |
+| Integration review | `consult -m X --type integration pr N` |
 | Message builder | `af send <id> "short message"` |
 | Cleanup builder | `af cleanup -p <id>` |

package/skeleton/roles/builder.md

@@ -8,28 +8,27 @@ Builders run in one of two modes, determined by how they were spawned:
 
 | Mode | Command | Behavior |
 |------|---------|----------|
-| **Strict** (default) | `af spawn -p XXXX` | Porch orchestrates - runs autonomously to completion |
-| **Soft** | `af spawn --soft -p XXXX` | AI follows protocol - architect verifies compliance |
+| **Strict** (default) | `af spawn XXXX` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `af spawn XXXX --soft` | AI follows protocol - architect verifies compliance |
 
 ## Strict Mode (Default)
 
-Spawned with: `af spawn -p XXXX`
+Spawned with: `af spawn XXXX`
 
 In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**.
 
 ### The Core Loop
 
 ```bash
-# 1. Get your next tasks (project ID auto-detected from worktree)
-porch next
+# 1. Check your current state
+porch status
 
-# 2. Do the work described in the tasks
-# 3. Signal completion
-porch done
+# 2. Run the protocol loop
+porch run
 
-# 4. If porch hits a gate, STOP and wait for human approval
-# 5. After gate approval, run porch next again
-# 6. Repeat until project is complete
+# 3. If porch hits a gate, STOP and wait for human approval
+# 4. After gate approval, run porch again
+# 5. Repeat until project is complete
 ```
 
 Porch handles:
@@ -57,7 +56,7 @@ You must:
 1. Output a clear message: "Spec ready for approval. Waiting for human."
 2. **STOP working**
 3. Wait for the human to run `porch approve XXXX spec-approval`
-4. After approval, run `porch next` again
+4. After approval, run `porch run` again
 
 ### What You DON'T Do in Strict Mode
 
@@ -69,7 +68,7 @@ You must:
 
 ## Soft Mode
 
-Spawned with: `af spawn --soft -p XXXX` or `af spawn --task "..."`
+Spawned with: `af spawn XXXX --soft` or `af spawn --task "..."`
 
 In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly.
 
@@ -98,21 +97,21 @@ cat codev/protocols/spir/protocol.md
 Run 3-way consultations at checkpoints:
 ```bash
 # After writing spec
-consult --model gemini --type spec-review spec XXXX &
-consult --model codex --type spec-review spec XXXX &
-consult --model claude --type spec-review spec XXXX &
+consult -m gemini --protocol spir --type spec &
+consult -m codex --protocol spir --type spec &
+consult -m claude --protocol spir --type spec &
 wait
 
 # After writing plan
-consult --model gemini --type plan-review plan XXXX &
-consult --model codex --type plan-review plan XXXX &
-consult --model claude --type plan-review plan XXXX &
+consult -m gemini --protocol spir --type plan &
+consult -m codex --protocol spir --type plan &
+consult -m claude --protocol spir --type plan &
 wait
 
 # After implementation
-consult --model gemini --type impl-review pr N &
-consult --model codex --type impl-review pr N &
-consult --model claude --type impl-review pr N &
+consult -m gemini --protocol spir --type pr &
+consult -m codex --protocol spir --type pr &
+consult -m claude --protocol spir --type pr &
 wait
 ```
 
@@ -164,7 +163,7 @@ If you encounter issues you can't resolve:
 
 Example:
 ```
-## BLOCKED: Spec 77
+## BLOCKED: Spec 0077
 Can't find the auth helper mentioned in spec. Options:
 1. Create a new auth helper
 2. Use a third-party library

package/skeleton/templates/AGENTS.md

@@ -50,7 +50,7 @@ Codev provides three CLI tools:
 
 - **codev**: Project management (init, adopt, update, doctor)
 - **af**: Agent Farm orchestration (start, spawn, status, cleanup)
-- **consult**: AI consultation for reviews (pr, spec, plan)
+- **consult**: AI consultation for reviews (general, protocol, stats)
 
 For complete reference, see `codev/resources/commands/`:
 - `codev/resources/commands/overview.md` - Quick start

package/skeleton/templates/CLAUDE.md

@@ -48,7 +48,7 @@ Codev provides three CLI tools:
 
 - **codev**: Project management (init, adopt, update, doctor)
 - **af**: Agent Farm orchestration (start, spawn, status, cleanup)
-- **consult**: AI consultation for reviews (pr, spec, plan)
+- **consult**: AI consultation for reviews (general, protocol, stats)
 
 For complete reference, see `codev/resources/commands/`:
 - `codev/resources/commands/overview.md` - Quick start

package/skeleton/templates/cheatsheet.md

@@ -76,10 +76,12 @@ A **role** defines who does what work and what tools/permissions they have.
 | **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
+- `spec` - Review specification completeness
+- `plan` - Review implementation plan feasibility
+- `impl` - Review code for spec adherence
+- `pr` - Review pull request before merge
+- `phase` - Phase-scoped review (builder only)
+- `integration` - Review for architectural fit
 
 ### Context Hierarchy
 
@@ -102,7 +104,6 @@ Project management commands. Typically used by **humans** to set up and maintain
 | `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)
 
@@ -112,7 +113,7 @@ Architect-Builder orchestration. Used by both **humans and agents**—agents use
 |---------|-------------|
 | `af dash start` | Start dashboard (port 4200, 4300, etc.) |
 | `af dash stop` | Stop all processes |
-| `af spawn -p <id>` | Spawn a builder for project |
+| `af spawn <id> --protocol spir` | 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 |
@@ -126,20 +127,23 @@ Multi-agent consultation. Used by both humans and agents—**mostly agents** dur
 
 | 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 |
+| `consult -m <model> --prompt "text"` | General consultation |
+| `consult -m <model> --protocol spir --type spec` | Review a specification |
+| `consult -m <model> --protocol spir --type plan` | Review an implementation plan |
+| `consult -m <model> --protocol spir --type pr` | Review a pull request |
+| `consult stats` | View consultation statistics |
 
 **Models**: `gemini` (alias: `pro`), `codex` (alias: `gpt`), `claude` (alias: `opus`)
 
-**Review Types** (via `--type`):
+**Review Types** (via `--type` with `--protocol`):
 | 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) |
+| `spec` | Review spec completeness and clarity |
+| `plan` | Review plan coverage and feasibility |
+| `impl` | Review implementation quality (Builder use) |
+| `pr` | Review pull request before merge |
+| `phase` | Phase-scoped review (Builder use) |
+| `integration` | Review architectural fit (Architect use) |
 
 ---
 
@@ -161,9 +165,9 @@ Multi-agent consultation. Used by both humans and agents—**mostly agents** dur
 
 ```bash
 # Run 3-way review in parallel
-consult --model gemini pr <id> &
-consult --model codex pr <id> &
-consult --model claude pr <id> &
+consult -m gemini --protocol spir --type pr &
+consult -m codex --protocol spir --type pr &
+consult -m claude --protocol spir --type pr &
 wait
 ```
 

package/skeleton/templates/pr-overview.md

@@ -57,15 +57,15 @@ To use this template for architect-mediated reviews:
 
 ```bash
 # Fill out this template and save as overview.md, then:
-consult --model gemini pr 68 --context overview.md
+consult -m gemini --type pr --context overview.md
 
 # Or pipe directly:
-cat overview.md | consult --model gemini pr 68 --context -
+cat overview.md | consult -m gemini --type pr --context -
 
 # For 3-way parallel reviews:
-consult --model gemini pr 68 --context overview.md &
-consult --model codex pr 68 --context overview.md &
-consult --model claude pr 68 --context overview.md &
+consult -m gemini --type pr --context overview.md &
+consult -m codex --type pr --context overview.md &
+consult -m claude --type pr --context overview.md &
 wait
 ```