@cluesmith/codev 2.0.3 → 2.0.7

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,15 @@ Builders work autonomously in isolated git worktrees. The Architect:
 ### Agent Farm CLI (`af`)
 
 ```bash
-af spawn -p 0001                          # Strict mode (default) - porch-driven
-af spawn -p 0001 -t "feature"             # Strict mode with title (no spec yet)
-af spawn -p 0001 --resume                 # Resume existing porch state
-af spawn --soft -p 0001                   # Soft mode - protocol-guided
+af spawn 1                             # Strict mode (default) - porch-driven
+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 0001                        # Remove completed builder
+af cleanup --project 1                    # Remove completed builder
 af dash start/stop                        # Dashboard management
-af send 0001 "message"                    # Short message to builder
+af send 1 "message"                    # Short message to builder
 ```
 
 **Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
@@ -45,8 +44,8 @@ af send 0001 "message"                    # Short message to builder
 ### Porch CLI (for strict mode)
 
 ```bash
-porch status 0001                           # Check project state
-porch approve 0001 spec-approval            # Approve a gate
+porch status 1                           # Check project state
+porch approve 1 spec-approval            # Approve a gate
 porch pending                               # List pending gates
 ```
 
@@ -54,16 +53,16 @@ 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
 ```
 
 ## Responsibilities
 
 1. **Decide what to build** - Identify features, prioritize work
-2. **Maintain project list** - Track all projects in `codev/projectlist.md`
+2. **Track projects** - Use GitHub Issues as the project registry
 3. **Spawn builders** - Choose soft or strict mode based on needs
 4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue
 5. **Monitor progress** - Track builder status, unblock when stuck
@@ -75,17 +74,14 @@ wait
 ### 1. Starting a New Feature
 
 ```bash
-# 1. Reserve project number in projectlist.md
+# 1. Create a GitHub Issue for the feature
 # 2. Spawn the builder
 
 # Default: Strict mode (porch-driven with gates)
-af spawn -p 0042
-
-# With project title (if no spec exists yet)
-af spawn -p 0042 -t "user-authentication"
+af spawn 42
 
 # Or: Soft mode (builder follows protocol independently)
-af spawn --soft -p 0042
+af spawn 42 --soft
 ```
 
 ### 2. Approving Gates (Strict Mode Only)
@@ -95,26 +91,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_0042_user-authentication/codev/specs/0042-user-authentication.md
+cat worktrees/spir_42_user-authentication/codev/specs/42-user-authentication.md
 
 # Approve if satisfactory
-porch approve 0042 spec-approval
+porch approve 42 spec-approval
 ```
 
 **plan-approval** - After builder writes the plan
 ```bash
 # Review the plan
-cat worktrees/spir_0042_user-authentication/codev/plans/0042-user-authentication.md
+cat worktrees/spir_42_user-authentication/codev/plans/42-user-authentication.md
 
 # Approve if satisfactory
-porch approve 0042 plan-approval
+porch approve 42 plan-approval
 ```
 
 ### 3. Monitoring Progress
 
 ```bash
 af status              # Overview of all builders
-porch status 0042      # Detailed state for one project (strict mode)
+porch status 42      # Detailed state for one project (strict mode)
 ```
 
 ### 4. Integration Review
@@ -123,9 +119,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 +135,7 @@ Integration looks good. No conflicts with existing modules.
 Architect integration review"
 
 # Notify builder
-af send 0042 "PR approved, please merge"
+af send 42 "PR approved, please merge"
 ```
 
 ### 5. Cleanup
@@ -147,7 +143,7 @@ af send 0042 "PR approved, please merge"
 After builder merges and work is integrated:
 
 ```bash
-af cleanup -p 0042
+af cleanup -p 42
 ```
 
 ## Critical Rules
@@ -158,21 +154,21 @@ af cleanup -p 0042
 3. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
 
 ### ALWAYS Do These:
-1. **Reserve project numbers first** - Update projectlist.md before spawning
+1. **Create GitHub Issues first** - Track projects as issues before spawning
 2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully
 3. **Use PR comments for feedback** - Not terminal send-keys
 4. **Let builders own their work** - Guide, don't take over
 
 ## Project Tracking
 
-**`codev/projectlist.md` is the canonical source of truth.**
+**GitHub Issues are the canonical source of truth for project tracking.**
 
 ```bash
 # See what needs work
-cat codev/projectlist.md
+gh issue list --label "priority:high"
 
