@cluesmith/codev 2.0.11 → 2.0.13

package/skeleton/protocols/aspir/prompts/review.md

@@ -0,0 +1,259 @@
+# REVIEW Phase Prompt
+
+You are executing the **REVIEW** phase of the SPIR protocol.
+
+## Your Goal
+
+Perform a comprehensive review, document lessons learned, and prepare for PR submission.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
+- **Review File**: `codev/reviews/{{artifact_name}}.md`
+
+## Prerequisites
+
+Before review, verify:
+1. All implementation phases are committed
+2. All tests are passing
+3. Build is passing
+4. Spec compliance verified for all phases
+
+Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"`
+
+## Process
+
+### 1. Comprehensive Review
+
+Review the entire implementation:
+
+**Code Quality**:
+- Is the code readable and maintainable?
+- Are there any code smells?
+- Is error handling consistent?
+- Are there any security concerns?
+
+**Architecture**:
+- Does the implementation fit well with existing code?
+- Are there any architectural concerns?
+- Is the design scalable if needed?
+
+**Documentation**:
+- Is code adequately commented where needed?
+- Are public APIs documented?
+- Is README updated if needed?
+
+### 2. Spec Comparison
+
+Compare final implementation to original specification:
+
+- What was delivered vs what was specified?
+- Any deviations? Document why.
+- All success criteria met?
+
+### 3. Create Review Document
+
+Create `codev/reviews/{{artifact_name}}.md`:
+
+```markdown
+# Review: {{title}}
+
+## Summary
+Brief description of what was implemented.
+
+## Spec Compliance
+- [x] Requirement 1: Implemented as specified
+- [x] Requirement 2: Implemented with deviation (see below)
+- [x] Requirement 3: Implemented as specified
+
+## Deviations from Plan
+- **Phase X**: [What changed and why]
+
+## Lessons Learned
+
+### What Went Well
+- [Positive observation 1]
+- [Positive observation 2]
+
+### Challenges Encountered
+- [Challenge 1]: [How it was resolved]
+- [Challenge 2]: [How it was resolved]
+
+### What Would Be Done Differently
+- [Insight 1]
+- [Insight 2]
+
+### Methodology Improvements
+- [Suggested improvement to SPIR protocol]
+- [Suggested improvement to tooling]
+
+## Technical Debt
+- [Any shortcuts taken that should be addressed later]
+
+## Consultation Feedback
+
+[See instructions below]
+
+## Flaky Tests
+- [Any pre-existing tests that were skipped as flaky during this project]
+- [Include test name, file path, and observed failure mode]
+- [If none: "No flaky tests encountered"]
+
+## Follow-up Items
+- [Any items identified for future work]
+```
+
+### 3b. Include Consultation Feedback
+
+**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded.
+
+Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model:
+
+```markdown
+## Consultation Feedback
+
+### Specify Phase (Round 1)
+
+#### Gemini
+- **Concern**: [Summary of the concern]
+  - **Addressed**: [What was changed to resolve it]
+
+#### Codex
+- **Concern**: [Summary]
+  - **Rebutted**: [Why the current approach is correct]
+
+#### Claude
+- No concerns raised (APPROVE)
+
+### Plan Phase (Round 1)
+...
+```
+
+**Response types** — each concern gets exactly one:
+- **Addressed**: Builder made a change to resolve the concern
+- **Rebutted**: Builder explains why the concern doesn't apply
+- **N/A**: Concern is out of scope, already handled elsewhere, or moot
+
+**Edge cases**:
+- If all reviewers approved with no concerns: "No concerns raised — all consultations approved"
+- For COMMENT verdicts: include their feedback (non-blocking but useful context)
+- For CONSULT_ERROR (model failure): note "Consultation failed for [model]"
+- If a phase had multiple rounds, give each round its own subsection
+
+### 4. Update Architecture and Lessons Learned Documentation
+
+**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing.
+
+**Architecture Updates** (`codev/resources/arch.md`):
+1. Read the current `codev/resources/arch.md`
+2. Determine if this project introduced architectural changes worth documenting (new subsystems, data flows, design decisions, invariants, file locations)
+3. If yes: make the updates to arch.md and describe what you changed in the `## Architecture Updates` section of the review
+4. If no: write "No architecture updates needed" in the section with a brief explanation (e.g., "This was a template-only change with no new subsystems or data flows")
+
+**Lessons Learned Updates** (`codev/resources/lessons-learned.md`):
+1. Read the current `codev/resources/lessons-learned.md`
+2. Determine if this project produced generalizable lessons (patterns, anti-patterns, debugging insights, process improvements)
+3. If yes: add entries to lessons-learned.md and describe what you added in the `## Lessons Learned Updates` section of the review
+4. If no: write "No lessons learned updates needed" in the section with a brief explanation (e.g., "Straightforward implementation with no novel insights beyond existing entries")
+
+### 4b. Update Other Documentation
+
+If needed, also update:
+- README.md (new features, changed behavior)
+- API documentation
+
+### 5. Final Verification
+
+Before PR:
+- [ ] All tests pass (use project-specific test command)
+- [ ] Build passes (use project-specific build command)
+- [ ] Lint passes (if configured)
+- [ ] No uncommitted changes: `git status`
+- [ ] Review document complete
+
+### 6. Create Pull Request
+
+**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that
+porch consultation reviews the actual PR, and the architect can review a real PR
+when the pr gate fires.
+
+```bash
+gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
+## Summary
+[Brief description of the implementation]
+
+## Changes
+- [Change 1]
+- [Change 2]
+
+## Testing
+- All unit tests passing
+- Integration tests added for [X]
+- Manual testing completed for [Y]
+
+## Spec
+Link: codev/specs/{{artifact_name}}.md
+
+## Review
+Link: codev/reviews/{{artifact_name}}.md
+EOF
+)"
+```
+
+### 7. Signal Completion
+
+After the PR is created, signal completion. Porch will run 3-way consultation
+(Gemini, Codex, Claude) automatically via the verify step. If reviewers request
+changes, you'll be respawned with their feedback.
+
+## Output
+
+- Review document at `codev/reviews/{{artifact_name}}.md`
+- Updated documentation (if needed)
+- Pull request created and ready for review
+
+## Signals
+
+- After review document is complete:
+  ```
+  <signal>REVIEW_COMPLETE</signal>
+  ```
+
+- After PR is created — signal completion so porch runs consultation:
+  ```
+  <signal>PR_READY</signal>
+  ```
+
+## Important Notes
+
+1. **Be honest in lessons learned** - Future you will thank present you
+3. **Document deviations** - They're not failures, they're learnings
+4. **Update methodology** - If you found a better way, document it
+5. **Don't skip the checklist** - It catches last-minute issues
+6. **Clean PR description** - Makes review easier
+
+## What NOT to Do
+
+- Don't run `consult` commands yourself (porch handles consultations)
+- Don't skip lessons learned ("nothing to report")
+- Don't merge your own PR (Architect handles integration)
+- Don't leave uncommitted changes
+- Don't forget to update documentation
+- Don't rush this phase - it's valuable for learning
+- Don't use `git add .` or `git add -A` (security risk)
+
+## Review Prompts for Reflection
+
+Ask yourself:
+- What surprised me during implementation?
+- Where did I spend the most time? Was it avoidable?
+- What would have helped me go faster?
+- Did the spec adequately describe what was needed?
+- Did the plan phases make sense in hindsight?
+- What tests caught issues? What tests were unnecessary?
+
+Capture these reflections in the lessons learned section.

