@cluesmith/codev 3.2.4 → 3.3.1

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

@@ -1,184 +0,0 @@
-# Plan: [Title]
-
-## Metadata
-- **ID**: plan-[YYYY-MM-DD]-[short-name]
-- **Status**: draft
-- **Specification**: [Link to codev/specs/spec-file.md]
-- **Created**: [YYYY-MM-DD]
-
-## Executive Summary
-[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.]
-
-## Success Metrics
-[Copy from specification and add implementation-specific metrics]
-- [ ] All specification criteria met
-- [ ] Test coverage >90%
-- [ ] Performance benchmarks achieved
-- [ ] 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]
-**Dependencies**: None
-
-#### Objectives
-- [Clear, single objective for this phase]
-- [What value does this phase deliver?]
-
-#### Deliverables
-- [ ] [Specific deliverable 1]
-- [ ] [Specific deliverable 2]
-- [ ] [Tests for this phase]
-- [ ] [Documentation updates]
-
-#### Implementation Details
-[Specific technical approach for this phase. Include:
-- Key files/modules to create or modify
-- Architectural decisions
-- API contracts
-- Data models]
-
-#### Acceptance Criteria
-- [ ] [Testable criterion 1]
-- [ ] [Testable criterion 2]
-- [ ] All tests pass
-- [ ] Code review completed
-
-#### Test Plan
-- **Unit Tests**: [What to test]
-- **Integration Tests**: [What to test]
-- **Manual Testing**: [Scenarios to verify]
-
-#### Rollback Strategy
-[How to revert this phase if issues arise]
-
-#### Risks
-- **Risk**: [Specific risk for this phase]
-  - **Mitigation**: [How to address]
-
----
-
-### Phase 2: [Descriptive Name]
-**Dependencies**: Phase 1
-
-[Repeat structure for each phase]
-
----
-
-### Phase 3: [Descriptive Name]
-**Dependencies**: Phase 2
-
-[Continue for all phases]
-
-## Dependency Map
-```
-Phase 1 ──→ Phase 2 ──→ Phase 3
-             ↓
-         Phase 4 (optional)
-```
-
-## Resource Requirements
-### Development Resources
-- **Engineers**: [Expertise needed]
-- **Environment**: [Dev/staging requirements]
-
-### Infrastructure
-- [Database changes]
-- [New services]
-- [Configuration updates]
-- [Monitoring additions]
-
-## Integration Points
-### External Systems
-- **System**: [Name]
-  - **Integration Type**: [API/Database/Message Queue]
-  - **Phase**: [Which phase needs this]
-  - **Fallback**: [What if unavailable]
-
-### Internal Systems
-[Repeat structure]
-
-## Risk Analysis
-### Technical Risks
-| Risk | Probability | Impact | Mitigation | Owner |
-|------|------------|--------|------------|-------|
-| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] |
-
-### Schedule Risks
-| Risk | Probability | Impact | Mitigation | Owner |
-|------|------------|--------|------------|-------|
-| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] |
-
-## Validation Checkpoints
-1. **After Phase 1**: [What to validate]
-2. **After Phase 2**: [What to validate]
-3. **Before Production**: [Final checks]
-
-## Monitoring and Observability
-### Metrics to Track
-- [Metric 1: Description and threshold]
-- [Metric 2: Description and threshold]
-
-### Logging Requirements
-- [What to log and at what level]
-- [Retention requirements]
-
-### Alerting
-- [Alert condition and severity]
-- [Who to notify]
-
-## Documentation Updates Required
-- [ ] API documentation
-- [ ] Architecture diagrams
-- [ ] Runbooks
-- [ ] User guides
-- [ ] Configuration guides
-
-## Post-Implementation Tasks
-- [ ] Performance validation
-- [ ] Security audit
-- [ ] Load testing
-- [ ] User acceptance testing
-- [ ] Monitoring validation
-
-## Expert Review
-**Date**: [YYYY-MM-DD]
-**Model**: [Model consulted]
-**Key Feedback**:
-- [Feasibility assessment]
-- [Missing considerations]
-- [Risk identification]
-- [Alternative suggestions]
-
-**Plan Adjustments**:
-- [How the plan was modified based on feedback]
-
-## Approval
-- [ ] Technical Lead Review
-- [ ] Engineering Manager Approval
-- [ ] Resource Allocation Confirmed
-- [ ] Expert AI Consultation Complete
-
-## Change Log
-| Date | Change | Reason | Author |
-|------|--------|--------|--------|
-| [Date] | [What changed] | [Why] | [Who] |
-
-## Notes
-[Additional context, assumptions, or considerations]
-

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

