@cluesmith/codev 3.2.4 → 3.3.0

package/skeleton/protocols/air/consult-types/impl-review.md

@@ -1,43 +1,32 @@
 # Implementation Review Prompt
 
 ## Context
-You are reviewing implementation work for a small feature built under the AIR protocol. The builder implemented directly from a GitHub issue — there is no spec or plan document. Your job is to verify the implementation matches the issue requirements and follows good practices.
 
-## CRITICAL: Verify Before Flagging
+You are reviewing implementation work built under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec or plan document. Verify it matches the issue and follows good practice; review against the issue, not against artifacts AIR does not produce.
 
-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
+## Verify before flagging
+
+Before requesting changes for missing configuration, wrong patterns, or framework issues, confirm the claim against the project rather than your training data:
+
+- Check `package.json` for the actual dependency versions — framework conventions change between major versions.
+- Read the actual config files (or confirm their deliberate absence) before flagging a missing config.
 
 ## Baked Decisions
 
 If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the implementation **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Issue Adherence**
-   - Does the implementation fulfill the issue requirements?
-   - Are the described 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?
-   - Do tests cover the main paths AND edge cases?
-
-4. **Scope**
-   - Is the change under 300 LOC? If not, should this be escalated to ASPIR?
-   - Does the implementation stay focused on the issue, or does it include unrelated changes?
+- **Issue Adherence** — the implementation fulfills the issue's requirements and acceptance criteria.
+- **Code Quality** — readable and maintainable; no obvious bugs; error cases handled.
+- **Test Coverage** — tests are adequate and cover main paths and edge cases.
+- **Scope** — the change stays focused on the issue and under ~300 LOC; if larger, it should escalate to ASPIR.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -51,14 +40,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Implementation looks good, ready for PR
-- `REQUEST_CHANGES`: Issues that must be fixed
-- `COMMENT`: Minor suggestions, can proceed but note feedback
-
-## Notes
+- `APPROVE`: implementation looks good, ready for PR.
+- `REQUEST_CHANGES`: issues that must be fixed.
+- `COMMENT`: minor suggestions; can proceed but note the feedback.
 
-- AIR has no spec or plan — review against the GitHub issue
-- Focus on "does this feature work correctly" not "is this architecturally perfect"
-- If referencing line numbers, use `file:line` format
-- The builder needs actionable feedback
+AIR has no spec or plan — review against the GitHub issue, and judge "does this feature work correctly", not "is this architecturally perfect".

package/skeleton/protocols/air/consult-types/pr-review.md

@@ -1,48 +1,30 @@
 # PR Ready Review Prompt
 
 ## Context
-You are performing a review of a pull request created under the AIR protocol. The builder implemented a small feature directly from a GitHub issue — there are no spec, plan, or review files. The review is embedded in the PR body.
+
+You are reviewing a pull request created under the AIR protocol — a small feature implemented directly from a GitHub issue, with no spec, plan, or review file. The review is embedded in the PR body.
 
 ## Baked Decisions
 
 If the issue body includes content under a "Baked Decisions" heading, the architect has marked those choices as fixed. Do not autonomously challenge them: do not propose alternative languages, frameworks, deployment shapes, or dependencies that contradict a baked decision. You may `COMMENT` with concerns about a baked decision (the architect decides whether to rescind it); reserve `REQUEST_CHANGES` for the case where the code **fails to honor** a stated baked decision — that is a real defect.
 
-If the baked decisions themselves contain contradictions, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
+If the baked decisions themselves contradict each other, do not pick one — `REQUEST_CHANGES` and ask the architect to clarify before proceeding.
 
 ## Focus Areas
 
-1. **Completeness**
-   - Are the issue requirements implemented?
-   - Is the PR body review section filled out (summary, key decisions, test plan)?
-   - Are commits properly formatted?
-
-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?
-   - Is the code properly formatted?
-
-4. **Scope**
-   - Is the change under 300 LOC?
-   - Does the implementation stay focused on the issue?
-   - Are there unrelated changes bundled in?
-
-5. **PR Quality**
-   - Does the PR link to the issue?
-   - Is the PR body review section informative?
-   - Is the branch up to date with its base (the integration branch the PR targets)?
+- **Completeness** — the issue's requirements are implemented and the PR body's review section (summary, key decisions, test plan) is filled out.
+- **Test Status** — all tests pass, coverage is adequate, and any skipped/flaky tests are accounted for.
+- **Code Cleanliness** — no debug code, no stray `TODO`, code properly formatted.
+- **Scope** — the change stays under ~300 LOC and focused on the issue, with no unrelated changes bundled in.
+- **PR Quality** — the PR links to the issue, the body's review section is informative, and the branch is up to date with its base (the integration branch the PR targets).
 
 ## Scope
 
