@cluesmith/codev 2.0.0-rc.9 → 2.0.0

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

@@ -0,0 +1,113 @@
+# SYNC Phase Prompt
+
+You are executing the **SYNC** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Update documentation to match the current state of the codebase.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Update arch.md
+
+Read the current architecture doc and compare with actual codebase:
+
+```bash
+cat codev/resources/arch.md
+ls -la packages/ src/ 2>/dev/null
+```
+
+Update:
+- Directory structure (if changed)
+- Component descriptions
+- Key files and their purposes
+- Remove references to deleted code
+- Add new utilities/components
+
+**arch.md must explain HOW things work, not just WHAT they are.**
+
+### 2. Generate/Update lessons-learned.md
+
+Scan review documents for lessons:
+
+```bash
+ls codev/reviews/
+```
+
+Extract actionable lessons:
+- Testing practices
+- Architecture decisions
+- Process improvements
+- Patterns to follow/avoid
+
+Format:
+```markdown
+## [Topic]
+- [From NNNN] Lesson description
+```
+
+### 3. Sync CLAUDE.md with AGENTS.md
+
+Compare the two files:
+```bash
+diff CLAUDE.md AGENTS.md | head -50
+```
+
+They must be identical. Update the stale one to match.
+
+### 4. Prune Documentation
+
+Check document sizes:
+```bash
+wc -l CLAUDE.md AGENTS.md README.md
+```
+
+Target ~400 lines for CLAUDE.md/README.md (guideline, not mandate).
+
+For any content removed, document:
+- WHAT was removed
+- WHY it was removed (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE)
+- WHERE it moved (if applicable)
+
+### 5. Commit Documentation Changes
+
+```bash
+git add codev/resources/arch.md codev/resources/lessons-learned.md
+git commit -m "[Maintain] Update arch.md and lessons-learned.md"
+
+git add CLAUDE.md AGENTS.md
+git commit -m "[Maintain] Sync CLAUDE.md with AGENTS.md"
+```
+
+## Important Rules
+
+1. **Never invent structure** - Only document what exists
+2. **Verify file paths** - Check that referenced files exist
+3. **Keep it current** - Remove obsolete references
+4. **Preserve important content** - Don't delete patterns/best practices
+5. **Document deletions** - Every removal needs justification
+
+## Output
+
+Update the maintenance run file with:
+- Documents updated
+- What was added/removed/changed
+- Any issues encountered
+
+## Signals
+
+When documentation is synchronized:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

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

@@ -0,0 +1,110 @@
+# VERIFY Phase Prompt
+
+You are executing the **VERIFY** phase of the MAINTAIN protocol.
+
+## Your Goal
+
+Run final validation and prepare for PR creation.
+
+## Context
+
+- **Current State**: {{current_state}}
+
+## Process
+
+### 1. Run Full Test Suite
+
+```bash
+npm run build
+npm test
+```
+
+Both must pass. If either fails, go back and fix the issue.
+
+### 2. Run Linting
+
+```bash
+npm run lint 2>/dev/null || echo "No lint script"
+```
+
+Fix any linting errors.
+
+### 3. Verify Documentation Links
+
+Check that documentation references resolve:
+```bash
+# Check arch.md file references
+grep -oE 'src/[^ ]+|packages/[^ ]+' codev/resources/arch.md | while read f; do
+  [ -e "$f" ] || echo "Missing: $f"
+done
+```
+
+### 4. Update Maintenance Run Summary
+
+Finalize the maintenance run file with:
+
+```markdown
+## Summary
+
+- **Dead code removed**: X files, Y functions
+- **Dependencies removed**: Z packages
+- **Documentation updated**: arch.md, lessons-learned.md
+- **All tests passing**: Yes/No
+- **Build status**: Success/Failure
+
+## Next Maintenance
+
+Recommended focus areas for next run:
+- ...
+```
+
+### 5. Create PR
+
+```bash
+git push origin HEAD
+
+gh pr create --title "[Maintain] Codebase maintenance run NNNN" --body "$(cat <<'EOF'
+## Summary
+
+- Dead code removal
+- Documentation sync
+- Dependency cleanup
+
+## Changes
+
+[List key changes]
+
+## Verification
+
+- [x] Build passes
+- [x] Tests pass
+- [x] Documentation updated
+EOF
+)"
+```
+
+## Validation Checklist
+
+Before signaling complete:
+
+- [ ] All tests pass
+- [ ] Build succeeds
+- [ ] No import/module errors
+- [ ] Documentation links resolve
+- [ ] Linter passes (if configured)
+- [ ] Maintenance run file is complete
+- [ ] PR is created
+
+## Signals
+
+When validation passes and PR is ready:
+
+```
+<signal>PHASE_COMPLETE</signal>
+```
+
+If blocked:
+
+```
+<signal>BLOCKED:reason</signal>
+```

