@cluesmith/codev 2.0.18 → 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/protocols/spike/builder-prompt.md

@@ -0,0 +1,62 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are executing a time-boxed technical feasibility spike.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the SPIKE protocol yourself (no porch orchestration)
+- Stay focused on the question — don't gold-plate
+- The findings document is your deliverable, not the code
+{{/if}}
+
+## Protocol
+Follow the SPIKE protocol: `codev/protocols/spike/protocol.md`
+
+{{#if task}}
+## Spike Question
+{{task_text}}
+{{/if}}
+
+## Recommended Workflow
+
+Follow this 3-step workflow. You can skip or reorder steps as the investigation demands.
+
+### 1. Research
+- Read documentation, examine existing code, search for prior art
+- Identify constraints, dependencies, and potential blockers
+- Understand the problem space before writing any code
+
+### 2. Iterate
+- Build minimal proof-of-concept code to test approaches
+- Focus on answering the feasibility question, not building production code
+- POC code doesn't need tests or polish
+- **Skip this step** if the answer is clear from research alone
+
+### 3. Findings
+- Write findings to `codev/spikes/<id>-<name>.md` using the template
+- Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats
+- Commit the findings document
+- Notify the architect: `af send architect "Spike <id> complete. Verdict: [verdict]"`
+
+## Key Principles
+
+- **Time-boxing**: Stay focused on the question. Don't explore tangents.
+- **Exploration over perfection**: POC code doesn't need tests or polish.
+- **Clear output**: The findings document is the deliverable, not the code.
+- **Know when to stop**: Once you can answer the feasibility question, write findings and stop. Don't keep iterating.
+- **Document failures**: "Not feasible" is a valid and valuable finding.
+
+## Handling Flaky Tests
+
+If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes):
+1. **DO NOT** edit `status.yaml` to bypass checks
+2. **DO NOT** skip porch checks or use any workaround to avoid the failure
+3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`)
+4. **DO** document each skipped flaky test in your findings under a `## Flaky Tests` section
+5. Commit the skip and continue with your work
+
+## Getting Started
+1. Read the SPIKE protocol document
+2. Understand the question you're investigating
+3. Start with research — don't jump straight to code

package/skeleton/protocols/spike/protocol.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "spike",
+  "version": "1.0.0",
+  "description": "Time-boxed technical feasibility exploration",
+  "input": {
+    "type": "task",
+    "required": false,
+    "default_for": []
+  },
+  "phases": [
+    {
+      "id": "spike",
+      "name": "Spike",
+      "description": "Execute the spike — research, iterate, write findings",
+      "type": "once"
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal spike is complete"
+    },
+    "BLOCKED": {
+      "description": "Signal spike is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "mode": "soft",
+    "consultation": {
+      "enabled": false,
+      "models": [],
+      "parallel": false
+    }
+  }
+}

package/skeleton/protocols/spike/protocol.md

@@ -0,0 +1,122 @@
+# SPIKE Protocol
+
+## Overview
+
+Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What would it take?" before committing to a full SPIR project.
+
+**Core Principle**: Stay focused on the question. Once you can answer it, write findings and stop.
+
+## When to Use
+
+**Use for**: Quick technical feasibility investigations, proof-of-concept explorations, "can we do X?" questions, evaluating approaches before committing to SPIR
+
+**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX), well-understood implementations (use TICK)
+
+### Spike vs Experiment
+
+| | Spike | Experiment |
+|---|---|---|
+| **Goal** | Answer a feasibility question | Test a formal hypothesis |
+| **Structure** | Lightweight guidance | Formal phases (hypothesis/design/execute/analyze) |
+| **Output** | Findings document | Experiment notes with metrics |
+| **Rigor** | Exploration-first | Measurement-first |
+| **Time** | Short (hours) | Longer (days) |
+
+## Spawning a Spike
+
+```bash
+af spawn --task "Can we use WebSockets for real-time updates?" --protocol spike
+af spawn --task "What would it take to support SQLite FTS?" --protocol spike
+```
+
+Spikes are always soft mode — no porch orchestration, no gates, no consultation.
+
+## Recommended Workflow
+
+The following 3-step workflow is **guidance only** — not enforced by porch. Follow it, skip steps, or reorder as the investigation demands.
+
+### Step 1: Research
+
+- Read documentation, examine existing code, search for prior art
+- Identify constraints, dependencies, and potential blockers
+- Understand the problem space before writing any code
+- Check if someone has already investigated this (look in `codev/spikes/`)
+
+### Step 2: Iterate
+
+- Build minimal proof-of-concept code
+- Try different approaches, hit walls, pivot
+- Focus on answering the feasibility question, not building production code
+- **Skip this step** if the answer is clear from research alone
+
+### Step 3: Findings
+
+- Write the findings document at `codev/spikes/<id>-<name>.md`
+- Use the template: `codev/protocols/spike/templates/findings.md`
+- Provide a clear feasibility verdict
+- Commit and notify the architect
+
+## Output
+
+Findings are stored in `codev/spikes/` using the pattern: `<id>-<descriptive-name>.md`
+
+Examples:
+- `codev/spikes/462-websocket-feasibility.md`
+- `codev/spikes/475-sqlite-fts-performance.md`
+
+The `<id>` is the GitHub issue number or project ID.
+
+## Proof-of-Concept Code
+
+POC code from the iterate step is committed to the spike branch alongside the findings document. It serves as evidence supporting the findings. However:
+
+- POC code does NOT need tests, polish, or production quality
+- POC code does NOT get merged to main — it stays on the spike branch
+- The findings document is the primary deliverable; the code is supporting evidence
+- If the spike leads to a SPIR project, the builder starts fresh
+
+## Outcome Handling
+
+- **Feasible**: Write findings with recommended approach and effort estimate. Architect decides whether to create a SPIR project.
+- **Not Feasible**: Write findings documenting why, what was tried, and what alternatives exist. This prevents future teams from repeating the investigation.
+- **Feasible with Caveats**: Write findings with conditions, risks, and trade-offs.
+
+In all cases, notify the architect:
+```bash
+af send architect "Spike <id> complete. Verdict: [feasible/not feasible/caveats]"
+```
+
+## Git Workflow
+
+### Commits
+```
+[Spike 462] Research: WebSocket library comparison
+[Spike 462] Iterate: POC with ws library
+[Spike 462] Findings: WebSockets feasible for real-time updates
+```
+
+### When to Commit
+- After significant research findings
+- After each iteration attempt
+- When writing the findings document (final commit)
+
+## Integration with Other Protocols
+
+### Spike -> SPIR
+When a spike validates feasibility:
+1. Create a SPIR spec referencing the spike findings
+2. Use findings to inform the solution approach
+3. Reference effort estimate for planning
+
+Example spec reference:
+```markdown
+## Background
+Spike 462 confirmed WebSocket feasibility with the `ws` library.
+See: codev/spikes/462-websocket-feasibility.md
+```
+
+### Spike -> "Do Not Pursue"
+When a spike finds something is not feasible:
+1. Document clearly in findings
+2. Close the related GitHub issue with a link to findings
+3. The findings become institutional knowledge