-- **DO NOT** flag the syntax of `git diff` examples that appear in review-file prose (e.g., `git diff ci..HEAD` inside a "Files Changed" caption or "How to Test Locally" section). Quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
+Do not flag the syntax of `git diff` examples that appear in review-file prose (e.g. `git diff ci..HEAD` inside a "Files Changed" caption) — quoted diff syntax is documentation, not a command. Apply two-dot/three-dot scrutiny only to diffs you compute yourself.
 
 ## Verdict Format
 
-After your review, provide your verdict in exactly this format:
+Provide your verdict in exactly this format — `consult` parses it:
 
 ```
 ---
@@ -56,13 +38,8 @@ KEY_ISSUES:
 ...
 ```
 
-**Verdict meanings:**
-- `APPROVE`: Ready for architect review
-- `REQUEST_CHANGES`: Issues to fix before review
-- `COMMENT`: Minor items, can proceed but note feedback
-
-## Notes
+- `APPROVE`: ready for architect review.
+- `REQUEST_CHANGES`: issues to fix before review.
+- `COMMENT`: minor items; can proceed but note the feedback.
 
-- AIR has no spec, plan, or review files — review the PR body and code diff
-- 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
+AIR has no spec, plan, or review files — review the PR body and the code diff.

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

@@ -2,9 +2,9 @@
 
 You are executing the **IMPLEMENT** phase of the AIR protocol.
 
-## Your Goal
+## Goal
 
-Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC.
+Implement the feature described in the issue, with tests, as a focused change under ~300 LOC. AIR produces no `codev/specs/` or `codev/plans/` artifacts.
 
 ## Baked Decisions
 
@@ -17,79 +17,26 @@ If two baked decisions contradict each other, do not pick one — pause, flag th
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## What must be true when you finish
 
-### 1. Read the Issue
+- **The feature matches the issue.** You have read it fully — desired behavior, acceptance criteria, any examples — and implemented exactly what it describes: no refactoring of surrounding code, no features beyond the issue, no unrelated bug fixes (file separate issues for those). Self-documenting code, no debug or commented-out code, existing project conventions.
+- **Tests exist.** They cover the happy path and the key edge cases, and are deterministic. (Purely declarative changes — config only — may not need them; say so.)
+- **Build and tests pass.** Confirm the real project commands (check `package.json` if unsure) and run them; fix failures before signaling.
+- **The change stays within AIR scope.** If it grows past ~300 LOC or turns architectural, signal `TOO_COMPLEX` rather than pressing on.
 
-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>`
+Commit with an explicit staged path and the 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/`
+- Implementation and tests complete and passing:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Too complex for AIR (> ~300 LOC or architectural):
+  ```
+  <signal>TOO_COMPLEX</signal>
+  ```
+- Blocked (missing context, unclear requirements):
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```

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

@@ -2,32 +2,20 @@
 
 You are executing the **PR** phase of the AIR protocol.
 
-## Your Goal
+## Goal
 
-Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect.
+Open the PR with the review embedded in its body, optionally run CMAP, and notify the architect.
 
 ## Context
 
 - **Issue**: #{{issue.number}} — {{issue.title}}
 - **Current State**: {{current_state}}
 
-## Process
+## Create the PR
 
-### 1. Create the Pull Request
+**The PR body IS the review for AIR** — do not create a file in `codev/reviews/`. Include a summary, the key decisions, and a test plan in the body itself.
 
-Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan.
-
-**PR body requirements**: The PR body MUST include `Closes #<N>` (where `<N>` is
-the driving issue number) so GitHub auto-closes the issue on merge. If the PR
-closes multiple issues (e.g. duplicates consolidated), include one `Closes #<N>`
-per issue. Without this, GitHub will not auto-close the issue.
-
-**Exception**: if this PR only partially addresses the issue, use `Refs #<N>`
-or `Part of #<N>` instead of `Closes` — the issue stays open until a
-follow-up PR closes it.
-
-**Note**: substitute the real issue number for `<N>` — do not leave the
-placeholder or any `{{...}}` template tag in the committed PR body.
+The body must carry `Closes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a partial fix uses `Refs #<N>` or `Part of #<N>` instead. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
 gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF'
@@ -35,15 +23,15 @@ gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF
 
 <1-2 sentence description of the feature>
 
-Closes #<N>  <!-- Substitute <N> with the real issue number -->
+Closes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 
 ## What Changed
 
-<Brief explanation of the implementation approach>
+<the implementation approach>
 
 ## Key Decisions
 
-<Any notable decisions made during implementation, or "None — straightforward implementation">
+<notable decisions, or "None — straightforward implementation">
 
 ## Test Plan
 
@@ -53,16 +41,14 @@ Closes #<N>  <!-- Substitute <N> with the real issue number -->
 
 ## Review Notes
 
-<Anything the reviewer should pay special attention to, or "Standard implementation — no special concerns">
+<anything the reviewer should focus on, 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.
+## Optional CMAP review
 
