fraim-framework 2.0.65 → 2.0.67

package/dist/registry/ai-manager-rules/design-phases/validate.md

@@ -0,0 +1,125 @@
+# Phase: Validate (Design)
+
+## INTENT
+To systematically validate that the technical design is complete, addresses all specification requirements, and provides clear implementation guidance.
+
+## OUTCOME
+Confirmation that:
+- Design addresses all specification requirements
+- Technical architecture is sound and implementable
+- APIs and data models are well-defined
+- Technical risks are identified and mitigated
+- Implementation guidance is clear and actionable
+
+## PRINCIPLES
+- **Spec Alignment**: Design must address all specification requirements
+- **Technical Soundness**: Architecture must be feasible and scalable
+- **Implementation Ready**: Clear guidance for development phase
+- **Risk Awareness**: Technical risks identified and mitigated
+- **Quality Standards**: Professional-grade design ready for implementation
+
+## WORKFLOW
+
+### Step 1: Load Specification and Design
+- Read the original specification document
+- Read the completed design document
+- Call `get_fraim_workflow({ workflow: "review-implementation-vs-design-spec" })`
+
+### Step 2: Execute Design Validation Checklist
+
+**Specification Alignment:**
+1. **Requirements Coverage**: All spec requirements addressed in design
+2. **Customer Needs**: Design supports all customer desired outcomes
+3. **User Experience**: Technical design enables specified user workflows
+4. **Validation Plan**: Design supports spec validation criteria
+
+**Technical Soundness:**
+5. **Architecture Clarity**: System components and interactions clearly defined
+6. **API Design**: Endpoints, request/response formats well-specified
+7. **Data Models**: Database schema and data structures defined
+8. **Integration Points**: External system interactions documented
+9. **Scalability**: Performance and scaling considerations addressed
+
+**Implementation Readiness:**
+10. **Implementation Plan**: Clear step-by-step development guidance
+11. **Testing Strategy**: Comprehensive testing approach defined
+12. **Technical Risks**: Risks identified with mitigation strategies
+13. **Alternative Analysis**: Other approaches considered and rejected
+
+**Quality Standards:**
+14. **Template Compliance**: Follows TECHSPEC/BUGSPEC template structure
+15. **Professional Quality**: Clear writing, proper formatting, complete sections
+
+### Step 3: Risk Assessment Review
+- Verify all technical risks are realistic and significant
+- Confirm mitigation strategies are actionable
+- Check if any risks require spikes or prototypes
+- Assess overall project feasibility
+
+### Step 4: Implementation Guidance Review
+- Ensure implementation plan is detailed enough
+- Verify testing strategy covers all requirements
+- Check that guidance addresses potential challenges
+- Confirm design enables spec validation plan
+
+### Step 5: Generate Validation Report
+Document findings for each validation area:
+- Specification alignment assessment
+- Technical soundness evaluation
+- Implementation readiness review
+- Quality standards compliance
+- Overall recommendation
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ All specification requirements addressed in design
+- ✅ Technical architecture is sound and implementable
+- ✅ APIs and data models clearly defined
+- ✅ Technical risks identified with mitigation plans
+- ✅ Implementation guidance is clear and actionable
+- ✅ Quality standards met consistently
+- ✅ Validation report generated with evidence
+
+### Phase Incomplete If:
+- ❌ Specification requirements not fully addressed
+- ❌ Technical architecture unclear or infeasible
+- ❌ API design incomplete or poorly defined
+- ❌ Technical risks not identified or mitigated
+- ❌ Implementation guidance insufficient
+- ❌ Quality issues identified
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "validate", 
+  status: "complete",
+  evidence: {
+    validationReport: "All specification requirements addressed, architecture sound",
+    specAlignmentScore: "100% - all requirements covered",
+    technicalSoundness: "PASS - architecture feasible and scalable",
+    implementationReadiness: "PASS - clear guidance provided",
+    qualityAssessment: "Professional grade, ready for implementation",
+    validationDecision: "PASS"
+  }
+})
+```
+
+If validation fails:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "validate", 
+  status: "incomplete",
+  findings: {
+    failedAreas: ["API design incomplete", "Technical risks not mitigated"],
+    validationDecision: "FAIL",
+    nextAction: "Return to design phase to address validation failures"
+  }
+})
+```

