@cluesmith/codev 2.0.12 → 2.0.14

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.

package/skeleton/protocols/aspir/templates/plan.md

@@ -0,0 +1,204 @@
+# Plan: [Title]
+
+## Metadata
+- **ID**: plan-[YYYY-MM-DD]-[short-name]
+- **Status**: draft
+- **Specification**: [Link to codev/specs/spec-file.md]
+- **Created**: [YYYY-MM-DD]
+
+## Executive Summary
+[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.]
+
+## Success Metrics
+[Copy from specification and add implementation-specific metrics]
+- [ ] All specification criteria met
+- [ ] Test coverage >90%
+- [ ] Performance benchmarks achieved
+- [ ] Zero critical security issues
+- [ ] Documentation complete
+
+## Phases (Machine Readable)
+
+<!-- REQUIRED: porch uses this JSON to track phase progress. Update this when adding/removing phases. -->
+
+```json
+{
+  "phases": [
+    {"id": "phase_1", "title": "Phase 1 Title Here"},
+    {"id": "phase_2", "title": "Phase 2 Title Here"},
+    {"id": "phase_3", "title": "Phase 3 Title Here"}
+  ]
+}
+```
+
+## Phase Breakdown
+
+### Phase 1: [Descriptive Name]
+**Dependencies**: None
+
+#### Objectives
+- [Clear, single objective for this phase]
+- [What value does this phase deliver?]
+
+#### Deliverables
+- [ ] [Specific deliverable 1]
+- [ ] [Specific deliverable 2]
+- [ ] [Tests for this phase]
+- [ ] [Documentation updates]
+
+#### Implementation Details
+[Specific technical approach for this phase. Include:
+- Key files/modules to create or modify
+- Architectural decisions
+- API contracts
+- Data models]
+
+#### Acceptance Criteria
+- [ ] [Testable criterion 1]
+- [ ] [Testable criterion 2]
+- [ ] All tests pass
+- [ ] Code review completed
+
+#### Test Plan
+- **Unit Tests**: [What to test]
+- **Integration Tests**: [What to test]
+- **Manual Testing**: [Scenarios to verify]
+
+#### Rollback Strategy
+[How to revert this phase if issues arise]
+
+#### Risks
+- **Risk**: [Specific risk for this phase]
+  - **Mitigation**: [How to address]
+
+---
+
+### Phase 2: [Descriptive Name]
+**Dependencies**: Phase 1
+
+[Repeat structure for each phase]
+
+---
+
+### Phase 3: [Descriptive Name]
+**Dependencies**: Phase 2
+
+[Continue for all phases]
+
+## Dependency Map
+```
+Phase 1 ──→ Phase 2 ──→ Phase 3
+             ↓
+         Phase 4 (optional)
+```
+
+## Resource Requirements
+### Development Resources
+- **Engineers**: [Expertise needed]
+- **Environment**: [Dev/staging requirements]
+
+### Infrastructure
+- [Database changes]
+- [New services]
+- [Configuration updates]
+- [Monitoring additions]
+
+## Integration Points
+### External Systems
+- **System**: [Name]
+  - **Integration Type**: [API/Database/Message Queue]
+  - **Phase**: [Which phase needs this]
+  - **Fallback**: [What if unavailable]
+
+### Internal Systems
+[Repeat structure]
+
+## Risk Analysis
+### Technical Risks
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|------------|--------|------------|-------|
+| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] |
+
+### Schedule Risks
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|------------|--------|------------|-------|
+| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] |
+
+## Validation Checkpoints
+1. **After Phase 1**: [What to validate]
+2. **After Phase 2**: [What to validate]
+3. **Before Production**: [Final checks]
+
+## Monitoring and Observability
+### Metrics to Track
+- [Metric 1: Description and threshold]
+- [Metric 2: Description and threshold]
+
+### Logging Requirements
+- [What to log and at what level]
+- [Retention requirements]
+
+### Alerting
+- [Alert condition and severity]
+- [Who to notify]
+
+## Documentation Updates Required
+- [ ] API documentation
+- [ ] Architecture diagrams
+- [ ] Runbooks
+- [ ] User guides
+- [ ] Configuration guides
+
+## Post-Implementation Tasks
+- [ ] Performance validation
+- [ ] Security audit
+- [ ] Load testing
+- [ ] User acceptance testing
+- [ ] Monitoring validation
+
+## Expert Review
+**Date**: [YYYY-MM-DD]
+**Model**: [Model consulted]
+**Key Feedback**:
+- [Feasibility assessment]
+- [Missing considerations]
+- [Risk identification]
+- [Alternative suggestions]
+
+**Plan Adjustments**:
+- [How the plan was modified based on feedback]
+
+## Approval
+- [ ] Technical Lead Review
+- [ ] Engineering Manager Approval
+- [ ] Resource Allocation Confirmed
+- [ ] Expert AI Consultation Complete
+
+## Change Log
+| Date | Change | Reason | Author |
+|------|--------|--------|--------|
+| [Date] | [What changed] | [Why] | [Who] |
+
+## Notes
+[Additional context, assumptions, or considerations]
+
+---
+
+## Amendment History
+
+This section tracks all TICK amendments to this plan. TICKs modify both the spec and plan together as an atomic unit.
+
+<!-- When adding a TICK amendment, add a new entry below this line in chronological order -->
+
+<!--
+### TICK-001: [Amendment Title] (YYYY-MM-DD)
+
+**Changes**:
+- [Phase added]: [Description of new phase]
+- [Phase modified]: [What was updated]
+- [Implementation steps]: [New steps added]
+
+**Review**: See `reviews/####-name-tick-001.md`
+
+---
+-->