@cluesmith/codev 2.0.3 → 2.0.7

package/skeleton/protocols/maintain/protocol.json

@@ -20,7 +20,7 @@
         "artifact": "codev/maintain/*.md"
       },
       "verify": {
-        "type": "impl-review",
+        "type": "impl",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -41,7 +41,7 @@
         "artifact": "src/**/*.{ts,tsx,js,jsx}"
       },
       "verify": {
-        "type": "impl-review",
+        "type": "impl",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -74,7 +74,7 @@
         "artifact": "codev/resources/*.md"
       },
       "verify": {
-        "type": "impl-review",
+        "type": "impl",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
@@ -95,7 +95,7 @@
         "artifact": "codev/maintain/*.md"
       },
       "verify": {
-        "type": "pr-ready",
+        "type": "pr",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },

package/skeleton/protocols/maintain/protocol.md

@@ -57,8 +57,8 @@ Each maintenance run creates a numbered file in `codev/maintain/`:
 
 ```
 codev/maintain/
-├── 0001.md
-├── 0002.md
+├── 1.md
+├── 2.md
 └── ...
 ```
 
@@ -111,8 +111,7 @@ ruff check --select F401   # Find unused imports
 
 | Task | Parallelizable | Human Review? | Description |
 |------|----------------|---------------|-------------|
-| Update projectlist.md status | Yes | No | Update project statuses |
-| Archive terminal projects | Yes | No | Move completed/abandoned to terminal section |
+| Update GitHub Issue statuses | Yes | No | Close completed issues, update labels |
 
 ### Framework Tasks
 
@@ -285,15 +284,15 @@ Extract actionable wisdom from review documents into `codev/resources/lessons-le
 # Lessons Learned
 
 ## Testing
-- [From 0001] Always use XDG sandboxing in tests to avoid touching real $HOME
-- [From 0009] Verify dependencies actually export what you expect
+- [From 1] Always use XDG sandboxing in tests to avoid touching real $HOME
+- [From 9] Verify dependencies actually export what you expect
 
 ## Architecture
-- [From 0008] Single source of truth beats distributed state
-- [From 0031] SQLite with WAL mode handles concurrency better than JSON files
+- [From 8] Single source of truth beats distributed state
+- [From 31] SQLite with WAL mode handles concurrency better than JSON files
 
 ## Process
-- [From 0001] Multi-agent consultation catches issues humans miss
+- [From 1] Multi-agent consultation catches issues humans miss
 ```
 
 ### Sync CLAUDE.md ↔ AGENTS.md
@@ -421,9 +420,9 @@ After completing all tasks and validation, run a 3-way consultation review:
 
 ```bash
 # Run all three in parallel
-consult --model gemini --type impl-review pr <branch-name> &
-consult --model codex --type impl-review pr <branch-name> &
-consult --model claude --type impl-review pr <branch-name> &
+consult -m gemini --protocol maintain --type pr &
+consult -m codex --protocol maintain --type pr &
+consult -m claude --protocol maintain --type pr &
 wait
 ```
 

package/skeleton/protocols/maintain/templates/maintenance-run.md

@@ -1,4 +1,4 @@
-# Maintenance Run NNNN
+# Maintenance Run NNN
 
 ## Metadata
 - **Date**: YYYY-MM-DD
@@ -30,7 +30,7 @@ git log --oneline <last-maint-commit>..HEAD
 
 ### Framework
 - [ ] codev update
-- [ ] projectlist.md status updates
+- [ ] GitHub Issue status updates (close completed, update labels)
 
 ## Findings
 

package/skeleton/protocols/protocol-schema.json