package/skeleton/protocols/aspir/prompts/specify.md

@@ -0,0 +1,139 @@
+# SPECIFY Phase Prompt
+
+You are executing the **SPECIFY** phase of the SPIR protocol.
+
+## Your Goal
+
+Create a comprehensive specification document that thoroughly explores the problem space and proposed solution.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+
+## Process
+
+### 0. Check for Existing Spec (ALWAYS DO THIS FIRST)
+
+**Before asking ANY questions**, check if a spec already exists:
+
+```bash
+ls codev/specs/{{project_id}}-*.md
+```
+
+**If a spec file exists:**
+1. READ IT COMPLETELY - the answers to your questions are already there
+2. The spec author has already made the key decisions
+3. DO NOT ask clarifying questions - proceed directly to consultation
+4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch
+
+**If no spec exists:** Proceed to Step 1 below.
+
+### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
+
+Before writing anything, ask clarifying questions to understand:
+- What problem is being solved?
+- Who are the stakeholders?
+- What are the constraints?
+- What's in scope vs out of scope?
+- What does success look like?
+
+If this is your first iteration AND no spec exists, ask these questions now and wait for answers.
+
+**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer.
+
+**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step.
+
+### 2. Problem Analysis
+
+Once you have answers, document:
+- The problem being solved (clearly articulated)
+- Current state vs desired state
+- Stakeholders and their needs
+- Assumptions and constraints
+
+### 3. Solution Exploration
+
+Generate multiple solution approaches. For each:
+- Technical design overview
+- Trade-offs (pros/cons)
+- Complexity assessment
+- Risk assessment
+
+### 4. Open Questions
+
+List uncertainties categorized as:
+- **Critical** - blocks progress
+- **Important** - affects design
+- **Nice-to-know** - optimization
+
+### 5. Success Criteria
+
+Define measurable acceptance criteria:
+- Functional requirements (MUST, SHOULD, COULD)
+- Non-functional requirements (performance, security)
+- Test scenarios
+
+### 6. Finalize
+
+After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback.
+
+## Output
+
+Create or update the specification file at `codev/specs/{{artifact_name}}.md`.
+
+**IMPORTANT**: Keep spec/plan/review filenames in sync:
+- Spec: `codev/specs/{{artifact_name}}.md`
+- Plan: `codev/plans/{{artifact_name}}.md`
+- Review: `codev/reviews/{{artifact_name}}.md`
+
+## Signals
+
+Emit appropriate signals based on your progress:
+
+- When waiting for clarifying question answers, **include your questions in the signal**:
+  ```
+  <signal type=AWAITING_INPUT>
+  Please answer these questions:
+  1. What should the primary use case be - internal tooling or customer-facing?
+  2. What are the key constraints we should consider?
+  3. Who are the main stakeholders?
+  </signal>
+  ```
+
+  The content inside the signal tag is displayed prominently to the user.
+
+- After completing the initial spec draft:
+  ```
+  <signal>SPEC_DRAFTED</signal>
+  ```
+
+
+## Commit Cadence
+
+Make commits at these milestones:
+1. `[Spec {{project_id}}] Initial specification draft`
+2. `[Spec {{project_id}}] Specification with multi-agent review`
+3. `[Spec {{project_id}}] Specification with user feedback`
+4. `[Spec {{project_id}}] Final approved specification`
+
+**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
+```bash
+git add codev/specs/{{artifact_name}}.md
+```
+
+## Important Notes
+
+1. **Be thorough** - A good spec prevents implementation problems
+3. **Be specific** - Vague specs lead to wrong implementations
+4. **Include examples** - Concrete examples clarify intent
+
+## What NOT to Do
+
+- Don't run `consult` commands yourself (porch handles consultations)
+- Don't include implementation details (that's for the Plan phase)
+- Don't estimate time (AI makes time estimates meaningless)
+- Don't start coding (you're in Specify, not Implement)
+- Don't use `git add .` or `git add -A` (security risk)

