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

package/skeleton/protocols/bugfix/prompts/investigate.md

@@ -0,0 +1,77 @@
+# INVESTIGATE Phase Prompt
+
+You are executing the **INVESTIGATE** phase of the BUGFIX protocol.
+
+## Your Goal
+
+Understand the bug, reproduce it, identify the root cause, and assess whether it's fixable within BUGFIX scope (< 300 LOC).
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Read the Issue
+
+Read the full issue description. Identify:
+- What is the expected behavior?
+- What is the actual behavior?
+- Are there reproduction steps?
+- Are there error messages or screenshots?
+
+### 2. Reproduce the Bug
+
+Before fixing anything, confirm the bug exists:
+- Follow the reproduction steps from the issue
+- If no steps are given, infer them from the description
+- Document the exact reproduction steps you used
+- If you **cannot** reproduce, signal `BLOCKED` with details
+
+### 3. Identify Root Cause
+
+Trace the bug to its source:
+- Read the relevant code paths
+- Use grep/search to find related code
+- Identify the exact file(s) and line(s) causing the issue
+- Understand **why** the bug occurs, not just **where**
+
+### 4. Assess Complexity
+
+Determine if this is BUGFIX-appropriate:
+- **< 300 LOC change**: Proceed with BUGFIX
+- **> 300 LOC or architectural**: Signal `TOO_COMPLEX` to escalate
+
+Consider:
+- How many files need to change?
+- Does it require new abstractions or refactoring?
+- Are there cascading effects?
+
+## Output
+
+By the end of this phase, you should know:
+1. The exact root cause
+2. Which files need to change
+3. The approximate size of the fix
+4. Whether it's BUGFIX-appropriate
+
+## Signals
+
+When investigation is complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If the bug is too complex for BUGFIX:
+
+```
+<signal>TOO_COMPLEX</signal>
+```
+
+If you're blocked (can't reproduce, missing context, etc.):
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -0,0 +1,84 @@
+# PR Phase Prompt
+
+You are executing the **PR** phase of the BUGFIX protocol.
+
+## Your Goal
+
+Create a pull request, run CMAP review, and address feedback.
+
+## Context
+
+- **Issue**: #{{issue.number}} — {{issue.title}}
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Create the Pull Request
+
+Create a PR that links to the issue:
+
+```bash
+gh pr create --title "Fix #{{issue.number}}: <brief description>" --body "$(cat <<'EOF'
+## Summary
+
+<1-2 sentence description of the bug and fix>
+
+Fixes #{{issue.number}}
+
+## Root Cause
+
+<Brief explanation of why the bug occurred>
+
+## Fix
+
+<Brief explanation of what was changed>
+
+## Test Plan
+
+- [ ] Regression test added
+- [ ] Build passes
+- [ ] All tests pass
+EOF
+)"
+```
+
+### 2. Run CMAP Review
+
+Run 3-way parallel consultation on the PR:
+
+```bash
+consult --model gemini pr <PR_NUMBER> &
+consult --model codex pr <PR_NUMBER> &
+consult --model claude pr <PR_NUMBER> &
+```
+
+All three should run in the background (`run_in_background: true`).
+
+### 3. Address Feedback
+
+Review the consultation results:
+- Fix any issues identified by reviewers
+- Push updates to the PR branch
+- Re-run CMAP if substantial changes were made
+
+### 4. Notify Architect
+
+After CMAP review is complete and feedback is addressed, notify the architect:
+
+```bash
+af send architect "PR #<number> ready for review (fixes issue #{{issue.number}})"
+```
+
+## Signals
+
+When PR is created and reviews are complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If you're blocked:
+
+```
+<signal>BLOCKED:reason goes here</signal>
+```

package/skeleton/protocols/bugfix/protocol.json