@@ -149,7 +149,7 @@
         },
         "type": {
           "type": "string",
-          "description": "Review type (spec-review, plan-review, impl-review, pr-ready)"
+          "description": "Review type (spec, plan, impl, pr, phase, integration)"
         },
         "parallel": {
           "type": "boolean",

package/skeleton/protocols/spir/consult-types/impl-review.md

@@ -0,0 +1,72 @@
+# Implementation Review Prompt
+
+## Context
+You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+
+## CRITICAL: Verify Before Flagging
+
+Before requesting changes for missing configuration, incorrect patterns, or framework issues:
+1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
+2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
+3. **Do not assume** your training data reflects the version in use — verify against project files
+4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
+
+## Focus Areas
+
+1. **Spec Adherence**
+   - Does the implementation fulfill the spec requirements for this phase?
+   - Are acceptance criteria met?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - Are there plan items skipped or partially completed?
+
+5. **UX Verification** (if spec has UX requirements)
+   - Does the actual user experience match what the spec describes?
+   - If spec says "async" or "non-blocking", is it actually async?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Phase is complete, builder can proceed
+- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
+- `COMMENT`: Minor suggestions, can proceed but note feedback
+
+## Scoping (Multi-Phase Plans)
+
+When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
+- **ONLY review work belonging to the current plan phase**
+- The query will specify which phase you are reviewing
+- Do NOT request changes for functionality scheduled in later phases
+- Do NOT flag missing features that are out of scope for this phase
+- If unsure whether something belongs to this phase, check the plan file
+
+## Notes
+
+- This is a phase-level review, not the final PR review
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

package/skeleton/protocols/spir/consult-types/phase-review.md

@@ -0,0 +1,72 @@
+# Implementation Review Prompt
+
+## Context
+You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
+
+## CRITICAL: Verify Before Flagging
+
+Before requesting changes for missing configuration, incorrect patterns, or framework issues:
+1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions
+2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs
+3. **Do not assume** your training data reflects the version in use — verify against project files
+4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed
+
+## Focus Areas
+
+1. **Spec Adherence**
+   - Does the implementation fulfill the spec requirements for this phase?
+   - Are acceptance criteria met?
+
+2. **Code Quality**
+   - Is the code readable and maintainable?
+   - Are there obvious bugs or issues?
+   - Are error cases handled appropriately?
+
+3. **Test Coverage**
+   - Are the tests adequate for this phase?
+   - Do tests cover the main paths AND edge cases?
+
+4. **Plan Alignment**
+   - Does the implementation follow the plan?
+   - Are there plan items skipped or partially completed?
+
+5. **UX Verification** (if spec has UX requirements)
+   - Does the actual user experience match what the spec describes?
+   - If spec says "async" or "non-blocking", is it actually async?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+```
+
+**Verdict meanings:**
+- `APPROVE`: Phase is complete, builder can proceed
+- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
+- `COMMENT`: Minor suggestions, can proceed but note feedback
+
+## Scoping (Multi-Phase Plans)
+
+When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl):
+- **ONLY review work belonging to the current plan phase**
+- The query will specify which phase you are reviewing
+- Do NOT request changes for functionality scheduled in later phases
+- Do NOT flag missing features that are out of scope for this phase
+- If unsure whether something belongs to this phase, check the plan file
+
+## Notes
+
+- This is a phase-level review, not the final PR review
+- Focus on "does this phase work" not "is the whole feature done"
+- If referencing line numbers, use `file:line` format
+- The builder needs actionable feedback to continue

package/skeleton/protocols/spir/consult-types/pr-review.md

@@ -0,0 +1,72 @@
+# PR Ready Review Prompt
+
+## Context
+You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review.
+
+## Focus Areas
+
+1. **Completeness**
+   - Are all spec requirements implemented?
+   - Are all plan phases complete?
+   - Is the review document written (`codev/reviews/XXXX-name.md`)?
+   - Are all commits properly formatted (`[Spec XXXX][Phase]`)?
+
+2. **Test Status**
+   - Do all tests pass?
+   - Is test coverage adequate for the changes?
+   - Are there any skipped or flaky tests?
+
+3. **Code Cleanliness**
+   - Is there any debug code left in?
+   - Are there any TODO comments that should be resolved?
+   - Are there any `// REVIEW:` comments that weren't addressed?
+   - Is the code properly formatted?
+
+4. **Documentation**
+   - Are inline comments clear where needed?
+   - Is the review document comprehensive?
+   - Are any new APIs documented?
+
+5. **PR Readiness**
+   - Is the branch up to date with main?
+   - Are commits atomic and well-described?
+   - Is the change diff reasonable in size?
+
+## Verdict Format
+
+After your review, provide your verdict in exactly this format:
+
+```
+---
+VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
+SUMMARY: [One-line summary of your assessment]
+CONFIDENCE: [HIGH | MEDIUM | LOW]
+---
+KEY_ISSUES:
+- [Issue 1 or "None"]
+- [Issue 2]
+...
+
+PR_SUMMARY: |
+  ## Summary
+  [2-3 sentences describing what this PR does]
+
+  ## Key Changes
+  - [Change 1]
+  - [Change 2]
+
+  ## Test Plan
+  - [How to test]
+```
+
+**Verdict meanings:**
+- `APPROVE`: Ready to create PR
+- `REQUEST_CHANGES`: Issues to fix before PR creation
+- `COMMENT`: Minor items, can create PR but note feedback
+
+## Notes
+
+- This is the builder's final self-review before hand-off
+- The PR_SUMMARY in your output can be used as the PR description
+- Focus on "is this ready for someone else to review" not "is this perfect"
+- Any issues found here are cheaper to fix than during integration review

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

@@ -11,8 +11,8 @@ Transform the approved specification into an executable implementation plan with
 - **Project ID**: {{project_id}}
 - **Project Title**: {{title}}
 - **Current State**: {{current_state}}
-- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
-- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
 
 ## Prerequisites
 
@@ -74,7 +74,7 @@ After completing the plan draft, signal completion. Porch will run 3-way consult
 
 ## Output
 
-Create the plan file at `codev/plans/{{project_id}}-{{title}}.md`.
+Create the plan file at `codev/plans/{{artifact_name}}.md`.
 
 Use the plan template from `codev/protocols/spir/templates/plan.md` if available.
 
@@ -129,7 +129,7 @@ Make commits at these milestones:
 
 **CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
 ```bash
-git add codev/plans/{{project_id}}-{{title}}.md
+git add codev/plans/{{artifact_name}}.md
 ```
 
 ## Important Notes

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

@@ -11,9 +11,9 @@ Perform a comprehensive review, document lessons learned, and prepare for PR sub
 - **Project ID**: {{project_id}}
 - **Project Title**: {{title}}
 - **Current State**: {{current_state}}
-- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
-- **Plan File**: `codev/plans/{{project_id}}-{{title}}.md`
-- **Review File**: `codev/reviews/{{project_id}}-{{title}}.md`
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
+- **Plan File**: `codev/plans/{{artifact_name}}.md`
+- **Review File**: `codev/reviews/{{artifact_name}}.md`
 
 ## Prerequisites
 
@@ -57,7 +57,7 @@ Compare final implementation to original specification:
 
 ### 3. Create Review Document
 
-Create `codev/reviews/{{project_id}}-{{title}}.md`:
+Create `codev/reviews/{{artifact_name}}.md`:
 
 ```markdown
 # Review: {{title}}
@@ -118,7 +118,7 @@ Before PR:
 
 **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.
+when the pr gate fires.
 
 ```bash
 gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
@@ -135,10 +135,10 @@ gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
 - Manual testing completed for [Y]
 
 ## Spec
-Link: codev/specs/{{project_id}}-{{title}}.md
+Link: codev/specs/{{artifact_name}}.md
 
 ## Review
-Link: codev/reviews/{{project_id}}-{{title}}.md
+Link: codev/reviews/{{artifact_name}}.md
 EOF
 )"
 ```
@@ -151,7 +151,7 @@ changes, you'll be respawned with their feedback.
 
 ## Output
 
-- Review document at `codev/reviews/{{project_id}}-{{title}}.md`
+- Review document at `codev/reviews/{{artifact_name}}.md`
 - Updated documentation (if needed)
 - Pull request created and ready for review
 

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

@@ -11,7 +11,7 @@ Create a comprehensive specification document that thoroughly explores the probl
 - **Project ID**: {{project_id}}
 - **Project Title**: {{title}}
 - **Current State**: {{current_state}}
-- **Spec File**: `codev/specs/{{project_id}}-{{title}}.md`
+- **Spec File**: `codev/specs/{{artifact_name}}.md`
 
 ## Process
 
@@ -82,12 +82,12 @@ After completing the spec draft, signal completion. Porch will run 3-way consult
 
 ## Output
 
-Create or update the specification file at `codev/specs/{{project_id}}-{{title}}.md`.
+Create or update the specification file at `codev/specs/{{artifact_name}}.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`
+- Spec: `codev/specs/{{artifact_name}}.md`
+- Plan: `codev/plans/{{artifact_name}}.md`
+- Review: `codev/reviews/{{artifact_name}}.md`
 
 ## Signals
 
@@ -121,7 +121,7 @@ Make commits at these milestones:
 
 **CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files:
 ```bash