@@ -1,120 +0,0 @@
-# Review: [Feature/Project Name]
-
-## Summary
-
-[1-3 sentences: what was built, how many phases, net outcome.]
-
-## Spec Compliance
-
-- [x] AC1: [Description] (Phase N)
-- [x] AC2: [Description] (Phase N)
-- [ ] ACn: [Not met — reason]
-
-## Deviations from Plan
-
-- **Phase N**: [What changed and why]
-
-## Key Metrics
-
-- **Commits**: [N] on the branch
-- **Tests**: [N] passing ([N] existing + [N] new)
-- **Files created**: [list]
-- **Files deleted**: [list]
-- **Net LOC impact**: [+/-N lines]
-
-## Timelog
-
-All times [timezone], [date range].
-
-| Time | Event |
-|------|-------|
-| HH:MM | First commit: [description] |
-| HH:MM | [Phase/milestone] |
-| — | **GATE: [gate-name]** (human approval required) |
-| HH:MM | Implementation begins |
-| HH:MM | Phase N complete after N iterations |
-| HH:MM | **GATE: pr** |
-
-### Autonomous Operation
-
-| Period | Duration | Activity |
-|--------|----------|----------|
-| Spec + Plan | ~Nm | [Summary] |
-| 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): **Xh Ym**
-**Total autonomous work time** (excluding gate waits): **~Xh Ym**
-**Context window resets**: [N] (resumed automatically / required manual restart)
-
-## Consultation Iteration Summary
-
-[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT.
-
-| Phase | Iters | Who Blocked | What They Caught |
-|-------|-------|-------------|------------------|
-| Specify | N | [Model] | [Brief description] |
-| Plan | N | [Model] | [Brief description] |
-| Phase 1 | N | [Model] | [Brief description] |
-| Phase N | N | [Model] | [Brief description] |
-| Review | N | [Model] | [Brief description] |
-
-**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern].
-
-### Avoidable Iterations
-
-Iterations that could have been prevented with better builder behavior:
-
-1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."]
-
-2. **[Pattern]**: [Another avoidable iteration pattern.]
-
-## Consultation Feedback
-
-[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."]
-
-### [Phase] Phase (Round N)
-
-#### Gemini
-- **Concern**: [Summary of concern]
-  - **Addressed**: [What was changed]
-
-#### Codex
-- **Concern**: [Summary of concern]
-  - **Rebutted**: [Why current approach is correct]
-
-#### Claude
-- No concerns raised (APPROVE)
-
-## Lessons Learned
-
-### What Went Well
-- [Specific positive observation — what worked and why]
-
-### Challenges Encountered
-- **[Challenge]**: [How it was resolved. How many iterations it cost.]
-
-### What Would Be Done Differently
-- [Actionable improvement for future builders]
-
-## Architecture Updates
-
-[What you routed where — HOT `codev/resources/arch-critical.md` (tiny, capped, always-injected) vs COLD `codev/resources/arch.md` (reference) — or why no changes were needed.]
-
-- Routed: [hot | cold] — [fact/section] — [what was added/changed; note any demotion if the hot file was full]
-- Or: "No architecture updates needed — [brief reason]"
-
-## Lessons Learned Updates
-
-[What you routed where — HOT `codev/resources/lessons-critical.md` (capped) vs COLD `codev/resources/lessons-learned.md` (reference) — or why no changes were needed.]
-
-- Routed: [hot | cold] — [category] — [lesson summary]
-- Or: "No lessons learned updates needed — [brief reason]"
-
-## Technical Debt
-
-- [Any shortcuts taken or inconsistencies introduced]
-
-## Follow-up Items
-
-- [Items identified for future work, outside this spec's scope]

package/skeleton/protocols/aspir/templates/spec.md

@@ -1,154 +0,0 @@
-# Specification: [Title]
-
-<!--
-SPEC vs PLAN BOUNDARY:
-This spec defines WHAT and WHY. The plan defines HOW and WHEN.
-
-DO NOT include in this spec:
-- Implementation phases or steps
-- File paths to modify
-- Code examples or pseudocode
-- "First we will... then we will..."
-
-These belong in codev/plans/XXXX-*.md
--->
-
-## Metadata
-- **ID**: spec-[YYYY-MM-DD]-[short-name]
-- **Status**: draft
-- **Created**: [YYYY-MM-DD]
-
-## Clarifying Questions Asked
-<!-- Document the questions you asked the user/stakeholder and their answers -->
-[List the questions you asked to understand the problem better and the responses received. This shows the discovery process.]
-
-## Problem Statement
-[Clearly articulate the problem being solved. Include context about why this is important, who is affected, and what the current pain points are.]
-
-## Current State
-[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.]
-
-## Desired State
-[Describe the ideal solution. How should things work after implementation? What specific improvements will users see?]
-
-## Stakeholders
-- **Primary Users**: [Who will directly use this feature?]
-- **Secondary Users**: [Who else is affected?]
-- **Technical Team**: [Who will implement and maintain this?]
-- **Business Owners**: [Who has decision authority?]
-
-## Success Criteria
-- [ ] [Specific, measurable criterion 1]
-- [ ] [Specific, measurable criterion 2]
-- [ ] [Specific, measurable criterion 3]
-- [ ] All tests pass with >90% coverage
-- [ ] Performance benchmarks met (specify below)
-- [ ] Documentation updated
-
-## Constraints
-### Technical Constraints
-- [Existing system limitations]
-- [Technology stack requirements]
-- [Integration points]
-
-### Business Constraints
-- [Timeline requirements]
-- [Budget considerations]
-- [Compliance requirements]
-
-## Assumptions
-- [List assumptions being made]
-- [Include dependencies on other work]
-- [Note any prerequisites]
-
-## Solution Approaches
-
-### Approach 1: [Name]
-**Description**: [Brief overview of this approach]
-
-**Pros**:
-- [Advantage 1]
-- [Advantage 2]
-
-**Cons**:
-- [Disadvantage 1]
-- [Disadvantage 2]
-
-**Estimated Complexity**: [Low/Medium/High]
-**Risk Level**: [Low/Medium/High]
-
-### Approach 2: [Name]
-[Repeat structure for additional approaches]
-
-[Add as many approaches as appropriate for the problem]
-
-## Open Questions
-
-### Critical (Blocks Progress)
-- [ ] [Question that must be answered before proceeding]
-
-### Important (Affects Design)
-- [ ] [Question that influences technical decisions]
-
-### Nice-to-Know (Optimization)
-- [ ] [Question that could improve the solution]
-
-## Performance Requirements
-- **Response Time**: [e.g., <200ms p95]
-- **Throughput**: [e.g., 1000 requests/second]
-- **Resource Usage**: [e.g., <500MB memory]
-- **Availability**: [e.g., 99.9% uptime]
-
-## Security Considerations
-- [Authentication requirements]
-- [Authorization model]
-- [Data privacy concerns]
-- [Audit requirements]
-
-## Test Scenarios
-### Functional Tests
-1. [Scenario 1: Happy path]
-2. [Scenario 2: Edge case]
-3. [Scenario 3: Error condition]
-
-### Non-Functional Tests
-1. [Performance test scenario]
-2. [Security test scenario]
-3. [Load test scenario]
-
-## Dependencies
-- **External Services**: [List any external APIs or services]
-- **Internal Systems**: [List internal dependencies]
-- **Libraries/Frameworks**: [List required libraries]
-
-## References
-- [Link to relevant documentation in codev/ref/]
-- [Link to related specifications]
-- [Link to architectural diagrams]
-- [Link to research materials]
-
-## Risks and Mitigation
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|------------|--------|-------------------|
-| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] |
-| [Risk 2] | Low/Med/High | Low/Med/High | [How to address] |
-
-## Expert Consultation
-<!-- Only if user requested multi-agent consultation -->
-**Date**: [YYYY-MM-DD]
-**Models Consulted**: [e.g., GPT-5 and Gemini Pro]
-**Sections Updated**:
-- [Section name]: [Brief description of change based on consultation]
-- [Section name]: [Brief description of change based on consultation]
-
-Note: All consultation feedback has been incorporated directly into the relevant sections above.
-
-## Approval
-- [ ] Technical Lead Review
-- [ ] Product Owner Review
-- [ ] Stakeholder Sign-off
-- [ ] Expert AI Consultation Complete
-
-## Notes
-[Any additional context or considerations not covered above]
-