@cluesmith/codev 2.0.0-rc.7 → 2.0.0-rc.71

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

@@ -0,0 +1,208 @@
+# IMPLEMENT Phase Prompt
+
+You are executing the **IMPLEMENT** phase of the SPIR protocol.
+
+## Your Goal
+
+Write clean, well-structured code AND tests that implement the current plan phase.
+
+## Context
+
+- **Project ID**: {{project_id}}
+- **Project Title**: {{title}}
+- **Current State**: {{current_state}}
+- **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}}
+
+## ⚠️ SCOPE RESTRICTION — READ THIS FIRST
+
+**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).**
+
+- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations.
+- **DO NOT** read the full plan file and implement everything you see.
+- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope.
+- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires.
+
+## What Happens After You Finish
+
+When you signal `PHASE_COMPLETE`, porch will:
+1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation
+2. Check that tests exist and pass
+3. If reviewers request changes, you'll be respawned with their feedback
+4. Once approved, porch commits and moves to the next plan phase
+
+## Spec Compliance (CRITICAL)
+
+**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
+
+### Trust Hierarchy
+
+```
+SPEC (source of truth)
+  ↓
+PLAN (implementation guide derived from spec)
+  ↓
+EXISTING CODE (NOT TRUSTED - must be validated against spec)
+```
+
+**Never trust existing code over the spec.** Previous implementations may have drifted.
+
+### Pre-Implementation Sanity Check (PISC)
+
+**Before writing ANY code:**
+
+1. ✅ "Have I read the spec in the last 30 minutes?"
+2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?"
+3. ✅ "Does my approach match the spec's Technical Implementation section?"
+4. ✅ "If the spec has code examples, am I following them?"
+5. ✅ "Does the existing code I'm building on actually match the spec?"
+
+**If ANY answer is "no" or "unsure" → STOP and re-read the spec.**
+
+### Avoiding "Fixing Mode"
+
+A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to:
+- Cargo-culting patterns that may be wrong
+- Building on broken foundations
+- Implementing something different from the spec
+
+**When you catch yourself "fixing" code:**
+1. STOP
+2. Ask: "What does the spec say about this?"
+3. Re-read the spec's Traps to Avoid section
+4. Verify existing code matches the spec before building on it
+
+## Prerequisites
+
+Before implementing, verify:
+1. Previous phase (if any) is committed to git
+2. You've read the plan phase you're implementing
+3. You understand the success criteria for this phase
+4. Dependencies from earlier phases are available
+
+## Process
+
+### 1. Review the Plan Phase
+
+Read the current phase in the plan:
+- What is the objective?
+- What files need to be created/modified?
+- What are the success criteria?
+- What dependencies exist?
+
+### 2. Set Up
+
+- Verify you're on the correct branch
+- Check that previous phase is committed: `git log --oneline -5`
+- Ensure build passes before starting: `npm run build` (or equivalent)
+
+### 3. Implement the Code
+
+Write the code following these principles:
+
+**Code Quality Standards**:
+- Self-documenting code (clear names, obvious structure)
+- No commented-out code
+- No debug prints in final code
+- Explicit error handling
+- Follow project style guide
+
+**Implementation Approach**:
+- Work on one file at a time
+- Make small, incremental changes
+- Document complex logic with comments
+
+### 4. Write Tests
+
+**Tests are required.** For each piece of functionality you implement:
+
+- Write unit tests for core logic
+- Write integration tests if the phase involves multiple components
+- Test error cases and edge conditions
+- Ensure tests are deterministic (no flaky tests)
+
+**Test file locations** (follow project conventions):
+- `tests/` or `__tests__/` directories
+- `*.test.ts` or `*.spec.ts` naming
+
+### 5. Verify Everything Works
+
+Run both build and tests:
+
+```bash
+npm run build      # Must pass
+npm test           # Must pass
+```
+
+**Important**: Don't assume these commands exist. Check `package.json` first.
+
+Fix any errors before signaling completion.
+
+### 6. Self-Review
+
+Before signaling completion:
+- Read through all code changes
+- Read through all test changes
+- Verify code matches the spec requirements
+- Ensure no accidental debug code
+- Check test coverage is adequate
+
+## Output
+
+When complete, you should have:
+- Modified/created source files as specified in the plan phase
+- Tests covering the new functionality
+- All build checks passing
+- All tests passing
+
+## Signals
+
+When implementation AND tests are complete and passing:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you encounter a blocker:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```
+
+If you need spec/plan clarification:
+
+```
+<signal type=AWAITING_INPUT>
+Your specific questions here
+</signal>
+```
+
+## Important Notes
+
+1. **Follow the plan** - Implement what's specified, not more
+2. **Don't over-engineer** - Simplest solution that works
+3. **Don't skip error handling** - But don't go overboard either
+4. **Keep changes focused** - Only touch files in this phase
+5. **Build AND tests must pass** - Don't signal complete until both pass
+6. **Write tests** - Every implementation phase needs tests
+
+## What NOT to Do
+
+- Don't modify files outside this phase's scope
+- Don't add features not in the spec
+- Don't leave TODO comments for later (fix now or note as blocker)
+- Don't skip writing tests
+- Don't use `git add .` or `git add -A` when you commit (security risk)
+
+## Handling Problems
+
+**If the plan is unclear**:
+Signal `AWAITING_INPUT` with your specific question.
+
+**If you discover the spec is wrong**:
+Signal `BLOCKED` and explain the issue. The Architect may need to update the spec.
+
+**If a dependency is missing**:
+Signal `BLOCKED` with details about what's missing.
+
+**If build or tests fail and you can't fix it**:
+Signal `BLOCKED` with the error message.

package/skeleton/protocols/{spider → spir}/prompts/plan.md

@@ -1,6 +1,6 @@
 # PLAN Phase Prompt
 
-You are executing the **PLAN** phase of the SPIDER protocol.
+You are executing the **PLAN** phase of the SPIR protocol.
 
 ## Your Goal
 
@@ -14,10 +14,6 @@ Transform the approved specification into an executable implementation plan with
 - **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
 - **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
 
-## CRITICAL: Multi-Agent Consultation is MANDATORY
-
-The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
-
 ## Prerequisites
 
 Before planning, verify:
@@ -72,51 +68,15 @@ Phase 3: API Endpoints (depends on Phase 2)
 Phase 4: Frontend Integration (depends on Phase 3)
 ```
 