package/dist/registry/ai-manager-rules/design.json

@@ -0,0 +1,97 @@
+{
+  "workflowType": "design",
+  "description": "Design phase validation ensures that technical designs are complete, follow RFC format, and provide clear implementation guidance.",
+  "validationRules": [
+    {
+      "step": 1,
+      "description": "Verify issue is labeled with phase:design",
+      "passCriteria": "Issue has 'phase:design' label applied",
+      "weight": "blocking",
+      "category": "process"
+    },
+    {
+      "step": 2,
+      "description": "Verify RFC document exists in correct location",
+      "command": "find \"docs/rfcs\" -name \"*{issue_number}*\" -type f",
+      "passCriteria": "RFC document exists at docs/rfcs/{issue_number}-{kebab-title}.md with substantial content (>1500 characters)",
+      "weight": "blocking",
+      "category": "completeness"
+    },
+    {
+      "step": 3,
+      "description": "Check RFC follows technical design template structure",
+      "passCriteria": "RFC includes all required sections: Problem Statement, Solution Overview, Technical Design, Implementation Plan, Testing Strategy, Risks and Mitigations",
+      "weight": "blocking",
+      "category": "structure"
+    },
+    {
+      "step": 4,
+      "description": "Validate Problem Statement is clear",
+      "passCriteria": "Problem Statement clearly defines the technical challenge and why it needs to be solved",
+      "weight": "blocking",
+      "category": "problem-definition"
+    },
+    {
+      "step": 5,
+      "description": "Validate Solution Overview provides clear direction",
+      "passCriteria": "Solution Overview describes the high-level approach and key architectural decisions",
+      "weight": "blocking",
+      "category": "solution-design"
+    },
+    {
+      "step": 6,
+      "description": "Check Technical Design has sufficient detail",
+      "passCriteria": "Technical Design includes API contracts, data models, component interactions, and implementation details",
+      "weight": "blocking",
+      "category": "technical-detail"
+    },
+    {
+      "step": 7,
+      "description": "Validate Implementation Plan is actionable",
+      "passCriteria": "Implementation Plan breaks down work into clear, executable steps with dependencies identified",
+      "weight": "blocking",
+      "category": "implementation-planning"
+    },
+    {
+      "step": 8,
+      "description": "Check Testing Strategy is comprehensive",
+      "passCriteria": "Testing Strategy covers unit tests, integration tests, and validation scenarios",
+      "weight": "blocking",
+      "category": "testing"
+    },
+    {
+      "step": 9,
+      "description": "Verify Risks and Mitigations are identified",
+      "passCriteria": "Risks and Mitigations section identifies potential issues and mitigation strategies",
+      "weight": "warning",
+      "category": "risk-management"
+    },
+    {
+      "step": 10,
+      "description": "Check all requirements from spec are addressed",
+      "passCriteria": "All requirements from the specification document are covered in the technical design",
+      "weight": "blocking",
+      "category": "completeness"
+    }
+  ],
+  "gradingCriteria": {
+    "passRequirements": [
+      "ALL blocking validation steps must pass",
+      "At least 80% of warning validation steps should pass",
+      "Design demonstrates clear technical understanding",
+      "Implementation plan is realistic and actionable",
+      "No placeholder text or incomplete sections remain"
+    ],
+    "failRequirements": [
+      "ANY blocking validation step fails",
+      "Multiple warning validation steps fail indicating quality issues",
+      "Design appears incomplete or lacks technical depth",
+      "Requirements not properly addressed",
+      "Template structure not followed"
+    ]
+  },
+  "reportingFormat": {
+    "requiredFields": ["pass", "reasons"],
+    "instructions": "Evaluate each validation step honestly. If ANY blocking step fails, you must report pass=false. Provide specific reasons for failure in the reasons array. Focus on technical completeness and implementation clarity."
+  }
+}

package/dist/registry/ai-manager-rules/implement-phases/code.md