package/skeleton/protocols/spike/templates/findings.md

@@ -0,0 +1,67 @@
+# Spike: [Title]
+
+**Date**: YYYY-MM-DD
+
+**Verdict**: Feasible | Not Feasible | Feasible with Caveats
+
+## Question
+
+What technical question was being investigated? Be specific:
+- What are you trying to determine?
+- What prompted this investigation?
+- What decision depends on the answer?
+
+## Research Summary
+
+What was explored during the research phase:
+- Documentation read
+- Existing code examined
+- Prior art found
+- Key constraints identified
+
+## Approaches Tried
+
+What was built or tested during the iterate phase:
+
+### Approach 1: [Name]
+- **What**: Brief description of what was tried
+- **Result**: What happened
+- **Verdict**: Worked / Didn't work / Partially worked
+
+### Approach 2: [Name]
+*(Add more approaches as needed, or remove if research alone answered the question)*
+
+## Constraints Discovered
+
+Technical limitations, dependencies, and gotchas found during the investigation:
+- [Constraint 1]
+- [Constraint 2]
+
+## Recommended Approach
+
+*(If feasible)* How should full implementation proceed?
+- Recommended library/technique/pattern
+- Key architectural decisions
+- Things to watch out for
+
+*(If not feasible)* Why not, and what alternatives exist?
+
+## Effort Estimate
+
+Rough sizing for a full SPIR project: **Small** | **Medium** | **Large**
+
+- Small: < 300 LOC, 1-2 files, straightforward
+- Medium: 300-1000 LOC, multiple files, some complexity
+- Large: 1000+ LOC, architectural changes, significant complexity
+
+## Next Steps
+
+- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"]
+- [ ] [Or: "Do not pursue — blocked by X"]
+- [ ] [Or: "Investigate Y further before deciding"]
+
+## References
+
+- [Link to relevant documentation]
+- [Link to relevant code/commits]
+- [Link to external resources consulted]