package/skeleton/protocols/maintain/protocol.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "maintain",
+  "alias": "maint",
+  "version": "2.0.0",
+  "description": "Codebase maintenance - dead code removal, doc sync, hygiene with 3-way review",
+  "input": {
+    "type": "protocol",
+    "required": false,
+    "default_for": ["--protocol maintain"]
+  },
+  "phases": [
+    {
+      "id": "audit",
+      "name": "Audit",
+      "description": "Analyze codebase for dead code, unused dependencies, stale docs",
+      "type": "build_verify",
+      "build": {
+        "prompt": "audit.md",
+        "artifact": "codev/maintain/*.md"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 3,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "next": "clean"
+    },
+    {
+      "id": "clean",
+      "name": "Clean",
+      "description": "Remove identified dead code and unused dependencies",
+      "type": "build_verify",
+      "build": {
+        "prompt": "clean.md",
+        "artifact": "src/**/*.{ts,tsx,js,jsx}"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 5,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "checks": {
+        "build": {
+          "command": "npm run build",
+          "on_fail": "retry",
+          "max_retries": 2
+        },
+        "tests": {
+          "command": "npm test -- --exclude='**/e2e/**'",
+          "on_fail": "retry",
+          "max_retries": 2
+        }
+      },
+      "next": "sync"
+    },
+    {
+      "id": "sync",
+      "name": "Sync Documentation",
+      "description": "Update documentation to match current codebase",
+      "type": "build_verify",
+      "build": {
+        "prompt": "sync.md",
+        "artifact": "codev/resources/*.md"
+      },
+      "verify": {
+        "type": "impl-review",
+        "models": ["gemini", "codex", "claude"],
+        "parallel": true
+      },
+      "max_iterations": 5,
+      "on_complete": {
+        "commit": true,
+        "push": true
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify",
+      "description": "Final validation and PR creation",
+      "type": "build_verify",
+      "build": {
+        "prompt": "verify.md",
+        "artifact": "codev/maintain/*.md"
+      },
+      "verify": {
+        "type": "pr-ready",
+        "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
+        }
+      },
+      "gate": "maintain-complete",
+      "next": null
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "verify"
+    },
+    "BLOCKED": {
+      "description": "Signal maintenance is blocked",
+      "requires": "reason"
+    }
+  },
+  "defaults": {
+    "mode": "strict",
+    "max_iterations": 5,
+    "verify": {
+      "models": ["gemini", "codex", "claude"],
+      "parallel": true
+    }
+  }
+}

package/skeleton/protocols/maintain/protocol.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-MAINTAIN is a periodic maintenance protocol for keeping codebases healthy. Unlike SPIDER/TICK (which have sequential phases), MAINTAIN is a **task list** where tasks can run in parallel and some require human review.
+MAINTAIN is a periodic maintenance protocol for keeping codebases healthy. It runs as a **strict porch protocol** with sequential phases and 3-way consultation (Gemini, Codex, Claude) at each phase.
 
 **Core Principle**: Regular maintenance prevents technical debt accumulation.
 
@@ -22,20 +22,26 @@ Any builder can update these files during development, but MAINTAIN ensures they
 
 ## Execution Model
 
-MAINTAIN is executed by a Builder, spawned by the Architect:
+MAINTAIN is orchestrated by porch with 4 sequential phases:
 
 ```
-Architect: "Time for maintenance"
-    ↓
 af spawn --protocol maintain
     ↓
-Builder works through task list
-    ↓
+1. AUDIT: Scan for dead code, unused deps, stale docs
+    ↓ (3-way review)
+2. CLEAN: Remove identified cruft
+    ↓ (3-way review + build/test checks)
+3. SYNC: Update documentation
+    ↓ (3-way review)
+4. VERIFY: Final validation + PR
+    ↓ (3-way review)
 PR with maintenance changes
     ↓
-Architect reviews → Builder merges
+Architect reviews → Merge
 ```
 
+Each phase goes through build-verify cycles with 3-way consultation before proceeding.
+
 ## Prerequisites
 
 Before starting MAINTAIN:
@@ -180,8 +186,8 @@ Scan the actual codebase and update `codev/resources/arch.md`:
 - **Location**: path/to/component
 - **How It Works**:
   - Step-by-step explanation of the mechanism
-  - Key technologies used (e.g., "uses tmux for terminal multiplexing")
-  - Runtime behavior (e.g., "spawns a tmux session per builder")
+  - Key technologies used (e.g., "uses shellper processes for terminal persistence")
+  - Runtime behavior (e.g., "spawns a shellper process per builder terminal")
   - State management (e.g., "state stored in SQLite at .agent-farm/state.db")
 - **Key Files**:
   - `file.ts` - does X
@@ -216,7 +222,7 @@ For each major component, arch.md MUST explain the implementation mechanism, not
 
 | Bad (just WHAT) | Good (includes HOW) |
 |-----------------|---------------------|
-| "Agent Farm manages builders" | "Agent Farm spawns builders in isolated git worktrees. Each builder runs in a tmux session (named `builder-{id}`). The dashboard uses ttyd to expose terminals via HTTP on ports 4201-4299. State is persisted in SQLite." |
+| "Agent Farm manages builders" | "Agent Farm spawns builders in isolated git worktrees. Each builder runs in a shellper-backed terminal session. The Tower dashboard exposes terminals via WebSocket. State is persisted in SQLite." |
 | "Consult tool queries AI models" | "Consult shells out to external CLIs (gemini-cli, codex, claude). It writes the consultant role to a temp file, sets environment variables, and streams stdout/stderr back to the user." |
 
 This level of detail enables rapid onboarding and debugging.
@@ -473,7 +479,7 @@ MAINTAIN is an **operational protocol**, not a feature development protocol:
 | Review | No |
 | 3-Way Consultation | **Yes** (before creating PR) |
 
-**Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIDER.
+**Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIR.
 
 ---
 

package/skeleton/protocols/protocol-schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "name": {
       "type": "string",
-      "description": "Protocol identifier (e.g., 'spider', 'tick', 'bugfix')"
+      "description": "Protocol identifier (e.g., 'spir', 'tick', 'bugfix')"
     },
     "version": {
       "type": "string",
@@ -27,6 +27,12 @@
       },
       "minItems": 1
     },