-# Find high-priority items
-grep -A5 "priority: high" codev/projectlist.md
+# View a specific project
+gh issue view 42
 ```
 
 Update status as projects progress:
@@ -216,13 +212,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,12 +8,12 @@ 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**.
 
@@ -69,7 +69,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 +98,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 +164,7 @@ If you encounter issues you can't resolve:
 
 Example:
 ```
-## BLOCKED: Spec 0077
+## BLOCKED: Spec 77
 Can't find the auth helper mentioned in spec. Options:
 1. Create a new auth helper
 2. Use a third-party library

package/skeleton/roles/consultant.md

@@ -25,3 +25,9 @@ You are a consultant providing a second perspective to support decision-making.
 | Consultant | Provides perspective, supports decisions |
 
 You think alongside the other agents, helping them see blind spots. You have filesystem access — use it to verify your claims against the actual codebase.
+
+## File Access Rules
+
+- **ALWAYS read files directly from disk** when reviewing specs, plans, or code. File paths are provided in the query — open and read them.
+- **NEVER rely on `git diff` or `git log -p` as your primary review source.** Diffs are lossy, get truncated, and miss uncommitted work. Read the actual files instead.
+- If you need to understand what changed, read the full file first, then optionally use `git diff` as a secondary reference.

package/skeleton/templates/AGENTS.md

@@ -30,9 +30,9 @@ This project uses **Codev** for AI-assisted development.
 ## File Naming Convention
 
 Use sequential numbering with descriptive names:
-- Specification: `codev/specs/0001-feature-name.md`
-- Plan: `codev/plans/0001-feature-name.md`
-- Review: `codev/reviews/0001-feature-name.md`
+- Specification: `codev/specs/1-feature-name.md`
+- Plan: `codev/plans/1-feature-name.md`
+- Review: `codev/reviews/1-feature-name.md`
 
 ## Git Workflow
 
@@ -40,8 +40,8 @@ Use sequential numbering with descriptive names:
 
 Commit messages format:
 ```
-[Spec 0001] Description of change
-[Spec 0001][Phase: implement] feat: Add feature
+[Spec 1] Description of change
+[Spec 1][Phase: implement] feat: Add feature
 ```
 
 ## CLI Commands
@@ -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

@@ -28,9 +28,9 @@ This project uses **Codev** for AI-assisted development.
 ## File Naming Convention
 
 Use sequential numbering with descriptive names:
-- Specification: `codev/specs/0001-feature-name.md`
-- Plan: `codev/plans/0001-feature-name.md`
-- Review: `codev/reviews/0001-feature-name.md`
+- Specification: `codev/specs/1-feature-name.md`
+- Plan: `codev/plans/1-feature-name.md`
+- Review: `codev/reviews/1-feature-name.md`
 
 ## Git Workflow
 
@@ -38,8 +38,8 @@ Use sequential numbering with descriptive names:
 
 Commit messages format:
 ```
-[Spec 0001] Description of change
-[Spec 0001][Phase: implement] feat: Add feature
+[Spec 1] Description of change
+[Spec 1][Phase: implement] feat: Add feature
 ```
 
 ## CLI Commands
@@ -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/lifecycle.md

@@ -18,7 +18,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** The Architect (AI) writes a specification. The human reviews and approves it.
 
-**Artifact:** Draft specification in `codev/specs/NNNN-name.md`
+**Artifact:** Draft specification in `codev/specs/NNN-name.md`
 
 ---
 
@@ -30,7 +30,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** The Architect creates an implementation plan.
 
-**Artifact:** Approved specification in `codev/specs/NNNN-name.md`
+**Artifact:** Approved specification in `codev/specs/NNN-name.md`
 
 ---
 
@@ -42,7 +42,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** A Builder is spawned to implement the plan.
 
-**Artifact:** Implementation plan in `codev/plans/NNNN-name.md`
+**Artifact:** Implementation plan in `codev/plans/NNN-name.md`
 
 ---
 
@@ -90,7 +90,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** Nothing - the project is complete! A review document captures lessons learned.
 
-**Artifact:** Review document in `codev/reviews/NNNN-name.md`
+**Artifact:** Review document in `codev/reviews/NNN-name.md`
 
 ---
 
@@ -100,7 +100,7 @@ Projects can also end up in terminal states if they won't be completed:
 
 ### Abandoned
 