-### 2. Optional CMAP Review
-
-If the implementation is non-trivial, run 3-way consultation:
+CMAP is your judgement call for AIR. Skip it for simple changes (config, small UI); run it for features touching core logic or several modules:
 
 ```bash
 consult -m gemini --protocol air --type pr &
@@ -70,41 +56,23 @@ 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.
+If you run it, wait for all three, record each verdict, fix real issues, and push.
 
-### 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:
+## Notify the architect
 
 ```bash
 afx send architect "PR #<number> ready for review (implements issue #{{issue.number}})"
 ```
 
-If CMAP was run, include verdicts:
-```bash
-afx send architect "PR #<number> ready for review (implements issue #{{issue.number}}). CMAP: gemini=<verdict>, codex=<verdict>, claude=<verdict>"
-```
+If you ran CMAP, include the verdicts: `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>
-```
+- PR created and ready for review:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```

package/skeleton/protocols/air/protocol.md

@@ -1,91 +1,60 @@
 # 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.
+**A**utonomous **I**mplement → **R**eview. The lightest protocol that still produces a reviewed
+PR: no spec, no plan, no artifact files. The GitHub issue *is* the specification, and the review
+lives in the PR body.
 
-## What is AIR?
+Use AIR when a small feature (roughly <300 LOC) is fully described by its issue and needs no
+architectural decision, no new abstraction, and no significant refactor. If the issue leaves the
+approach genuinely open, the cost of a spec is lower than the cost of building the wrong thing —
+use SPIR or ASPIR. For a defect rather than a feature, use BUGFIX.
 
-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.
+## The state machine
 
-### 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**
-- Architectural changes → use **SPIR**
-- Complex features with multiple phases → use **SPIR** or **ASPIR**
-
-## Baked Decisions (Optional)
+```json
+{{> protocols/air/protocol.json}}
+```
 
-When filing an issue for AIR, you can pin architectural decisions you don't want the builder or CMAP reviewers to re-litigate. Include a `## Baked Decisions` section (any heading level is fine) anywhere in the issue body. Useful categories: language, framework, deployment shape, key dependencies, decisions deferred to a later spec. The builder will treat each listed item as fixed during implementation; CMAP reviewers will not propose alternatives unless the implementation itself fails to honor a stated decision. Leave the section out for issues where you want the builder to explore freely — absence is the no-op default. You can amend or rescind a baked decision at any time by updating the issue and respawning, or by sending the builder a direct instruction via `afx send`.
+## Artifacts
 
-## Protocol Phases
+**None on disk.** The issue carries the requirements; the review goes in the PR body. That is
+the whole economy of AIR — a `codev/reviews/` file for a 200-line change costs more to maintain
+than it ever repays.
 
-### I - Implement
+## Consultation
 
-The builder reads the GitHub issue and implements the feature:
+At the builder's discretion, unlike SPIR's mandatory 3-way at every phase. Reach for it when the
+change touches shared code or you are unsure the approach is right; skip it when the issue is
+unambiguous and the diff is small.
 
-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
+## Gate
 
-If the feature grows beyond 300 LOC or requires architectural decisions, the builder signals `TOO_COMPLEX` to escalate to ASPIR.
+The `pr` gate is human. There are no pre-implementation gates — which is precisely why AIR is
+only appropriate when the issue has already settled the questions a spec would ask.
 
-### R - Review (PR)
+## Baked Decisions
 
-The builder creates a PR with the review embedded in the PR body:
+An issue may carry a `## Baked Decisions` section pinning architectural choices the architect
+does not want re-litigated — typically **language**, **framework**, deployment shape, key
+**dependencies**, or decisions deferred to a later spec.
 
-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
+Every item in it is fixed. Copy the section verbatim into the spec's Constraints and do not
+re-open it in the spec, plan, or review; CMAP reviewers will not propose alternatives unless the
+spec fails to honour one. If two items contradict each other, do not choose — surface the
+contradiction and wait.
 
-The **PR gate** is preserved — a human reviews all code before merge.
+**Absence is the no-op default**: an issue with no such section is an invitation to explore
+freely, not an omission to be filled in.
 
-## Usage
+The architect can **amend or rescind** a baked decision at any time by updating the issue and
+respawning, or by sending the builder a direct instruction via `afx send`.
 
-```bash
-# Spawn a builder using AIR
-afx spawn 42 --protocol air
+## Escalation
 
-# The builder implements autonomously and stops at the PR gate
-```
+If implementation reveals that the change is not small, or that it needs a decision the issue
+does not make, **stop and say so** rather than growing an AIR project into an unplanned SPIR.
+Escalating early is cheap; discovering it at PR review is not.
 
-## File Structure
+## Branch naming
 
-```
-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
-```
+`builder/air-<issue>-<short-description>`