@cluesmith/codev 1.6.2 → 2.0.0-rc.10

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

@@ -0,0 +1,174 @@
+# SPECIFY Phase Prompt
+
+You are executing the **SPECIFY** phase of the SPIDER 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/{{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.
+
+## Process
+
+### 1. Clarifying Questions (ALWAYS START HERE)
+
+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, ask these questions now and wait for answers.
+
+**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. 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
+
+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
+
+## Output
+
+Create or update the specification file at `codev/specs/{{project_id}}-{{title}}.md`.
+
+**IMPORTANT**: Keep spec/plan/review filenames in sync:
+- Spec: `codev/specs/{{project_id}}-{{title}}.md`
+- 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, **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>
+  ```
+
+- After incorporating consultation feedback:
+  ```
+  <signal>CONSULTATION_INCORPORATED</signal>
+  ```
+
+- After final spec is ready for human approval:
+  ```
+  <signal>SPEC_READY_FOR_APPROVAL</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/{{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
+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 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/spider/protocol.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "spider",
+  "version": "2.0.0",
+  "description": "Specification-driven development with build-verify cycles",
+  "phases": [
+    {
+      "id": "specify",
+      "name": "Specify",
+      "description": "Write specification with 3-way review",
+      "type": "build_verify",
+      "build": {
+        "prompt": "specify.md",
+        "artifact": "codev/specs/${PROJECT_ID}-*.md"
+      },
+      "verify": {
+        "type": "spec-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "gate": "spec-approval",
+      "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_ID}-*.md"
+      },
+      "verify": {
+        "type": "plan-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "plan_exists": "test -f codev/plans/${PROJECT_ID}-*.md",
+        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_ID}-*.md"
+      },
+      "gate": "plan-approval",
+      "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-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test",
+          "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_ID}-*.md"
+      },
+      "verify": {
+        "type": "pr-ready",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "gate": "pr-ready",
+      "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": {
+    "max_iterations": 3,
+    "verify": {
+      "models": ["gemini", "codex", "claude"],
+      "parallel": true
+    }
+  }
+}

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

@@ -17,6 +17,20 @@
 - [ ] 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]

package/skeleton/protocols/tick/protocol.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "tick",
+  "version": "1.0.0",
+  "description": "Amendment workflow for existing SPIDER specifications",
+  "phases": [
+    {
+      "id": "identify",
+      "name": "Identify Target",
+      "description": "Find the existing spec to amend",
+      "type": "once",
+      "steps": [
+        "analyze_requirements",
+        "find_target_spec",
+        "verify_spec_integrated",
+        "determine_tick_number"
+      ],
+      "transition": {
+        "on_complete": "amend_spec"
+      }
+    },
+    {
+      "id": "amend_spec",
+      "name": "Amend Specification",
+      "description": "Update the existing specification",
+      "type": "once",
+      "steps": [
+        "analyze_changes_needed",
+        "update_spec_sections",
+        "add_amendment_entry",
+        "commit_spec_changes"
+      ],
+      "transition": {
+        "on_complete": "amend_plan"
+      }
+    },
+    {
+      "id": "amend_plan",
+      "name": "Amend Plan",
+      "description": "Update the existing plan",
+      "type": "once",
+      "steps": [
+        "update_plan_phases",
+        "add_amendment_history",
+        "commit_plan_changes"
+      ],
+      "transition": {
+        "on_complete": "implement"
+      }
+    },
+    {
+      "id": "implement",
+      "name": "Implement",
+      "description": "Implement the amendment",
+      "type": "once",
+      "steps": [
+        "implement_changes",
+        "self_review",
+        "commit"
+      ],
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "transition": {
+        "on_complete": "defend"
+      }
+    },
+    {
+      "id": "defend",
+      "name": "Defend",
+      "description": "Test the amendment",
+      "type": "once",
+      "steps": [
+        "write_tests",
+        "run_tests",
+        "fix_failures"
+      ],
+      "checks": {
+        "tests": {
+          "command": "npm test",
+          "on_fail": "implement",
+          "max_retries": 1
+        }
+      },
+      "transition": {
+        "on_complete": "evaluate"
+      }
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Verify amendment meets requirements",
+      "type": "once",
+      "steps": [
+        "verify_requirements",
+        "check_regressions"
+      ],
+      "transition": {
+        "on_complete": "review"
+      }
+    },
+    {
+      "id": "review",
+      "name": "Review",
+      "description": "Create review document and PR",
+      "type": "once",
+      "steps": [
+        "create_tick_review",
+        "create_pr"
+      ],
+      "consultation": {
+        "on": "review",
+        "models": ["gemini", "codex"],
+        "type": "impl-review",
+        "parallel": true,
+        "max_rounds": 1
+      },
+      "gate": {
+        "name": "pr-ready",
+        "description": "Amendment ready for PR",
+        "requires": ["tests_pass", "review_complete"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal implementation is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "consultation": {
+      "enabled": true,
+      "models": ["gemini", "codex"],
+      "parallel": true
+    },
+    "checks": {
+      "build": "npm run build",
+      "test": "npm test"
+    }
+  }
+}

package/skeleton/roles/architect.md

@@ -214,59 +214,49 @@ planning → active → released → archived
 
 ## Development Protocols
 
-The Architect uses SPIDER or TICK protocols. The Architect is responsible for the **Specify** and **Plan** phases. The Builder handles **Implement**, **Defend**, **Evaluate**, and **Review** (IDER).
-
-### Phase 1: Specify (Architect)
-
-1. Understand the user's request at a system level
-2. **Check `codev/resources/lessons-learned.md`** for relevant past lessons
-3. Identify major components and dependencies
-4. Create a detailed specification (incorporating lessons learned)
-5. **Consult external reviewers** using the consult tool:
-   ```bash
-   consult --model gemini --type spec-review spec 0034
-   consult --model codex --type spec-review spec 0034
-   ```
-5. Address concerns raised by the reviewers
-6. **Present to human** for final review:
-   ```bash
-   af open codev/specs/0034-feature-name.md
-   ```
-
-### Phase 2: Plan (Architect)
-
-1. Convert the spec into a sequence of implementation steps for the builder
-2. **Check `codev/resources/lessons-learned.md`** for implementation pitfalls to avoid
-3. Define what tests are needed
-4. Specify acceptance criteria
-5. **Consult external reviewers** using the consult tool:
-   ```bash
-   consult --model gemini --type plan-review plan 0034
-   consult --model codex --type plan-review plan 0034
-   ```
-5. Address concerns raised by the reviewers
-6. **Present to human** for final review:
-   ```bash
-   af open codev/plans/0034-feature-name.md
-   ```
-
-### Phases 3-6: IDER (Builder)
-
-Once the spec and plan are approved, the Architect spawns a builder:
+The Architect uses SPIDER or TICK protocols. **The Builder executes the full SPIDER protocol** (Specify → Plan → Implement → Defend → Evaluate → Review). The Architect's role is to spawn builders, approve gates, and integrate their work.
+
+### Spawning a Builder
+
+When a new feature is needed:
 
 ```bash
 af spawn -p 0034
 ```
 
-**Important:** Update the project status to `implementing` in `codev/projectlist.md` when spawning a builder.
+The builder will:
+1. **Specify** - Write the spec, run 3-way consultation, then hit `spec-approval` gate
+2. **Plan** - Write the plan, run 3-way consultation, then hit `plan-approval` gate
+3. **Implement/Defend/Evaluate** - Complete I→D→E cycles for each plan phase
+4. **Review** - Create review document and PR
+
+### Approving Gates
+
+The builder stops at two gates that require human approval:
+
+1. **spec-approval** - After the builder writes the spec
+   - Review the spec at `codev/specs/XXXX-name.md`
+   - Verify it captures requirements correctly
+   - Approve: `porch approve XXXX spec-approval --a-human-explicitly-approved-this`
+
+2. **plan-approval** - After the builder writes the plan
+   - Review the plan at `codev/plans/XXXX-name.md`
+   - Verify phases are logical and complete
+   - Approve: `porch approve XXXX plan-approval --a-human-explicitly-approved-this`
 
-The Builder then executes the remaining phases:
-- **Implement** - Write the code following the plan
-- **Defend** - Write tests to validate the implementation
-- **Evaluate** - Verify requirements are met
-- **Review** - Document lessons learned, create PR
+**Important:** Update the project status in `codev/projectlist.md` as gates are approved.
 
-The Architect monitors progress and provides guidance when the builder is blocked.
+### Monitoring Progress
+
+```bash
+# Check builder status
+af status
+
+# Check porch state for a project
+porch status 0034
+```
+
+The Architect monitors progress and provides guidance when builders are blocked.
 
 ## Spikes: De-risking Technical Unknowns
 
@@ -285,12 +275,14 @@ When facing high-risk technical unknowns, use **spikes** - short, time-boxed exp
 ### Providing Context
 
 When spawning a Builder, provide:
-- The spec file path
-- The plan file path
+- The project ID and name
+- High-level description of the feature
 - Any relevant architecture context
 - Constraints or patterns to follow
 - Which protocol to use (SPIDER/TICK)
 
+The builder will create the spec and plan files themselves.
+
 ### Handling Blocked Status
 
 When a Builder reports `blocked`: