@cluesmith/codev 3.2.4 → 3.3.0

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

@@ -1,10 +1,10 @@
 # IMPLEMENT Phase Prompt
 
-You are executing the **IMPLEMENT** phase of the SPIR protocol.
+You are executing the **IMPLEMENT** phase of the ASPIR protocol.
 
-## Your Goal
+## Goal
 
-Write clean, well-structured code AND tests that implement the current plan phase.
+Implement the current plan phase — code and tests — so it matches the spec and passes build and tests.
 
 ## Context
 
@@ -13,203 +13,34 @@ Write clean, well-structured code AND tests that implement the current plan phas
 - **Current State**: {{current_state}}
 - **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}}
 
-## ⚠️ SCOPE RESTRICTION — READ THIS FIRST
+## Scope: this phase only
 
-**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).**
+Your scope is exactly `{{plan_phase_id}}` ({{plan_phase_title}}), whose details are included below under "Current Plan Phase Details". Other phases are handled in later porch iterations — do not implement them, and do not read the full plan and build everything you see. Read `codev/specs/{{project_id}}-*.md` for requirements, but implement only what this phase requires.
 
-- **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.
+When you signal `PHASE_COMPLETE`, porch runs the 3-way consultation, checks that tests exist and pass, and either respawns you with feedback or commits and moves to the next phase.
 
-## What Happens After You Finish
+## What must be true when 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
+- **The implementation matches the spec.** The spec is the source of truth; the plan derives from it; existing code is not trusted until validated against the spec, because earlier work may have drifted. Code that "works" but diverges from the spec is wrong. When you notice yourself patching symptoms in existing code, stop and re-check what the spec actually requires before building further.
+- **Tests exist and are meaningful.** Unit tests for the core logic, integration tests where the phase spans components, and coverage of error and edge cases. Tests are deterministic. Follow the project's existing test locations and naming.
+- **Build and tests pass.** Confirm the actual project commands (check `package.json` rather than assuming `npm run build` / `npm test` exist) and run them; fix failures before signaling.
+- **The change is clean.** Self-documenting names, explicit error handling, no commented-out or debug code, only the files this phase touches — the simplest solution that satisfies the phase, not more.
 
 ## 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.
-
-**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes):
-1. **DO NOT** edit `status.yaml` to bypass checks
-2. **DO NOT** skip porch checks or use workarounds to avoid the failure
-3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`)
-4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up
-5. Commit the skip and continue with your work
+- Implementation and tests complete and passing:
+  ```
+  <signal>PHASE_COMPLETE</signal>
+  ```
+- Blocked — the plan is wrong, the spec is wrong, a dependency is missing, or build/tests fail in a way you cannot resolve:
+  ```
+  <signal>BLOCKED:reason goes here</signal>
+  ```
+- Need spec/plan clarification:
+  ```
+  <signal type=AWAITING_INPUT>
+  Your specific questions here
+  </signal>
+  ```
+
+A blocker is a signal, not a silent workaround: never edit `status.yaml` or bypass a porch check to force a green.

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

@@ -1,10 +1,10 @@
 # PLAN Phase Prompt
 
-You are executing the **PLAN** phase of the SPIR protocol.
+You are executing the **PLAN** phase of the ASPIR protocol.
 
-## Your Goal
+## Goal
 
-Transform the approved specification into an executable implementation plan with clear phases.
+Turn the approved spec into an executable plan at `codev/plans/{{artifact_name}}.md`: a phase breakdown a builder can implement one phase at a time.
 
 ## Context
 
@@ -14,105 +14,41 @@ Transform the approved specification into an executable implementation plan with
 - **Spec File**: `codev/specs/{{artifact_name}}.md`
 - **Plan File**: `codev/plans/{{artifact_name}}.md`
 
-## Prerequisites
+## What must be true when you finish
 
-Before planning, verify:
-1. The specification exists and has been approved
-2. You've read and understood the entire spec
-3. Success criteria are clear and measurable
+- **The plan derives from the spec.** You have read the whole spec — its functional and non-functional requirements, constraints, and success criteria — and the plan validates against them.
+- **The work is decomposed into phases, each of which is:**
+  - **self-contained** — a complete unit of functionality;
+  - **independently testable** — verifiable on its own;
+  - **valuable** — delivers observable progress;
+  - **committable** — a single atomic commit.
 
-## Process
-
-### 1. Analyze the Specification
-
-Read the spec thoroughly. Identify:
-- All functional requirements
-- Non-functional requirements
-- Dependencies and constraints
-- Success criteria to validate against
-
-### 2. Identify Implementation Phases
-
-Break the work into logical phases. Each phase should be:
-- **Self-contained** - A complete unit of functionality
-- **Independently testable** - Can be verified on its own
-- **Valuable** - Delivers observable progress
-- **Committable** - Can be a single atomic commit
-
-Good phase examples:
-- "Database Schema" - Creates all tables/migrations
-- "Core API Endpoints" - Implements main REST routes
-- "Authentication Flow" - Handles login/logout/session
-
-Bad phase examples:
-- "Setup" - Too vague
-- "Part 1" - Not descriptive
-- "Everything" - Not broken down
-
-### 3. Define Each Phase
-
-For each phase, document:
-- **Objective** - Single clear goal
-- **Files to modify/create** - Specific paths
-- **Dependencies** - Which phases must complete first
-- **Success criteria** - How to know it's done
-- **Test approach** - What tests will verify it
-
-### 4. Order Phases by Dependencies
-
-Arrange phases so dependencies are satisfied:
-```
-Phase 1: Database Schema (no dependencies)
-Phase 2: Data Models (depends on Phase 1)
-Phase 3: API Endpoints (depends on Phase 2)
-Phase 4: Frontend Integration (depends on Phase 3)
-```
-
-### 5. Finalize
-
-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.
+  A phase name states what it delivers ("Database schema", "Authentication flow"), not a position ("Setup", "Part 1").
+- **Each phase carries its own contract:** objective, the specific files it creates or modifies, which earlier phases it depends on, its success criteria, and how it will be tested.
+- **Phases are ordered so dependencies are satisfied before the phase that needs them.**
 
 ## Output
 
-Create the plan file at `codev/plans/{{artifact_name}}.md`, following the template below:
+Write the plan to `codev/plans/{{artifact_name}}.md` using the template below as its interface:
 
 {{> protocols/spir/templates/plan.md}}
 
 ## Signals
 
-Emit appropriate signals based on your progress:
-
-- After completing the plan draft:
+- Draft done:
   ```
   <signal>PLAN_DRAFTED</signal>
   ```
 
-## Commit Cadence
+## Commit cadence
 
-Make commits at these milestones:
+Commit at each milestone, staging the plan file explicitly:
+```bash
+git add codev/plans/{{artifact_name}}.md
+```
 1. `[Spec {{project_id}}] Initial implementation plan`
 2. `[Spec {{project_id}}] Plan with multi-agent review`
 3. `[Spec {{project_id}}] Plan with user feedback`
 4. `[Spec {{project_id}}] Final approved plan`
 
-**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
-```bash
-git add codev/plans/{{artifact_name}}.md
-```
-
-## Important Notes
-
-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
-
-## What NOT to Do
-
-- 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
-- Don't skip dependency analysis
-- Don't make phases too large (if >5 files, split it)
-- Don't use `git add .` or `git add -A` (security risk)
+Porch runs the 3-way consultation itself after you signal — do not run `consult`. This is the Plan phase: decompose and sequence the work, do not write code, and do not estimate time.