@cluesmith/codev 2.1.0-rc.1 → 2.1.0-rc.2

package/skeleton/protocols/air/prompts/implement.md

@@ -0,0 +1,89 @@
+# IMPLEMENT Phase Prompt
+
+You are executing the **IMPLEMENT** phase of the AIR protocol.
+
+## Your Goal
+
+Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC.
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Read the Issue
+
+Read the full issue description. Identify:
+- What is the desired behavior?
+- What are the acceptance criteria?
+- Are there examples or mockups?
+- What files/modules are likely affected?
+
+### 2. Implement the Feature
+
+Apply a focused implementation:
+- Implement what the issue describes — no more, no less
+- Do NOT refactor surrounding code
+- Do NOT add features beyond what's described in the issue
+- Do NOT fix unrelated bugs you happen to notice (file separate issues)
+
+**Code Quality**:
+- Self-documenting code (clear names, obvious structure)
+- No commented-out code or debug prints
+- Follow existing project conventions
+
+### 3. Add Tests
+
+Write tests that:
+- Cover the main happy path
+- Cover key edge cases
+- Are deterministic (not flaky)
+
+Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.).
+
+### 4. Verify the Build
+
+Run build and tests:
+
+```bash
+npm run build      # Must pass
+npm test           # Must pass
+```
+
+Fix any failures before proceeding. If build/test commands don't exist, check `package.json`.
+
+### 5. Commit
+
+Stage and commit your changes:
+- Use explicit file paths (never `git add -A` or `git add .`)
+- Commit message: `[Air #{{issue.number}}] feat: <brief description>`
+
+## Signals
+
+When implementation and tests are complete and passing:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If the feature is too complex for AIR (> 300 LOC or architectural):
+
+```
+<signal>TOO_COMPLEX</signal>
+```
+
+If you're blocked (missing context, unclear requirements, etc.):
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```
+
+## Important Notes
+
+1. **Stay focused** — Implement what the issue describes, nothing else
+2. **Tests are expected** — Add tests unless the change is purely declarative (e.g., config only)
+3. **Build AND tests must pass** — Don't signal complete until both pass
+4. **Stay under 300 LOC** — If the feature grows beyond this, signal `TOO_COMPLEX`
+5. **No spec/plan artifacts** — AIR does not create files in `codev/specs/` or `codev/plans/`

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

@@ -0,0 +1,98 @@
+# PR Phase Prompt
+
+You are executing the **PR** phase of the AIR protocol.
+
+## Your Goal
+
+Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect.
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Create the Pull Request
+
+Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan:
+
+```bash
+gh pr create --title "[Air #{{issue.number}}] feat: <brief description>" --body "$(cat <<'EOF'
+## Summary
+
+<1-2 sentence description of the feature>
+
+Implements #{{issue.number}}
+
+## What Changed
+
+<Brief explanation of the implementation approach>
+
+## Key Decisions
+
+<Any notable decisions made during implementation, or "None — straightforward implementation">
+
+## Test Plan
+
+- [ ] Unit tests added
+- [ ] Build passes
+- [ ] All tests pass
+
+## Review Notes
+
+<Anything the reviewer should pay special attention to, or "Standard implementation — no special concerns">
+EOF
+)"
+```
+
+**IMPORTANT**: Do NOT create a review file in `codev/reviews/`. The PR body IS the review for AIR.
+
+### 2. Optional CMAP Review
+
+If the implementation is non-trivial, run 3-way consultation:
+
+```bash
+consult -m gemini --protocol air --type pr &
+consult -m codex --protocol air --type pr &
+consult -m claude --protocol air --type pr &
+```
+
+All three should run in the background (`run_in_background: true`).
+
+**This is optional** — use your judgement. For simple features (config changes, small UI additions), you may skip consultation. For features touching core logic or multiple modules, run it.
+
+### 3. Address Feedback (if CMAP was run)
+
+If you ran CMAP:
+- Wait for all consultations to complete
+- Record each model's verdict
+- Fix any issues identified
+- Push updates to the PR branch
+
+### 4. Notify Architect
+
+Send notification with PR link:
+
+```bash
+af send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
+```
+
+If CMAP was run, include verdicts:
+```bash
+af send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
+```
+
+## Signals
+
+When PR is created and ready for review:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you're blocked:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```