package/skeleton/protocols/aspir/protocol.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "aspir",
+  "version": "1.0.0",
+  "description": "ASPIR: Autonomous SPIR — Specify → Plan → Implement → Review without human approval gates",
+  "input": {
+    "type": "spec",
+    "required": false,
+    "default_for": ["--project", "-p"]
+  },
+  "phases": [
+    {
+      "id": "specify",
+      "name": "Specify",
+      "description": "Write specification with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "specify.md",
+        "artifact": "codev/specs/${PROJECT_TITLE}.md"
+      },
+      "verify": {
+        "type": "spec",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "next": "plan"
+    },
+    {
+      "id": "plan",
+      "name": "Plan",
+      "description": "Write implementation plan with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "plan.md",
+        "artifact": "codev/plans/${PROJECT_TITLE}.md"
+      },
+      "verify": {
+        "type": "plan",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md",
+        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md",
+        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
+      },
+      "next": "implement"
+    },
+    {
+      "id": "implement",
+      "name": "Implement",
+      "description": "Implement code with 3-way review per plan phase",
+      "type": "per_plan_phase",
+      "build": {
+        "prompt": "implement.md",
+        "artifact": "src/**/*.{ts,tsx,js,jsx}"
+      },
+      "verify": {
+        "type": "impl",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "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 review phase",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "transition": {
+        "on_complete": "implement",
+        "on_all_phases_complete": "review"
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "description": "Final review and PR with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "review.md",
+        "artifact": "codev/reviews/${PROJECT_TITLE}.md"
+      },
+      "verify": {
+        "type": "pr",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 1,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "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"
+        },
+        "review_has_arch_updates": {
+          "command": "grep -q '## Architecture Updates' codev/reviews/${PROJECT_TITLE}.md",
+          "description": "Review must include '## Architecture Updates' section (what changed in arch.md, or why no changes needed)"
+        },
+        "review_has_lessons_updates": {
+          "command": "grep -q '## Lessons Learned Updates' codev/reviews/${PROJECT_TITLE}.md",
+          "description": "Review must include '## Lessons Learned Updates' section (what changed in lessons-learned.md, or why no changes needed)"
+        },
+        "e2e_tests": {
+          "command": "npm run test:e2e 2>&1 || echo 'e2e tests skipped (not configured)'",
+          "description": "Full e2e test suite - only runs in review phase",
+          "optional": true
+        }
+      },
+      "gate": "pr",
+      "next": null
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current build phase is complete",
+      "transitions_to": "verify"
+    },
+    "BLOCKED": {
+      "description": "Signal implementation is blocked",
+      "requires": "reason"
+    }
+  },
+  "phase_completion": {
+    "build_succeeds": "npm run build 2>&1",
+    "tests_pass": "npm test 2>&1",
+    "commit_has_code": "git log -1 --name-only --pretty=format: | grep -qE '\\.(ts|tsx|js|jsx|py|go|rs)$'"
+  },
+  "defaults": {
+    "mode": "strict",
+    "max_iterations": 1,
+    "verify": {
+      "models": ["gemini", "codex", "claude"],
+      "parallel": true
+    }
+  }
+}