@@ -0,0 +1,323 @@
+# Phase: Code
+
+## INTENT
+To write the minimal, testable code needed to fix the bug or implement the feature, following approved designs and established patterns.
+
+## OUTCOME
+Working implementation that:
+- Fixes the bug or implements the feature
+- Follows approved design/RFC
+- Includes comprehensive tests
+- Maintains code quality
+- Is ready for validation
+
+## 🎯 SUCCESS MINDSET
+
+**Your Goal**: Working application that users can actually use, not just passing tests.
+
+**Critical Success Factors**:
+- 🔍 **Manual validation is MANDATORY** - You WILL test in browser/API/CLI manually
+- ⚠️ **Every error must be investigated** - No assumptions, no "that's probably fine"
+- 🚫 **No placeholder code** - Implement complete solutions, no TODOs or "for now" comments
+- 📊 **100% test success required** - 91% is failure, 99% is failure, only 100% is success
+- 🏗️ **Prototype-first** - Build simplest end-to-end solution, then engineer it properly
+
+## RULES FOR THIS PHASE
+
+### Success Criteria
+Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus especially on:
+- **Integrity** (never claim tests pass if you didn't run them)
+- **Correctness** (follow architecture, tests must pass, no `any` types)
+- **Completeness** (implement everything in the issue description)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Critical for coding phase:
+- **Prototype-First Development**: Build simplest solution that works end-to-end, validate manually, then engineer correctly
+- **Manual Validation Required**: Test with browser/curl before creating automated tests
+- **Resource Waste Prevention**: Maximum 2 retries for expensive operations
+- **NEVER use placeholder comments** like "For now", "TODO", "FIXME"
+
+### Architecture Compliance
+Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full architecture guidelines. Follow all architectural standards - no shortcuts.
+
+### Git Operations (if needed)
+When using git commands directly (if MCP tools unavailable), read `registry/rules/git-safe-commands.md` via `get_fraim_file` to avoid interactive commands that hang agents.
+
+## PRINCIPLES
+- **Design-Driven**: Follow approved RFCs and design documents
+- **Minimal Implementation**: Write only code needed for this issue
+- **Test-First**: Write tests before or alongside implementation
+- **Quality Focus**: Maintain code quality and follow patterns
+- **Complete**: All aspects of design/spec implemented
+
+## 📋 ENHANCED WORKFLOW
+
+### Step 1: Prototype-First Development
+
+**Build Simplest End-to-End Solution**:
+- Focus on getting something working, not perfect
+- Don't worry about code quality initially
+- Prove the approach works before optimizing
+- Get basic functionality working first
+
+**Manual Validation (CRITICAL)**:
+- Test every step manually using browser/curl/CLI
+- Verify each acceptance criteria works
+- Take screenshots/capture output as evidence
+- Fix any issues found immediately
+
+### Step 2: Review Design/Spec
+
+**For Bugs:**
+- Review bug description and repro test
+- Understand root cause
+- Plan minimal fix
+
+**For Features:**
+- Review approved RFC/design document
+- Review spike/POC findings (if applicable)
+- Understand all acceptance criteria
+- Plan implementation approach
+
+### Step 3: Check for Design Feedback
+
+**CRITICAL**: Before implementing, check for feedback:
+- Design Review Feedback: `docs/evidence/{issue_number}-design-reviewer-feedback.md`
+- Feature Review Feedback: `docs/evidence/{issue_number}-feature-reviewer-feedback.md`
+
+**If feedback exists:**
+- **MUST address all items** before proceeding
+- Update evidence document after addressing
+- Cannot skip or defer feedback items
+
+### Step 4: Implement Changes
+
+**For Bugs:**
+- Make minimal changes to fix the issue
+- Focus on root cause, not symptoms
+- Avoid unrelated changes
+- Keep diff small and focused
+
+**For Features:**
+- Implement all aspects from design/spec
+- Follow existing patterns and architecture
+- Create necessary files/modules
+- Implement all API contracts
+- Implement all data models
+- Implement all user interfaces
+- No placeholder code for core functionality
+
+### Step 5: Fix All Errors (MANDATORY)
+
+**Error Investigation Requirements**:
+- **Every error in logs must be investigated**
+- **No error is "expected" until proven**
+- **Fix root causes, not symptoms**
+- **Document why any remaining errors are acceptable**
+
+**Common Error Sources**:
+- Server startup errors
+- API connection errors
+- Database connection errors
+- TypeScript compilation errors
+- Test execution errors
+
+### Step 6: Write Comprehensive Tests
+
+**MANDATORY**: Every issue requires tests - no exceptions.
+
+**For Bugs:**
+- Verify repro test from repro phase now passes
+- Add additional edge case tests if needed
+- Ensure tests cover the fix
+
+**For Features:**
+- Write tests for all acceptance criteria
+- Test main user scenarios
+- Test edge cases
+- Test error conditions
+- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full test architecture standards
+
+**Test Requirements:**
+- Use shared-server-utils.ts for server tests
+- Unique API keys per test
+- Proper cleanup in finally blocks
+- No individual server instances
+- Proper timeouts (5-10s for network calls)
+- Tests must validate real functionality, not mocks
+- No tests that default to passing
+
+**Test Tagging Guidelines:**
+Tag tests appropriately to ensure proper test suite execution:
+
+- **`smoke`**: Tag tests as "smoke" if they verify:
+  - Core system functionality (CLI commands, server startup, basic workflows)
+  - Critical user journeys (init, sync, basic operations)
+  - Integration points between major components
+  - Functionality that, if broken, would make the system unusable
+
+- **`integration`**: Tests that verify multiple components working together
+- **`unit`**: Tests that verify individual functions or classes in isolation
+- **`e2e`**: End-to-end tests that verify complete user workflows
+
+**Smoke Test Execution Rules:**
+If ANY tests are tagged "smoke" or you're modifying core functionality:
+1. **MANDATORY**: Run full smoke test suite: `npm run test-smoke-ci`
+2. **MANDATORY**: Include smoke test output in evidence
+3. **MANDATORY**: All smoke tests must pass before proceeding
+4. **BLOCKING**: Smoke test failures block phase completion
+
+### Step 7: Run All Tests (100% Success Required)
+
+**Execute all tests:**
+```bash
+npm test -- path/to/test.test.ts
+```
+
+**Verify:**
+- All tests pass (100%, not 91% or 99%)
+- No timeouts
+- No errors
+- Tests fail if code is broken (validate this)
+
+**If ANY tests fail:**
+- **STOP** - Do not proceed
+- Investigate failure thoroughly
+- Fix the issue
+- Re-run tests
+- Only proceed when 100% pass
+
+### Step 8: TypeScript Compilation
+
+```bash
+npx tsc --noEmit --skipLibCheck
+```
+
+**Must exit with code 0** (no errors)
+
+If compilation fails:
+- Fix errors
+- Re-compile
+- Iterate until clean
+
+### Step 9: Final Manual Validation (CRITICAL)
+
+**Trust, but Verify:**
+- Do not rely solely on automated tests
+- Inspect generated artifacts manually
+- Verify content looks correct
+- Check for placeholders or errors
+
+**For UI changes:**
+- Start dev server
+- Navigate to changed UI
+- Verify visual correctness
+- Test user interactions
+- Take screenshots as evidence
+
+**For API changes:**
+- Test with curl or similar
+- Verify request/response formats
+- Test error handling
+- Capture API responses as evidence
+
+**For CLI changes:**
+- Run commands manually
+- Verify output correctness
+- Test various inputs
+- Capture command output as evidence
+
+## 📸 EVIDENCE REQUIREMENTS
+
+You MUST provide concrete evidence for all claims:
+
+1. **Screenshots**: Application working in browser/UI
+2. **Test Output**: Complete test suite results (100% pass)
+3. **Server Logs**: Clean startup with no errors
+4. **API Responses**: Curl/Postman output for API changes
+5. **Manual Validation**: Step-by-step verification of acceptance criteria
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Implementation complete per design/spec
+- ✅ (Bugs) Minimal, focused changes
+- ✅ (Features) All design aspects implemented
+- ✅ Tests written and passing (100%)
+- ✅ TypeScript compiles cleanly
+- ✅ Manual validation successful with evidence
+- ✅ Design feedback addressed (if applicable)
+- ✅ All errors investigated and resolved
+- ✅ Evidence provided for all claims
+
+### Phase Incomplete If:
+- ❌ Design/spec not fully implemented
+- ❌ No tests written
+- ❌ ANY tests fail (even 1 out of 100)
+- ❌ TypeScript compilation errors
+- ❌ Manual validation reveals issues
+- ❌ Design feedback not addressed
+- ❌ Errors in logs not investigated
+- ❌ Missing evidence for claims
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "code", 
+  status: "complete",
+  findings: {
+    evidence: "Brief summary of what you implemented and validated"
+  },
+  evidence: {
+    testOutput: "Complete test output showing 100% pass rate",
+    screenshots: ["Screenshots of working functionality"],
+    serverLogs: ["Clean server startup logs"],
+    manualValidationSteps: [
+      "Step-by-step manual validation performed",
+      "Browser testing results",
+      "API testing results"
+    ],
+    reflectionAnalysis: "Complete 4-phase reflection analysis",
+    claims: [
+      "Specific claims about what works",
+      "All tests pass",
+      "Manual validation complete"
+    ]
+  }
+})
+```
+
+If implementation incomplete, iterate:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "code",
+  status: "incomplete", 
+  findings: {
+    uncertainties: ["Issues encountered", "What needs to be fixed"]
+  }
+})
+```
+```
+
+## SCRIPTS
+
+**Run tests:**
+```bash
+npm test -- path/to/test.test.ts
+```
+
+**Compile TypeScript:**
+```bash
+npx tsc --noEmit --skipLibCheck
+```
+
+**Start dev server (for manual testing):**
+```bash
+npm run dev
+```

package/dist/registry/ai-manager-rules/implement-phases/completeness-review.md

@@ -0,0 +1,94 @@
+# Phase: Completeness Review
+
+## INTENT
+To verify that all design aspects have been implemented and that the work fully addresses the requirements from the design document or issue specification.
+
+## OUTCOME
+Confirmation that:
+- All design aspects implemented
+- All acceptance criteria met
+- Implementation matches design specifications
+- Work is complete and ready for finalization
+
+## PRINCIPLES
+- **Design Fidelity**: Implementation must match design specifications
+- **Complete Coverage**: All design aspects must be addressed
+- **Evidence-Based**: Use existing comprehensive review workflows
+
+## WORKFLOW
+
+### Step 1: Execute Design Review Workflow
+
+Use the comprehensive design validation workflow:
+- Read `registry/workflows/reviewer/review-implementation-vs-design-spec.md` via `get_fraim_file`
+- Follow the complete systematic review process
+- This workflow provides detailed checklists, validation steps, and templates
+- Works for both bugs and features - all should be reviewed against their design spec
+
+### Step 2: Execute Review Workflow
+
+**Follow the design review workflow completely:**
+- Use all the checklists provided
+- Execute all validation steps
+- Create feedback documents using the templates
+- Follow the iteration limits (max 3)
+
+### Step 3: Architecture Compliance
+
+Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then use `get_fraim_file` to read the full architecture guidelines. Verify implementation follows all design standards.
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Appropriate review workflow executed completely
+- ✅ All workflow checklists completed
+- ✅ All design aspects verified per workflow
+- ✅ Evidence quality meets workflow standards
+- ✅ Feedback documents created using workflow templates
+- ✅ Architecture compliance verified
+
+### Phase Incomplete If:
+- ❌ Review workflow not followed completely
+- ❌ Workflow checklists incomplete
+- ❌ Design aspects not verified per workflow standards
+- ❌ Evidence quality insufficient per workflow criteria
+- ❌ Feedback documents missing or not using templates
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "completeness-review", 
+  status: "complete",
+  evidence: {
+    reviewWorkflowUsed: "review-implementation-vs-design-spec", // Which workflow was used
+    workflowChecklistsComplete: "YES", // All checklists from workflow completed?
+    designAspectsVerified: "YES", // All design aspects verified per workflow?
+    evidenceQualityMet: "YES", // Evidence meets workflow standards?
+    feedbackDocumentsCreated: "YES", // Feedback documents created using templates?
+    architectureCompliant: "YES", // Architecture compliance verified?
+    reviewDecision: "APPROVE", // APPROVE/REQUEST_CHANGES/REJECT per workflow
+    summary: "Completed systematic design review using comprehensive workflow. All design aspects verified and documented."
+  }
+})
+```
+
+If review reveals issues:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "completeness-review", 
+  status: "incomplete",
+  evidence: {
+    reviewWorkflowUsed: "review-implementation-vs-design-spec",
+    reviewDecision: "REQUEST_CHANGES", // or "REJECT"
+    issuesFound: ["Missing test case X per workflow checklist", "Design requirement Y not implemented"],
+    feedbackDocumentLocation: "docs/evidence/{issue}-design-reviewer-feedback.md",
+    nextAction: "Implementation agent must address feedback per workflow iteration process"
+  }
+})
+```