-The project was canceled or rejected. It will not be implemented. The notes field in `projectlist.md` should explain why.
+The project was canceled or rejected. It will not be implemented. Close the GitHub Issue with a comment explaining why.
 
 ### On-Hold
 
@@ -125,12 +125,12 @@ conceived → [HUMAN APPROVES] → specified → planned → implementing → im
 
 ## Managing Projects
 
-All project tracking happens in `codev/projectlist.md`. To manage projects:
+Project tracking uses **GitHub Issues**. To manage projects:
 
-- **Add a project:** Tell the Architect what you want to build
-- **Update status:** Ask the Architect to update the project status
+- **Add a project:** Create a GitHub Issue describing what you want to build
+- **Update status:** Update issue labels and comments as work progresses
 - **Approve stages:** Review the spec/plan and tell the Architect to mark it approved
-- **View progress:** Check the Projects tab in the dashboard or read `projectlist.md`
+- **View progress:** Check the Work tab in the dashboard or `gh issue list`
 
 ---
 

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
 ```
 

package/templates/open.html

@@ -988,17 +988,20 @@
       // Position dialog next to click
       const dialog = document.querySelector('.dialog');
       const rect = event.target.getBoundingClientRect();
-      const dialogWidth = 700;
+      // Use actual rendered width (CSS max-width: 90vw constrains on mobile)
+      const dialogWidth = Math.min(700, window.innerWidth * 0.9);
       const dialogHeight = 350;
+      const margin = 10;
 
       // Position to the right of the line number, with some padding
       let left = rect.right + 10;
       let top = rect.top;
 
       // Keep dialog in viewport
-      if (left + dialogWidth > window.innerWidth) {
-        left = window.innerWidth - dialogWidth - 20;
+      if (left + dialogWidth > window.innerWidth - margin) {
+        left = (window.innerWidth - dialogWidth) / 2;
       }
+      if (left < margin) left = margin;
       if (top + dialogHeight > window.innerHeight) {
         top = window.innerHeight - dialogHeight - 20;
       }

package/templates/tower.html

@@ -203,36 +203,6 @@
       overflow: hidden;
     }
 
-    .instance.gate-pending {
-      border-color: #f59e0b;
-      animation: gate-pulse 2s infinite;
-    }
-
-    @keyframes gate-pulse {
-      0%, 100% { border-color: #f59e0b; }
-      50% { border-color: #d97706; }
-    }
-
-    .gate-indicator {
-      padding: 8px 20px;
-      background: rgba(245, 158, 11, 0.15);
-      border-bottom: 1px solid var(--border);
-      font-size: 14px;
-      color: #f59e0b;
-      display: flex;
-      align-items: center;
-      gap: 8px;
-    }
-
-    .gate-indicator .gate-name {
-      font-weight: 600;
-    }
-
-    .gate-indicator .gate-builder {
-      color: var(--text-muted);
-      font-size: 12px;
-    }
-
     .instance-header {
       display: flex;
       justify-content: space-between;
@@ -1217,7 +1187,6 @@
     function renderInstance(instance) {
       const statusClass = instance.running ? 'running' : 'stopped';
       const statusText = instance.running ? 'Running' : 'Stopped';
-      const hasGate = instance.gateStatus?.hasGate;
 
       // Render terminals list - always show Overview first, then individual terminals
       const terminals = instance.terminals || [];
@@ -1270,16 +1239,8 @@
         ? formatDate(instance.lastUsed)
         : 'Never';
 
-      const gateIndicatorHtml = hasGate ? `
-        <div class="gate-indicator">
-          <span>⏳</span>
-          <span class="gate-name">${escapeHtml(instance.gateStatus.gateName || 'approval')}</span>
-          ${instance.gateStatus.builderId ? `<span class="gate-builder">(${escapeHtml(instance.gateStatus.builderId)})</span>` : ''}
-        </div>
-      ` : '';
-
       return `
-        <div class="instance ${hasGate ? 'gate-pending' : ''}" data-project="${escapeHtml(instance.workspacePath)}">
+        <div class="instance" data-project="${escapeHtml(instance.workspacePath)}">
           <div class="instance-header">
             <div class="instance-title">
               <span class="instance-name">${escapeHtml(instance.workspaceName)}</span>
@@ -1297,7 +1258,6 @@
               `}
             </div>
           </div>
-          ${gateIndicatorHtml}
           <div class="instance-path-row">
             <span class="instance-path" title="${escapeHtml(instance.workspacePath)}">
               ${escapeHtml(instance.workspacePath)}