-### 5. MANDATORY: First Consultation (After Draft)
-
-After completing the initial plan draft:
-
-```bash
-# Run consultations in parallel (REQUIRED)
-consult --model gemini plan {{project_id}} &
-consult --model codex plan {{project_id}} &
-wait
-```
-
-- Review ALL feedback from both models
-- Update the plan with incorporated feedback
-- Add a **Consultation Log** section documenting:
-  - Key feedback received
-  - Changes made in response
-  - Any feedback intentionally not incorporated (with reasoning)
-
-### 6. Human Review
-
-After consultation feedback is incorporated:
-- Present the plan for human review
-- Wait for approval or change requests
-- If changes requested, make them and proceed to Step 7
-
-### 7. MANDATORY: Second Consultation (After Human Feedback)
-
-After incorporating human feedback:
+### 5. Finalize
 
-```bash
-# Run consultations again (REQUIRED)
-consult --model gemini plan {{project_id}} &
-consult --model codex plan {{project_id}} &
-wait
-```
-
-- Update Consultation Log with new feedback
-- Incorporate changes
-- Prepare final plan for approval
+After completing the plan 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 the plan file at `codev/plans/{{project_id}}-{{title}}.md`.
 
-Use the plan template from `codev/protocols/spider/templates/plan.md` if available.
+Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
 
 ### Plan Structure
 
@@ -148,18 +108,6 @@ Brief summary of what will be implemented.
 - [Risk 1]: [Mitigation]
 - [Risk 2]: [Mitigation]
 
-## Consultation Log
-
-### First Consultation (After Draft)
-- **Gemini Feedback**: [Summary]
-- **Codex Feedback**: [Summary]
-- **Changes Made**: [List]
-- **Not Incorporated**: [List with reasons]
-
-### Second Consultation (After Human Feedback)
-- **Gemini Feedback**: [Summary]
-- **Codex Feedback**: [Summary]
-- **Changes Made**: [List]
 ```
 
 ## Signals
@@ -171,16 +119,6 @@ Emit appropriate signals based on your progress:
   <signal>PLAN_DRAFTED</signal>
   ```
 