@@ -1,8 +1,19 @@
 {
   "$schema": "../../protocol-schema.json",
   "name": "bugfix",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight protocol for minor bugfixes using GitHub Issues",
+  "input": {
+    "type": "github-issue",
+    "required": false,
+    "default_for": ["--issue", "-i"]
+  },
+  "hooks": {
+    "pre-spawn": {
+      "collision-check": true,
+      "comment-on-issue": "On it! Working on a fix now."
+    }
+  },
   "phases": [
     {
       "id": "investigate",
@@ -32,6 +43,11 @@
         "commit"
       ],
       "checks": {
+        "regression_test": {
+          "description": "A regression test MUST be added unless explicitly justified. No fix without a test.",
+          "required": true,
+          "skip_requires_justification": true
+        },
         "build": {
           "command": "npm run build",
           "on_fail": "retry",
@@ -65,37 +81,7 @@
         "max_rounds": 1
       },
       "transition": {
-        "on_complete": "review"
-      }
-    },
-    {
-      "id": "review",
-      "name": "Review",
-      "description": "Address review feedback",
-      "type": "once",
-      "steps": [
-        "address_feedback",
-        "update_pr"
-      ],
-      "transition": {
-        "on_complete": "merge"
-      }
-    },
-    {
-      "id": "merge",
-      "name": "Merge",
-      "description": "Merge the fix and close the issue",
-      "type": "once",
-      "steps": [
-        "merge_pr",
-        "verify_main",
-        "close_issue"
-      ],
-      "gate": {
-        "name": "merge-approval",
-        "description": "Architect approves merge",
-        "requires": ["review_complete", "tests_pass"],
-        "next": null
+        "on_complete": null
       }
     }
   ],
@@ -105,7 +91,7 @@
       "transitions_to": "next_phase"
     },
     "TOO_COMPLEX": {
-      "description": "Bug is too complex for BUGFIX, escalate to SPIDER",
+      "description": "Bug is too complex for BUGFIX, escalate to SPIR",
       "transitions_to": "escalate"
     },
     "BLOCKED": {
@@ -114,6 +100,7 @@
     }
   },
   "defaults": {
+    "mode": "strict",
     "consultation": {
       "enabled": true,
       "models": ["gemini", "codex"],

package/skeleton/protocols/experiment/builder-prompt.md

@@ -0,0 +1,52 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are executing a disciplined experiment.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the EXPERIMENT protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Document your findings thoroughly
+{{/if}}
+
+{{#if mode_strict}}
+## Mode: STRICT
+You are running in STRICT mode. This means:
+- Porch orchestrates your work
+- Run: `porch next` to get your next tasks
+- Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
+{{/if}}
+
+## Protocol
+Follow the EXPERIMENT protocol: `codev/protocols/experiment/protocol.md`
+
+## EXPERIMENT Overview
+The EXPERIMENT protocol ensures disciplined experimentation:
+
+1. **Hypothesis Phase**: Define what you're testing and success criteria
+2. **Design Phase**: Plan the experiment approach
+3. **Execute Phase**: Run the experiment and gather data
+4. **Analyze Phase**: Evaluate results and draw conclusions
+
+{{#if task}}
+## Experiment Focus
+{{task_text}}
+{{/if}}
+
+## Key Principles
+- Start with a clear, falsifiable hypothesis
+- Define success/failure criteria upfront
+- Keep scope minimal for quick iteration
+- Document findings regardless of outcome
+- Separate experiment artifacts from production code
+
+## Getting Started
+1. Read the EXPERIMENT protocol document
+2. Define your hypothesis clearly
+3. Follow the phases in order

package/skeleton/protocols/experiment/protocol.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "experiment",
+  "version": "1.0.0",
+  "description": "Disciplined experimentation with hypothesis testing",
+  "input": {
+    "type": "none",
+    "required": false,
+    "default_for": []
+  },
+  "hooks": {
+    "pre-spawn": {}
+  },
+  "phases": [
+    {
+      "id": "hypothesis",
+      "name": "Hypothesis",
+      "description": "Define the hypothesis and success criteria",
+      "type": "once",
+      "steps": [
+        "define_hypothesis",
+        "define_success_criteria",
+        "define_scope",
+        "create_experiment_doc"
+      ],
+      "transition": {
+        "on_complete": "design"
+      }
+    },
+    {
+      "id": "design",
+      "name": "Design",
+      "description": "Design the experiment approach",
+      "type": "once",
+      "steps": [
+        "choose_approach",
+        "identify_dependencies",
+        "plan_implementation",
+        "define_measurements"
+      ],
+      "transition": {
+        "on_complete": "execute"
+      }
+    },
+    {
+      "id": "execute",
+      "name": "Execute",
+      "description": "Run the experiment",
+      "type": "once",
+      "steps": [
+        "implement_prototype",
+        "gather_data",
+        "document_findings"
+      ],
+      "transition": {
+        "on_complete": "analyze"
+      }
+    },
+    {
+      "id": "analyze",
+      "name": "Analyze",
+      "description": "Analyze results and draw conclusions",
+      "type": "once",
+      "steps": [
+        "analyze_data",
+        "evaluate_hypothesis",
+        "document_conclusions",
+        "recommend_next_steps"
+      ],
+      "gate": {
+        "name": "experiment-complete",
+        "description": "Experiment complete",
+        "requires": ["conclusions_documented"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal experiment is blocked",
+      "requires": "reason"
+    },
+    "HYPOTHESIS_REJECTED": {
+      "description": "Signal hypothesis was disproven",
+      "transitions_to": "analyze"
+    }
+  },
+  "defaults": {
+    "mode": "soft",
+    "consultation": {
+      "enabled": false,
+      "models": [],
+      "parallel": false
+    },
+    "checks": {}
+  }
+}

package/skeleton/protocols/experiment/protocol.md

@@ -10,7 +10,7 @@ Disciplined experimentation: Each experiment gets its own directory with `notes.
 
 **Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes
 
-**Skip for**: Production code (use SPIDER), simple one-off scripts, well-understood implementations (use TICK)
+**Skip for**: Production code (use SPIR), simple one-off scripts, well-understood implementations (use TICK)
 
 ## Structure
 
@@ -141,7 +141,7 @@ What should be done based on findings?
 
 ## Integration with Other Protocols
 
-### Experiment → SPIDER
+### Experiment → SPIR
 When an experiment validates an approach for production use:
 
 1. Create a specification referencing the experiment
@@ -225,5 +225,5 @@ Determine if Redis caching improves API response times for repeated queries.
 - Memory usage: 50MB for 10k cached responses
 
 ## Next Steps
-Create SPIDER spec for production caching implementation.
+Create SPIR spec for production caching implementation.
 ```

package/skeleton/protocols/experiment/templates/notes.md

@@ -88,7 +88,7 @@ Based on these findings:
 
 1. **Immediate**: What should happen right after this experiment?
 2. **Follow-up experiments**: What new questions emerged?
-3. **Production path**: If validated, what's needed for production? (SPIDER spec?)
+3. **Production path**: If validated, what's needed for production? (SPIR spec?)
 
 ## References
 

package/skeleton/protocols/maintain/builder-prompt.md

@@ -0,0 +1,46 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are executing the MAINTAIN protocol to clean up and synchronize the codebase.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the MAINTAIN protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Work through each phase methodically
+{{/if}}
+
+{{#if mode_strict}}
+## Mode: STRICT
+You are running in STRICT mode. This means:
+- Porch orchestrates your work
+- Run: `porch next` to get your next tasks
+- Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way review** — always follow porch next → porch done cycle
+{{/if}}
+
+## Protocol
+Follow the MAINTAIN protocol: `codev/protocols/maintain/protocol.md`
+
+## MAINTAIN Overview
+The MAINTAIN protocol handles codebase hygiene:
+
+1. **Audit Phase**: Scan for dead code, unused dependencies, stale docs
+2. **Clean Phase**: Remove identified cruft, verify build
+3. **Sync Phase**: Update documentation (arch.md, lessons-learned.md, CLAUDE.md)
+4. **Verify Phase**: Run full test suite, confirm health
+
+## Key Rules
+- Use soft deletion (move to `codev/maintain/.trash/`)
+- Always verify build passes after removals
+- Update documentation to match current architecture
+- Don't remove anything actively used
+
+## Getting Started
+1. Read the MAINTAIN protocol document
+2. Start with the Audit phase
+3. Document all changes made

package/skeleton/protocols/maintain/prompts/audit.md

@@ -0,0 +1,111 @@
+# AUDIT Phase Prompt
+
+You are executing the **AUDIT** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Analyze the codebase to identify dead code, unused dependencies, and stale documentation.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Determine Base Commit
+
+Find the last maintenance run:
+```bash
+ls codev/maintain/
+```
+
+If previous runs exist, note the base commit to focus on changes since then.
+
+### 2. Scan for Dead Code
+
+Run static analysis tools:
+
+```bash
+# TypeScript/JavaScript
+npx ts-prune 2>/dev/null || echo "ts-prune not available"
+npx depcheck 2>/dev/null || echo "depcheck not available"
+
+# Check for unused exports
+grep -r "export " --include="*.ts" --include="*.tsx" | head -50
+```
+
+### 3. Scan for Unused Dependencies
+
+Check package.json for unused dependencies:
+```bash
+cat package.json | grep -A100 '"dependencies"' | head -50
+```
+
+Cross-reference with actual imports in the codebase.
+
+### 4. Scan for Stale Documentation
+
+Check for references to deleted files/functions:
+```bash
+# Recent changes
+git log --oneline -20
+
+# Check if arch.md references exist
+grep -E "src/|packages/" codev/resources/arch.md | head -20
+```
+
+### 5. Create Audit Report
+
+Create a maintenance run file: `codev/maintain/NNNN.md`
+
+Document:
+- Dead code identified (with file paths)
+- Unused dependencies
+- Stale documentation references
+- Recommended actions
+
+Use the template structure:
+```markdown
+# Maintenance Run NNNN
+
+**Date**: YYYY-MM-DD
+**Base Commit**: <commit-hash>
+
+## Dead Code Identified
+
+| File | Item | Reason |
+|------|------|--------|
+| path/to/file.ts | unusedFunction() | Not imported anywhere |
+
+## Unused Dependencies
+
+| Package | Reason |
+|---------|--------|
+| some-pkg | Not imported |
+
+## Stale Documentation
+
+| Document | Issue |
+|----------|-------|
+| arch.md | References deleted module |
+
+## Recommended Actions
+
+1. Remove X
+2. Update Y
+3. ...
+```
+
+## Signals
+
+When audit report is complete:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

package/skeleton/protocols/maintain/prompts/clean.md

@@ -0,0 +1,91 @@
+# CLEAN Phase Prompt
+
+You are executing the **CLEAN** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Remove the dead code and unused dependencies identified in the audit phase.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Prerequisites
+
+Read the audit report from the previous phase:
+```bash
+ls -la codev/maintain/
+cat codev/maintain/*.md | tail -100
+```
+
+## Process
+
+### 1. Remove Dead Code
+
+For each item identified in the audit:
+
+1. Verify it's truly unused (double-check with grep)
+2. Use `git rm` for tracked files
+3. For untracked files, move to `.trash/` before deleting
+
+**CRITICAL**: Use soft deletion first:
+```bash
+mkdir -p codev/maintain/.trash/$(date +%Y-%m-%d)
+mv path/to/file codev/maintain/.trash/$(date +%Y-%m-%d)/
+```
+
+### 2. Remove Unused Dependencies
+
+```bash
+# Remove from package.json
+npm uninstall <package-name>
+```
+
+### 3. Verify Build After Each Removal
+
+After each significant removal:
+```bash
+npm run build
+npm test -- --exclude='**/e2e/**'
+```
+
+If build fails, revert the change and investigate.
+
+### 4. Commit Changes
+
+Make atomic commits for each logical change:
+```bash
+git add <specific-files>
+git commit -m "[Maintain] Remove unused X"
+```
+
+**NEVER use `git add -A` or `git add .`**
+
+## Important Rules
+
+1. **One removal at a time** - Don't batch unrelated changes
+2. **Verify after each removal** - Build must pass
+3. **Document what was removed** - Update the maintenance run file
+4. **Soft delete first** - Move to .trash/ before permanent deletion
+5. **Check for side effects** - Grep for references before removing
+
+## Output
+
+Update the maintenance run file with:
+- What was removed
+- Build/test status after removal
+- Any issues encountered
+
+## Signals
+
+When all dead code is removed and build passes:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```