-git add codev/specs/{{project_id}}-{{title}}.md
+git add codev/specs/{{artifact_name}}.md
 ```
 
 ## Important Notes

package/skeleton/protocols/spir/protocol.json

@@ -17,14 +17,14 @@
       "type": "build_verify",
       "build": {
         "prompt": "specify.md",
-        "artifact": "codev/specs/${PROJECT_ID}-*.md"
+        "artifact": "codev/specs/${PROJECT_TITLE}.md"
       },
       "verify": {
-        "type": "spec-review",
+        "type": "spec",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 7,
+      "max_iterations": 1,
       "on_complete": {
         "commit": true,
         "push": true
@@ -39,22 +39,22 @@
       "type": "build_verify",
       "build": {
         "prompt": "plan.md",
-        "artifact": "codev/plans/${PROJECT_ID}-*.md"
+        "artifact": "codev/plans/${PROJECT_TITLE}.md"
       },
       "verify": {
-        "type": "plan-review",
+        "type": "plan",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 7,
+      "max_iterations": 1,
       "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",
-        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_ID}-*.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
+        "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md",
+        "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md",
+        "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'"
       },
       "gate": "plan-approval",
       "next": "implement"
@@ -69,11 +69,11 @@
         "artifact": "src/**/*.{ts,tsx,js,jsx}"
       },
       "verify": {
-        "type": "impl-review",
+        "type": "impl",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 7,
+      "max_iterations": 1,
       "on_complete": {
         "commit": true,
         "push": true
@@ -103,14 +103,14 @@
       "type": "build_verify",
       "build": {
         "prompt": "review.md",
-        "artifact": "codev/reviews/${PROJECT_ID}-*.md"
+        "artifact": "codev/reviews/${PROJECT_TITLE}.md"
       },
       "verify": {
-        "type": "pr-ready",
+        "type": "pr",
         "models": ["gemini", "codex", "claude"],
         "parallel": true
       },
-      "max_iterations": 7,
+      "max_iterations": 1,
       "on_complete": {
         "commit": true,
         "push": true
@@ -126,7 +126,7 @@
           "optional": true
         }
       },
-      "gate": "pr-ready",
+      "gate": "pr",
       "next": null
     }
   ],
@@ -147,7 +147,7 @@
   },
   "defaults": {
     "mode": "strict",
-    "max_iterations": 7,
+    "max_iterations": 1,
     "verify": {
       "models": ["gemini", "codex", "claude"],
       "parallel": true

package/skeleton/protocols/spir/protocol.md

@@ -553,9 +553,9 @@ Execute for each phase in the plan. Each phase follows a build-verify cycle.
 
 ### Specifications and Plans
 Format: `####-descriptive-name.md`