-- After incorporating consultation feedback:
-  ```
-  <signal>CONSULTATION_INCORPORATED</signal>
-  ```
-
-- After final plan is ready for human approval:
-  ```
-  <signal>PLAN_READY_FOR_APPROVAL</signal>
-  ```
-
 ## Commit Cadence
 
 Make commits at these milestones:
@@ -196,16 +134,14 @@ git add codev/plans/{{project_id}}-{{title}}.md
 
 ## Important Notes
 
-1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
-2. **No time estimates** - Don't include hours/days/weeks
+1. **No time estimates** - Don't include hours/days/weeks
 3. **Be specific about files** - Exact paths, not "the config file"
 4. **Keep phases small** - 1-3 files per phase is ideal
 5. **Document dependencies clearly** - Prevents blocked work
-6. **Document consultations** - Maintain the Consultation Log section
 
 ## What NOT to Do
 
-- Don't skip consultations (they are BLOCKING)
+- Don't run `consult` commands yourself (porch handles consultations)
 - Don't write code (that's for Implement phase)
 - Don't estimate time (meaningless in AI development)
 - Don't create phases that can't be independently tested

package/skeleton/protocols/{spider → spir}/prompts/review.md

@@ -1,14 +1,10 @@
 # REVIEW Phase Prompt
 
-You are executing the **REVIEW** phase of the SPIDER protocol.
+You are executing the **REVIEW** phase of the SPIR protocol.
 
 ## Your Goal
 
-Perform a comprehensive review, document lessons learned, run final consultation, and prepare for PR submission.
-
-## CRITICAL: Final Consultation Before PR
-
-The SPIDER protocol **requires** a final consultation with GPT-5 Codex AND Gemini Pro before submitting the PR. This ensures the complete implementation is reviewed.
+Perform a comprehensive review, document lessons learned, and prepare for PR submission.
 
 ## Context
 
@@ -92,7 +88,7 @@ Brief description of what was implemented.
 - [Insight 2]
 
 ### Methodology Improvements
-- [Suggested improvement to SPIDER protocol]
+- [Suggested improvement to SPIR protocol]
 - [Suggested improvement to tooling]
 
 ## Technical Debt
@@ -118,29 +114,14 @@ Before PR:
 - [ ] No uncommitted changes: `git status`
 - [ ] Review document complete
 
-### 6. MANDATORY: Final Consultation (PR-Ready Review)
+### 6. Create Pull Request
 
-**Before creating the PR, run final consultation:**
+**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-ready gate fires.
 
 ```bash
-# Run consultations in parallel (REQUIRED)
-consult --model gemini --type pr-ready spec {{project_id}} &
-consult --model codex --type pr-ready spec {{project_id}} &
-wait
-```
-
-- Review ALL feedback from both models
-- Address any final issues identified
-- This is the last chance to catch problems before PR
-
-### 7. Create Pull Request
-
-Prepare PR with:
-
-**Title**: `[Spec {{project_id}}] {{title}}`
-
-**Body**:
-```markdown
+gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 ## Summary
 [Brief description of the implementation]
 
@@ -158,37 +139,37 @@ Link: codev/specs/{{project_id}}-{{title}}.md
 
 ## Review
 Link: codev/reviews/{{project_id}}-{{title}}.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/{{project_id}}-{{title}}.md`
 - Updated documentation (if needed)
-- Pull request ready for submission
+- Pull request created and ready for review
 
 ## Signals
 
-Emit appropriate signals based on your progress:
-
 - After review document is complete:
   ```
   <signal>REVIEW_COMPLETE</signal>
   ```
 
-- After PR is created:
-  ```
-  <signal>PR_CREATED</signal>
-  ```
-
-- When ready for Architect review:
+- After PR is created — signal completion so porch runs consultation:
   ```
   <signal>PR_READY</signal>
   ```
 
 ## Important Notes
 