+    "input": {
+      "$ref": "#/definitions/protocolInput"
+    },
+    "hooks": {
+      "$ref": "#/definitions/protocolHooks"
+    },
     "signals": {
       "type": "object",
       "description": "Signal definitions for state transitions",
@@ -38,6 +44,11 @@
       "type": "object",
       "description": "Default configuration for the protocol",
       "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["strict", "soft"],
+          "description": "Default orchestration mode for the protocol"
+        },
         "consultation": {
           "$ref": "#/definitions/consultationDefaults"
         },
@@ -232,6 +243,48 @@
           "type": "string"
         }
       }
+    },
+    "protocolInput": {
+      "type": "object",
+      "description": "Protocol input configuration - defines what input types a protocol accepts",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["spec", "github-issue", "task", "protocol", "shell", "worktree"],
+          "description": "Primary input type for this protocol"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether an input of this type is required"
+        },
+        "default_for": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "CLI flags this protocol is the default for (e.g., ['--issue', '-i'])"
+        }
+      }
+    },
+    "protocolHooks": {
+      "type": "object",
+      "description": "Hooks triggered at various points in the spawn lifecycle",
+      "properties": {
+        "pre-spawn": {
+          "type": "object",
+          "description": "Hooks executed before spawning the builder",
+          "properties": {
+            "collision-check": {
+              "type": "boolean",
+              "description": "Check for worktree/PR collisions before spawning"
+            },
+            "comment-on-issue": {
+              "type": "string",
+              "description": "Comment to post on GitHub issue when spawning"
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -0,0 +1,66 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are implementing {{input_description}}.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the protocol document yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Run consultations manually when the protocol calls for them
+- You have flexibility in execution, but must stay compliant with the protocol
+{{/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
+- Do not deviate from the porch-driven workflow
+
+### 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
+- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval
+{{/if}}
+
+## Protocol
+Follow the SPIR protocol: `codev/protocols/spir/protocol.md`
+Read and internalize the protocol before starting any work.
+
+{{#if spec}}
+## Spec
+Read the specification at: `{{spec.path}}`
+{{/if}}
+
+{{#if plan}}
+## Plan
+Follow the implementation plan at: `{{plan.path}}`
+{{/if}}
+
+{{#if issue}}
+## Issue #{{issue.number}}
+**Title**: {{issue.title}}
+
+**Description**:
+{{issue.body}}
+{{/if}}
+
+{{#if task}}
+## Task
+{{task_text}}
+{{/if}}
+
+## Notifications
+Always use `af send architect "..."` to notify the architect at key moments:
+- **Gate reached**: `af send architect "Project {{project_id}}: <gate-name> ready for approval"`
+- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"`
+- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
+- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"`
+
+## Getting Started
+1. Read the protocol document thoroughly
+2. Review the spec and plan (if available)
+3. Begin implementation following the protocol phases