-- Use sequential numbering (0001, 0002, etc.)
+- Use sequential numbering (1, 2, etc.)
 - Same filename in both `specs/` and `plans/` directories
-- Example: `0001-user-authentication.md`
+- Example: `1-user-authentication.md`
 
 ## Status Tracking
 
@@ -578,10 +578,10 @@ For specification/plan documents:
 
 Examples:
 ```
-[Spec 0001] Initial specification draft
-[Spec 0001] Specification with multi-agent review
-[Spec 0001] Specification with user feedback
-[Spec 0001] Final approved specification
+[Spec 1] Initial specification draft
+[Spec 1] Specification with multi-agent review
+[Spec 1] Specification with user feedback
+[Spec 1] Final approved specification
 ```
 
 For implementation:
@@ -593,7 +593,7 @@ For implementation:
 
 Example:
 ```
-[Spec 0001][Phase: user-auth] feat: Add password hashing service
+[Spec 1][Phase: user-auth] feat: Add password hashing service
 
 Implements bcrypt-based password hashing with configurable rounds
 ```
@@ -605,7 +605,7 @@ spir/####-<spec-name>/<phase-name>
 
 Example:
 ```
-spir/0001-user-authentication/database-schema
+spir/1-user-authentication/database-schema
 ```
 
 

package/skeleton/protocols/spir/templates/review.md

@@ -33,7 +33,7 @@ All times [timezone], [date range].
 | — | **GATE: [gate-name]** (human approval required) |
 | HH:MM | Implementation begins |
 | HH:MM | Phase N complete after N iterations |
-| HH:MM | **GATE: pr-ready** |
+| HH:MM | **GATE: pr** |
 
 ### Autonomous Operation
 
@@ -43,7 +43,7 @@ All times [timezone], [date range].
 | Human gate wait | ~Nh Nm | Idle — waiting for approval |
 | Implementation → PR | ~Nh Nm | N phases, N consultation rounds |
 
-**Total wall clock** (first commit to pr-ready): **Xh Ym**
+**Total wall clock** (first commit to pr): **Xh Ym**
 **Total autonomous work time** (excluding gate waits): **~Xh Ym**
 **Context window resets**: [N] (resumed automatically / required manual restart)