-1. **Final consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews before PR
-2. **Be honest in lessons learned** - Future you will thank present you
+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
@@ -196,7 +177,7 @@ Emit appropriate signals based on your progress:
 
 ## What NOT to Do
 
-- Don't skip final consultation (it's BLOCKING)
+- 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

package/skeleton/protocols/{spider → spir}/prompts/specify.md

@@ -1,6 +1,6 @@
 # SPECIFY Phase Prompt
 
-You are executing the **SPECIFY** phase of the SPIDER protocol.
+You are executing the **SPECIFY** phase of the SPIR protocol.
 
 ## Your Goal
 
@@ -13,13 +13,25 @@ Create a comprehensive specification document that thoroughly explores the probl
 - **Current State**: {{current_state}}
 - **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
 
-## CRITICAL: Multi-Agent Consultation is MANDATORY
+## Process
 
-The SPIDER protocol **requires** consultation with GPT-5 Codex AND Gemini Pro at specific checkpoints. This is BLOCKING - you cannot proceed without completing consultations.
+### 0. Check for Existing Spec (ALWAYS DO THIS FIRST)
 
-## Process
+**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 (ALWAYS START HERE)
+### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS)
 
 Before writing anything, ask clarifying questions to understand:
 - What problem is being solved?
@@ -28,7 +40,9 @@ Before writing anything, ask clarifying questions to understand:
 - What's in scope vs out of scope?
 - What does success look like?
 
-If this is your first iteration, ask these questions now and wait for answers.
+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.
 
@@ -62,45 +76,9 @@ Define measurable acceptance criteria:
 - Non-functional requirements (performance, security)
 - Test scenarios
 
-### 6. MANDATORY: First Consultation (After Draft)
-
-After completing the initial spec draft:
-
-```bash
-# Run consultations in parallel (REQUIRED)
-consult --model gemini spec {{project_id}} &
-consult --model codex spec {{project_id}} &
-wait
-```
-
-- Review ALL feedback from both models
-- Update the spec with incorporated feedback
-- Add a **Consultation Log** section documenting:
-  - Key feedback received
-  - Changes made in response
-  - Any feedback intentionally not incorporated (with reasoning)
-
-### 7. Human Review
+### 6. Finalize
 
-After consultation feedback is incorporated:
-- Present the spec for human review
-- Wait for approval or change requests
-- If changes requested, make them and proceed to Step 8
-
-### 8. MANDATORY: Second Consultation (After Human Feedback)
-
-After incorporating human feedback:
-
-```bash
-# Run consultations again (REQUIRED)
-consult --model gemini spec {{project_id}} &
-consult --model codex spec {{project_id}} &
-wait
-```
-
-- Update Consultation Log with new feedback
-- Incorporate changes
-- Prepare final spec for approval
+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
 
@@ -111,31 +89,27 @@ Create or update the specification file at `codev/specs/{{project_id}}-{{title}}
 - Plan: `codev/plans/{{project_id}}-{{title}}.md`
 - Review: `codev/reviews/{{project_id}}-{{title}}.md`
 
-Include a **Consultation Log** section in the spec documenting all consultation feedback.
-
 ## Signals
 
 Emit appropriate signals based on your progress:
 
-- When waiting for clarifying question answers:
+- When waiting for clarifying question answers, **include your questions in the signal**:
   ```
-  <signal>AWAITING_INPUT</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>
   ```
 
-- After incorporating consultation feedback:
-  ```
-  <signal>CONSULTATION_INCORPORATED</signal>
-  ```
-
-- After final spec is ready for human approval:
-  ```
-  <signal>SPEC_READY_FOR_APPROVAL</signal>
-  ```
 
 ## Commit Cadence
 
@@ -152,15 +126,13 @@ git add codev/specs/{{project_id}}-{{title}}.md
 
 ## Important Notes
 
-1. **Consultation is MANDATORY** - Cannot skip GPT-5 + Gemini reviews
-2. **Be thorough** - A good spec prevents implementation problems
+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
-5. **Document consultations** - Maintain the Consultation Log section
 
 ## What NOT to Do
 
-- Don't skip consultations (they are BLOCKING)
+- 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)