package/skeleton/protocols/air/protocol.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "air",
+  "version": "1.0.0",
+  "description": "AIR: Autonomous Implement & Review — lightweight protocol for small features from GitHub Issues",
+  "input": {
+    "type": "github-issue",
+    "required": false,
+    "default_for": ["--issue", "-i"]
+  },
+  "hooks": {
+    "pre-spawn": {
+      "collision-check": true,
+      "comment-on-issue": "On it! Implementing this feature now."
+    }
+  },
+  "phases": [
+    {
+      "id": "implement",
+      "name": "Implement",
+      "description": "Implement the feature and add tests",
+      "type": "once",
+      "steps": [
+        "read_issue",
+        "implement_feature",
+        "add_tests",
+        "verify_build",
+        "commit"
+      ],
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test -- --exclude='**/e2e/**'",
+          "description": "Unit tests only - e2e tests run in PR phase",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "transition": {
+        "on_complete": "pr",
+        "on_too_complex": "escalate"
+      }
+    },
+    {
+      "id": "pr",
+      "name": "Create PR",
+      "description": "Create pull request with review in PR body",
+      "type": "once",
+      "steps": [
+        "create_pr",
+        "link_issue",
+        "optional_consultation",
+        "notify_architect"
+      ],
+      "consultation": {
+        "on": "review",
+        "models": ["gemini", "codex"],
+        "type": "impl",
+        "parallel": true,
+        "max_rounds": 1
+      },
+      "checks": {
+        "pr_exists": {
+          "command": "gh pr list --head \"$(git branch --show-current)\" --json number --jq 'length' | grep -q '^[1-9]'",
+          "description": "PR must be created before signaling completion"
+        },
+        "e2e_tests": {
+          "command": "npm run test:e2e 2>&1 || echo 'e2e tests skipped (not configured)'",
+          "description": "Full e2e test suite",
+          "optional": true
+        }
+      },
+      "gate": "pr",
+      "transition": {
+        "on_complete": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "TOO_COMPLEX": {
+      "description": "Feature is too complex for AIR, escalate to ASPIR",
+      "transitions_to": "escalate"
+    },
+    "BLOCKED": {
+      "description": "Signal implementation is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "mode": "strict",
+    "consultation": {
+      "enabled": true,
+      "models": ["gemini", "codex"],
+      "parallel": true
+    },
+    "checks": {
+      "build": "npm run build",
+      "test": "npm test"
+    }
+  }
+}

package/skeleton/protocols/air/protocol.md

@@ -0,0 +1,88 @@
+# AIR Protocol
+
+> **AIR** = **A**utonomous **I**mplement & **R**eview
+>
+> A lightweight protocol for small features that are fully specified by their GitHub issue.
+> Two phases: Implement → Review. No spec/plan artifacts.
+
+## What is AIR?
+
+AIR is a minimal protocol for implementing small features (< 300 LOC) where the GitHub issue provides all the requirements. It skips the Specify and Plan phases entirely — the builder implements directly from the issue and creates a PR with the review embedded in the PR body.
+
+### How AIR Compares
+
+| Aspect | BUGFIX | AIR | ASPIR/SPIR |
+|--------|--------|-----|------------|
+| **Use case** | Bug fixes | Small features | New features |
+| **Input** | GitHub Issue | GitHub Issue | GitHub Issue → Spec |
+| **Phases** | Investigate → Fix → PR | Implement → PR | Specify → Plan → Implement → Review |
+| **Artifacts** | None | None | Spec, plan, review files |
+| **Review location** | PR body | PR body | `codev/reviews/` file |
+| **Consultation** | PR phase only | Optional (builder decides) | Every phase (3-way) |
+| **Human gates** | None (PR gate) | None (PR gate) | Spec + Plan + PR gates (SPIR) |
+| **LOC limit** | < 300 | < 300 | No limit |
+
+### When to Use AIR
+
+- Small features (< 300 LOC)
+- Requirements are clear from the GitHub issue
+- No architectural decisions needed
+- No new abstractions or significant refactoring required
+- Would be overkill for full SPIR/ASPIR ceremony
+
+### When NOT to Use AIR
+
+- Bug fixes → use **BUGFIX**
+- Features needing spec discussion → use **SPIR** or **ASPIR**
+- Amendments to existing specs → use **TICK**
+- Architectural changes → use **SPIR**
+- Complex features with multiple phases → use **SPIR** or **ASPIR**
+
+## Protocol Phases
+
+### I - Implement
+
+The builder reads the GitHub issue and implements the feature:
+
+1. Read and understand the issue requirements
+2. Implement the feature (< 300 LOC)
+3. Write tests
+4. Verify build and tests pass
+5. Commit with descriptive message
+
+If the feature grows beyond 300 LOC or requires architectural decisions, the builder signals `TOO_COMPLEX` to escalate to ASPIR.
+
+### R - Review (PR)
+
+The builder creates a PR with the review embedded in the PR body:
+
+1. Create PR linking to the issue
+2. Include a review section in the PR body (summary, key decisions, test plan)
+3. Optionally run CMAP consultation if the builder judges the complexity warrants it
+4. Notify the architect
+
+The **PR gate** is preserved — a human reviews all code before merge.
+
+## Usage
+
+```bash
+# Spawn a builder using AIR
+af spawn 42 --protocol air
+
+# The builder implements autonomously and stops at the PR gate
+```
+
+## File Structure
+
+```
+codev-skeleton/protocols/air/
+├── protocol.json          # Protocol definition
+├── protocol.md            # This file
+├── builder-prompt.md      # Builder instructions (Handlebars template)
+├── prompts/
+│   ├── implement.md       # Implement phase prompt
+│   └── pr.md              # PR phase prompt
+└── consult-types/
+    ├── impl-review.md     # Implementation consultation guide
+    └── pr-review.md       # PR consultation guide
+```

package/skeleton/resources/risk-triage.md

@@ -0,0 +1,111 @@
+# PR Review Risk Triage Guide
+
+Quick reference for the architect's risk-based PR review process. For the full integration review workflow, see `codev/roles/architect.md` Section 4.
+
+## Risk Assessment
+
+When a builder PR arrives, assess risk before choosing review depth.
+
+### Step 1: Check Size and Scope
+
+```bash
+gh pr diff --stat <N>
+gh pr view <N> --json files | jq '.files[].path'
+```
+
+### Step 2: Determine Risk Level
+
+**Precedence: highest factor wins.** If any single factor is high, the overall risk is high.
+
+| Factor | Low | Medium | High |
+|--------|-----|--------|------|
+| **Lines changed** | < 100 | 100-500 | > 500 |
+| **Files touched** | 1-3 | 4-10 | > 10 |
+| **Subsystem** | Docs, tests, cosmetic | Features, commands, shared libs | Protocol, state mgmt, security |
+| **Cross-cutting** | No shared interfaces | Some shared code | Core interfaces, APIs |
+
+### Step 3: Execute Review
+
+| Risk | Action | Cost |
+|------|--------|------|
+| **Low** | Read PR, summarize, tell builder to merge | $0 |
+| **Medium** | `consult -m claude --type integration pr N` | ~$1-2 |
+| **High** | 3-way CMAP (Gemini + Codex + Claude in parallel) | ~$4-5 |
+
+## Subsystem Path Mappings
+
+| Path Pattern | Subsystem | Risk |
+|-------------|-----------|------|
+| `packages/codev/src/commands/porch/` | Protocol orchestrator | High |
+| `packages/codev/src/tower/` | Tower architecture | High |
+| `packages/codev/src/state/` | State management | High |
+| `codev/protocols/` | Protocol definitions | High |
+| `codev-skeleton/protocols/` | Protocol templates | High |
+| `packages/codev/src/commands/af/` | Agent Farm commands | Medium |
+| `packages/codev/src/commands/consult/` | Consultation system | Medium |
+| `packages/codev/src/lib/` | Shared libraries | Medium |
+| `packages/codev/src/commands/` (other) | CLI commands | Medium |
+| `codev/roles/` | Role definitions | Medium |
+| `codev-skeleton/roles/` | Role templates | Medium |
+| `codev/resources/` | Documentation | Low |
+| `codev/specs/`, `codev/plans/`, `codev/reviews/` | Project artifacts | Low |
+| `packages/codev/tests/` | Tests only | Low |
+| `*.md` (not in `protocols/`) | Documentation | Low |
+
+## Typical Mappings by Protocol
+
+- **Low**: Most bugfixes, ASPIR features, documentation, UI tweaks, config updates
+- **Medium**: SPIR features, new commands, refactors touching 3+ files, new utility modules
+- **High**: Protocol changes, porch state machine, Tower architecture, security model changes
+
+**Note:** Protocol type is a heuristic, not the primary signal. An ASPIR PR that changes core state management should still be high-risk. Always check the actual diff.
+
+## Example Workflows
+
+### Low Risk: Bugfix (12 lines, 1 file, tests/)
+
+```bash
+$ gh pr diff --stat 120
+ packages/codev/tests/unit/foo.test.ts | 12 ++++++------
+ 1 file changed, 6 insertions(+), 6 deletions(-)
+
+# Low risk — read and approve
+gh pr comment 120 --body "## Architect Review
+
+Low-risk test fix. Corrects assertion in foo.test.ts.
+
+---
+Architect review"
+
+af send 0042 "PR approved, please merge"
+```
+
+### Medium Risk: New Feature (180 lines, 3 files, commands/)
+
+```bash
+$ gh pr diff --stat 121
+ packages/codev/src/commands/consult/risk.ts | 120 +++++++++++++
+ packages/codev/src/cli.ts                    |  15 ++
+ packages/codev/tests/unit/risk.test.ts       |  45 +++++
+ 3 files changed, 180 insertions(+)
+
+# Medium risk — single-model review
+consult -m claude --type integration pr 121
+```
+
+### High Risk: Protocol Change (650 lines, 14 files, porch/)
+
+```bash
+$ gh pr diff --stat 122
+ packages/codev/src/commands/porch/run.ts     | 200 ++++++++++++------
+ packages/codev/src/commands/porch/next.ts     | 150 ++++++++++----
+ packages/codev/src/state/project.ts           |  80 +++++---
+ ... 11 more files
+ 14 files changed, 420 insertions(+), 230 deletions(-)
+
+# High risk — full 3-way CMAP
+consult -m gemini --type integration pr 122 &
+consult -m codex --type integration pr 122 &
+consult -m claude --type integration pr 122 &
+wait
+```

package/skeleton/resources/workflow-reference.md

@@ -38,7 +38,8 @@ Quick reference for the 7-stage project workflow. For protocol details, see `cod
 │                        HANDOFF / INTEGRATION                                        │
 ├─────────────────────────────────────────────────────────────────────────────────────┤
 │  → 6. COMMITTED                                                                     │
-│         Architect does 3-way integration review                                     │
+│         Architect assesses PR risk: gh pr diff --stat N                             │
+│         Low: Read + merge | Medium: 1-model review | High: 3-way CMAP              │
 │         Architect iterates with builder via PR comments                             │
 │         Architect tells builder to merge                                            │
 │         Builder merges PR (NO --delete-branch flag)                                 │
@@ -59,7 +60,7 @@ Quick reference for the 7-stage project workflow. For protocol details, see `cod
 | 3 | planned | Architect | Commit spec + plan | Committed to main |
 | 4 | implementing | Builder | IDE loop per phase | All phases complete |
 | 5 | implemented | Builder | Write review, create PR | PR created |
-| 6 | committed | Architect + Builder | Integration review, merge | PR merged |
+| 6 | committed | Architect + Builder | Risk-based integration review, merge | PR merged |
 | 7 | integrated | Human | Validate production | Human confirms |
 
 ## Human Gates
@@ -143,9 +144,15 @@ consult -m codex --protocol spir --type impl
 consult -m gemini --protocol spir --type pr
 consult -m codex --protocol spir --type pr
 
-# Integration review (during Stage 6)
-consult -m gemini --type integration
-consult -m codex --type integration
+# Integration review (during Stage 6 — depth depends on risk)
+# Low risk: no consult needed, architect reads and merges
+# Medium risk: single-model review
+consult -m claude --type integration pr N
+# High risk: full 3-way CMAP
+consult -m gemini --type integration pr N &
+consult -m codex --type integration pr N &
+consult -m claude --type integration pr N &
+wait
 
 # Parallel 3-way reviews (run all three concurrently)
 consult -m gemini --protocol spir --type spec &
@@ -162,7 +169,7 @@ wait
 | `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 |
+| `integration` | Stage 6 | System fit, architectural consistency, side effects (depth varies by risk — see `codev/resources/risk-triage.md`) |
 
 ## Builder Lifecycle
 
@@ -240,3 +247,4 @@ af cleanup -p XXXX --force
 - Builder role: `codev/roles/builder.md`
 - Architect role: `codev/roles/architect.md`
 - Consultant role: `codev/roles/consultant.md`
+- Risk triage guide: `codev/resources/risk-triage.md`

package/skeleton/roles/architect.md

@@ -53,7 +53,10 @@ porch pending                               # List pending gates
 ### Consult Tool (for integration reviews)
 
 ```bash
-# 3-way parallel integration review of builder's PR
+# Single-model review (medium risk)
+consult -m claude --type integration pr 35
+
+# 3-way parallel review (high risk)
 consult -m gemini --type integration pr 35 &
 consult -m codex --type integration pr 35 &
 consult -m claude --type integration pr 35 &
@@ -117,12 +120,63 @@ af status              # Overview of all builders
 porch status 0042      # Detailed state for one project (strict mode)
 ```
 
-### 4. Integration Review
+### 4. Integration Review (Risk-Based Triage)
+
+When the builder creates a PR, **assess risk first** before deciding review depth.
+
+> **Full reference**: See `codev/resources/risk-triage.md` for subsystem mappings and examples.
+
+#### Step 1: Assess Risk
+
+```bash
+gh pr diff --stat <N>    # See lines changed and files touched
+gh pr view <N> --json files | jq '.files[].path'   # See which subsystems
+```
+
+#### Step 2: Triage
+
+| Risk | Criteria | Action |
+|------|----------|--------|
+| **Low** | <100 lines, 1-3 files, isolated (docs, tests, cosmetic, bugfixes) | Read PR, summarize root cause + fix, tell builder to merge |
+| **Medium** | 100-500 lines, 4-10 files, touches shared code (features, commands) | Single-model review: `consult -m claude --type integration pr N` |
+| **High** | >500 lines, >10 files, core subsystems (porch, Tower, protocols, security) | Full 3-way CMAP (see below) |
+
+**Precedence: highest factor wins.** If any single factor (lines, files, subsystem, or cross-cutting scope) is high-risk, treat the whole PR as high-risk.
+
+**Typical mappings:**
+- **Low**: Most bugfixes, ASPIR features, documentation, UI tweaks
+- **Medium**: SPIR features, new commands, refactors touching 3+ files
+- **High**: Protocol changes, porch state machine, Tower architecture, security model
+
+#### Step 3: Execute Review
+
+**Low risk** — no external models needed:
+```bash
+# Read the PR yourself, then approve
+gh pr comment 83 --body "## Architect Review
+
+Low-risk change. [Summary of what changed and why.]
+
+---
+Architect review"
+
+af send 0042 "PR approved, please merge"
+```
+
+**Medium risk** — single-model review:
+```bash
+consult -m claude --type integration pr 83
+
+# Post findings as PR comment
+gh pr comment 83 --body "## Architect Integration Review
+...
+Architect integration review"
 
-When the builder creates a PR:
+af send 0042 "PR approved, please merge"
+```
 
+**High risk** — full 3-way CMAP:
 ```bash
-# Run 3-way integration review
 consult -m gemini --type integration pr 83 &
 consult -m codex --type integration pr 83 &
 consult -m claude --type integration pr 83 &
@@ -130,15 +184,9 @@ wait
 
 # Post findings as PR comment
 gh pr comment 83 --body "## Architect Integration Review
-
-**Verdict: APPROVE**
-
-Integration looks good. No conflicts with existing modules.
-
----
+...
 Architect integration review"
 
-# Notify builder
 af send 0042 "PR approved, please merge"
 ```
 
@@ -225,6 +273,8 @@ Before approving implementations with UX requirements:
 | Approve spec | `porch approve <id> spec-approval` |
 | Approve plan | `porch approve <id> plan-approval` |
 | See pending gates | `porch pending` |
-| Integration review | `consult -m X --type integration pr N` |
+| Assess PR risk | `gh pr diff --stat N` |
+| Integration review (medium) | `consult -m claude --type integration pr N` |
+| Integration review (high) | 3-way CMAP (see Section 4) |
 | Message builder | `af send <id> "short message"` |
 | Cleanup builder | `af cleanup -p <id>` |