package/skeleton/protocols/aspir/protocol.md

@@ -0,0 +1,94 @@
+# ASPIR Protocol
+
+> **ASPIR** = **A**utonomous **S**pecify → **P**lan → **I**mplement → **R**eview
+>
+> Identical to SPIR but without human approval gates on spec and plan phases.
+> Each phase has one build-verify cycle with 3-way consultation.
+
+## What is ASPIR?
+
+ASPIR is an autonomous variant of the SPIR protocol. It follows the exact same phases (Specify → Plan → Implement → Review) with the same 3-way consultations, checks, and PR flow — but removes the `spec-approval` and `plan-approval` human gates.
+
+This means the builder proceeds automatically from Specify → Plan → Implement without waiting for human approval at each gate. The `pr` gate in the Review phase is preserved — a human still reviews all code before merge.
+
+### Differences from SPIR
+
+| Aspect | SPIR | ASPIR |
+|--------|------|-------|
+| Spec gate (`spec-approval`) | Human must approve | Auto-approved |
+| Plan gate (`plan-approval`) | Human must approve | Auto-approved |
+| PR gate (`pr`) | Human must approve | Human must approve |
+| Phases | Specify → Plan → Implement → Review | Same |
+| 3-way consultations | Yes, every phase | Same |
+| Checks (build, tests, PR) | Yes | Same |
+| Prompts / templates | Full set | Same (copied from SPIR) |
+
+### When to Use ASPIR
+
+Use ASPIR instead of SPIR when:
+
+- The work is **trusted and low-risk** — internal tooling, protocol additions, well-understood features
+- The architect has **pre-written and approved** the spec before spawning
+- The scope is **self-contained** with low blast radius
+- You want **full SPIR discipline** (consultations, phased implementation, review) without waiting at gates
+
+### When NOT to Use ASPIR
+
+Use SPIR instead when:
+
+- The feature involves **novel architecture** or unclear requirements
+- The spec needs **iterative human feedback** during drafting
+- The work is **high-risk** — security-sensitive, user-facing, or broadly impactful
+- You want to **review and adjust** the plan before implementation starts
+
+## Protocol Phases
+
+ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md).
+
+### S - Specify
+Write specification with 3-way review (Gemini, Codex, Claude). **No human gate** — proceeds directly to Plan after verification.
+
+### P - Plan
+Write implementation plan with 3-way review. **No human gate** — proceeds directly to Implement after verification and checks pass.
+
+### I - Implement
+Execute each plan phase with build-verify cycle. Same as SPIR — no gate between phases (SPIR also has no gate here).
+
+### R - Review
+Final review, PR preparation, and 3-way review. **PR gate preserved** — builder stops and waits for human approval before merge.
+
+## Usage
+
+```bash
+# Spawn a builder using ASPIR
+af spawn 42 --protocol aspir
+
+# The builder runs autonomously through Specify → Plan → Implement
+# and stops only at the PR gate in the Review phase
+```
+
+## File Structure
+
+```
+codev/protocols/aspir/
+├── protocol.json          # Protocol definition (SPIR minus gates)
+├── protocol.md            # This file
+├── builder-prompt.md      # Builder instructions (same as SPIR)
+├── prompts/
+│   ├── specify.md         # Specify phase prompt (same as SPIR)
+│   ├── plan.md            # Plan phase prompt (same as SPIR)
+│   ├── implement.md       # Implement phase prompt (same as SPIR)
+│   └── review.md          # Review phase prompt (same as SPIR)
+├── consult-types/
+│   ├── spec-review.md     # Spec consultation guide (same as SPIR)
+│   ├── plan-review.md     # Plan consultation guide (same as SPIR)
+│   ├── impl-review.md     # Impl consultation guide (same as SPIR)
+│   ├── phase-review.md    # Phase consultation guide (same as SPIR)
+│   └── pr-review.md       # PR consultation guide (same as SPIR)
+└── templates/
+    ├── spec.md            # Spec template (same as SPIR)
+    ├── plan.md            # Plan template (same as SPIR)
+    └── review.md          # Review template (same as SPIR)
+```
+
+All files except `protocol.json` and `protocol.md` are identical to their SPIR counterparts.