fraim-framework 2.0.44 → 2.0.45

package/bin/fraim.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM CLI Entry Point

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

@@ -0,0 +1,73 @@
+# Phase: Design-Completeness-Review
+
+## INTENT
+To verify that the technical design addresses all aspects of the functional specification, including the validation plan and testing strategy.
+
+## OUTCOME
+Confirmation that:
+- Design addresses all functional spec requirements
+- Validation plan from spec is reflected in design
+- Testing strategy covers all specified scenarios
+- Technical approach enables spec validation
+- Design is ready for implementation
+
+## WORKFLOW
+
+### Step 1: Load Functional Specification
+- Read the functional specification document from `docs/feature specs/{issue_number}-*.md`
+- Extract all requirements, user workflows, and validation criteria
+- Note any UI mockups and interaction patterns
+
+### Step 2: Verify Spec Requirements Coverage
+- Check that design addresses each functional requirement
+- Confirm technical approach supports all user workflows from spec
+- Verify API design enables the specified user experience
+- Ensure data models support all spec requirements
+
+### Step 3: Validation Plan Alignment
+**Critical**: The spec's validation plan must be implementable with this design
+- Review validation scenarios from functional spec
+- Confirm design provides necessary APIs/interfaces for validation
+- Check that testing strategy covers all validation scenarios
+- Verify design enables browser testing (if UI changes)
+- Ensure backend validation points are accessible
+
+### Step 4: Technical Feasibility Check
+- Confirm design is technically sound and implementable
+- Check that all spec requirements can be built with this approach
+- Verify integration points are well-defined
+- Assess if design enables the spec's success criteria
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ All functional spec requirements addressed in design
+- ✅ Validation plan from spec is implementable with this design
+- ✅ Testing strategy covers all spec scenarios
+- ✅ Technical approach is sound and feasible
+- ✅ Design enables spec success criteria
+- ✅ Ready for implementation phase
+
+### Phase Incomplete If:
+- ❌ Functional spec requirements not addressed
+- ❌ Validation plan not implementable with current design
+- ❌ Testing strategy insufficient for spec scenarios
+- ❌ Technical approach infeasible or unclear
+- ❌ Design doesn't enable spec success criteria
+
+### Report Back:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "design-completeness-review", 
+  status: "complete",
+  evidence: {
+    specRequirementsCovered: true,
+    validationPlanImplementable: true,
+    testingStrategySufficient: true,
+    technicallyFeasible: true,
+    functionalSpecPath: "docs/feature specs/{issue_number}-*.md"
+  }
+})
+```

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

@@ -0,0 +1,145 @@
+# Phase: Design-Design
+
+## INTENT
+To create a comprehensive technical design that translates the feature specification into implementable architecture, APIs, and technical solutions.
+
+## OUTCOME
+A complete technical design document that:
+- Translates spec requirements into technical architecture
+- Defines APIs, data models, and system interactions
+- Identifies technical risks and mitigation strategies
+- Provides clear implementation guidance
+- Includes technical validation criteria
+
+## PRINCIPLES
+- **Spec-Driven**: Design directly addresses specification requirements
+- **Implementation-Ready**: Provides clear technical guidance
+- **Risk-Aware**: Identifies and mitigates technical risks
+- **Validation-Focused**: Includes technical validation criteria
+- **Template-Compliant**: Follows RFC template structure
+
+## WORKFLOW
+
+### Step 1: Get Repository Context and Issue Details
+
+**GitHub Repository Context**: Before using GitHub MCP tools, read the local `.fraim/config.json` file to get the repository context:
+- Use `git.repoOwner` for the GitHub repository owner
+- Use `git.repoName` for the GitHub repository name
+- These values are required for GitHub MCP API calls (owner/repo parameters)
+
+**Read Issue Details**: Use GitHub MCP tools to get the complete issue information:
+- Read the full issue description, title, and labels
+- Check for linked documents (specs, RFCs, design docs)
+- Review any comments or discussion threads
+- Note acceptance criteria and requirements
+- Identify if there's an existing specification document
+
+### Step 2: Load Template and Specification
+- Call `get_fraim_file({ path: "templates/specs/TECHSPEC-TEMPLATE.md" })` (for features)
+- Call `get_fraim_file({ path: "templates/specs/BUGSPEC-TEMPLATE.md" })` (for bugs)
+- Read the completed specification document from previous phase
+- Call `get_fraim_file({ path: "rules/spike-first-development.md" })`
+
+### Step 3: Check for PR Feedback
+
+**CRITICAL**: Before creating design, check for feedback:
+- **PR Review Feedback**: `docs/evidence/{issue_number}-design-feedback.md`
+
+**If PR feedback exists:**
+- **MUST address all UNADDRESSED items** before proceeding
+- Update feedback file after addressing each item
+- Change status from UNADDRESSED to ADDRESSED with resolution details
+- Cannot skip or defer feedback items
+- Phase cannot complete until all feedback is addressed
+
+**PR Feedback File Format** (if exists):
+```markdown
+### Comment X - ADDRESSED
+- **Author**: reviewer_name
+- **Comment**: Original feedback
+- **Status**: ADDRESSED
+- **Resolution**: How you addressed this feedback
+```
+
+### Step 4: Analyze Specification Requirements
+- Extract all technical requirements from specification
+- Identify system components that need modification
+- Determine API changes or additions needed
+- Note any performance or scalability considerations
+- List integration points with existing systems
+
+### Step 5: Create Technical Design Document
+- Create RFC file at `docs/rfcs/{issue_number}-{kebab-case-title}.md`
+- Follow appropriate template structure (TECHSPEC or BUGSPEC)
+- Include all required sections:
+  - Problem statement (from spec)
+  - Technical requirements
+  - Proposed solution architecture
+  - API design and data models
+  - Implementation plan
+  - Testing strategy
+  - Risk assessment and mitigation
+  - Alternative approaches considered
+
+### Step 6: Design System Architecture
+- Define component interactions and data flow
+- Specify API endpoints and request/response formats
+- Design database schema changes (if needed)
+- Plan integration with existing systems
+- Consider scalability and performance implications
+
+### Step 7: Identify Technical Risks
+- List unfamiliar technologies or patterns
+- Note complex integrations or dependencies
+- Identify performance bottlenecks
+- Consider security implications
+- Plan risk mitigation strategies
+
+### Step 8: Apply Labels
+- Label the GitHub issue with `phase:design`
+- This will trigger automatic PR creation/update
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Technical design document created using appropriate template
+- ✅ All specification requirements addressed technically
+- ✅ System architecture clearly defined
+- ✅ API design and data models specified
+- ✅ Technical risks identified and mitigation planned
+- ✅ Implementation plan provides clear guidance
+- ✅ Testing strategy defined
+- ✅ **PR feedback addressed** (if `docs/evidence/{issue_number}-design-feedback.md` exists)
+- ✅ Issue labeled with `phase:design`
+
+### Phase Incomplete If:
+- ❌ Design document missing or incomplete
+- ❌ Template structure not followed
+- ❌ Specification requirements not addressed
+- ❌ Architecture unclear or missing
+- ❌ Technical risks not identified
+- ❌ Implementation guidance insufficient
+- ❌ **PR feedback not addressed** (UNADDRESSED items remain in feedback file)
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "design-design", 
+  status: "complete",
+  evidence: {
+    designDocument: "docs/rfcs/{issue_number}-{title}.md",
+    templateUsed: "TECHSPEC-TEMPLATE.md",
+    architectureComponents: ["API layer", "Database schema", "UI components"],
+    technicalRisks: ["Integration with legacy system", "Performance at scale"],
+    issueLabeled: "phase:design"
+  },
+  findings: {
+    keyDecisions: ["Use REST API", "PostgreSQL for data storage", "React components"],
+    riskMitigation: ["Spike legacy integration", "Load testing plan"]
+  }
+})
+```

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

@@ -0,0 +1,108 @@
+# Phase: Design
+
+## INTENT
+To create a comprehensive technical design that translates the feature specification into implementable architecture, APIs, and technical solutions.
+
+## OUTCOME
+A complete technical design document that:
+- Translates spec requirements into technical architecture
+- Defines APIs, data models, and system interactions
+- Identifies technical risks and mitigation strategies
+- Provides clear implementation guidance
+- Includes technical validation criteria
+
+## PRINCIPLES
+- **Spec-Driven**: Design directly addresses specification requirements
+- **Implementation-Ready**: Provides clear technical guidance
+- **Risk-Aware**: Identifies and mitigates technical risks
+- **Validation-Focused**: Includes technical validation criteria
+- **Template-Compliant**: Follows RFC template structure
+
+## WORKFLOW
+
+### Step 1: Load Template and Specification
+- Call `get_fraim_file({ path: "templates/specs/TECHSPEC-TEMPLATE.md" })` (for features)
+- Call `get_fraim_file({ path: "templates/specs/BUGSPEC-TEMPLATE.md" })` (for bugs)
+- Read the completed specification document from previous phase
+- Call `get_fraim_file({ path: "rules/spike-first-development.md" })`
+
+### Step 2: Analyze Specification Requirements
+- Extract all technical requirements from specification
+- Identify system components that need modification
+- Determine API changes or additions needed
+- Note any performance or scalability considerations
+- List integration points with existing systems
+
+### Step 3: Create Technical Design Document
+- Create RFC file at `docs/rfcs/{issue_number}-{kebab-case-title}.md`
+- Follow appropriate template structure (TECHSPEC or BUGSPEC)
+- Include all required sections:
+  - Problem statement (from spec)
+  - Technical requirements
+  - Proposed solution architecture
+  - API design and data models
+  - Implementation plan
+  - Testing strategy
+  - Risk assessment and mitigation
+  - Alternative approaches considered
+
+### Step 4: Design System Architecture
+- Define component interactions and data flow
+- Specify API endpoints and request/response formats
+- Design database schema changes (if needed)
+- Plan integration with existing systems
+- Consider scalability and performance implications
+
+### Step 5: Identify Technical Risks
+- List unfamiliar technologies or patterns
+- Note complex integrations or dependencies
+- Identify performance bottlenecks
+- Consider security implications
+- Plan risk mitigation strategies
+
+### Step 6: Apply Labels
+- Label the GitHub issue with `phase:design`
+- This will trigger automatic PR creation/update
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Technical design document created using appropriate template
+- ✅ All specification requirements addressed technically
+- ✅ System architecture clearly defined
+- ✅ API design and data models specified
+- ✅ Technical risks identified and mitigation planned
+- ✅ Implementation plan provides clear guidance
+- ✅ Testing strategy defined
+- ✅ Issue labeled with `phase:design`
+
+### Phase Incomplete If:
+- ❌ Design document missing or incomplete
+- ❌ Template structure not followed
+- ❌ Specification requirements not addressed
+- ❌ Architecture unclear or missing
+- ❌ Technical risks not identified
+- ❌ Implementation guidance insufficient
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "design", 
+  status: "complete",
+  evidence: {
+    designDocument: "docs/rfcs/{issue_number}-{title}.md",
+    templateUsed: "TECHSPEC-TEMPLATE.md",
+    architectureComponents: ["API layer", "Database schema", "UI components"],
+    technicalRisks: ["Integration with legacy system", "Performance at scale"],
+    issueLabeled: "phase:design"
+  },
+  findings: {
+    keyDecisions: ["Use REST API", "PostgreSQL for data storage", "React components"],
+    riskMitigation: ["Spike legacy integration", "Load testing plan"]
+  }
+})
+```

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

@@ -0,0 +1,60 @@
+# Phase: Finalize
+
+## INTENT
+To prepare completed work for human review by setting proper labels, creating/updating PR, and documenting evidence.
+
+## OUTCOME
+Work is ready for human review with:
+- Proper issue labels applied
+- PR created/updated with work
+- Evidence documented
+- Clean handoff to next phase or review
+
+## WORKFLOW
+
+### Step 1: Apply Issue Labels
+- Remove current phase label (e.g., `phase:spec`, `phase:design`, `phase:impl`)
+- Add `status:needs-review` label
+- Keep any other relevant labels
+
+### Step 2: Create/Update Pull Request
+- Ensure PR exists for the feature branch
+- Update PR title to reflect completed work
+- Update PR description with summary of work completed
+- Link to relevant documents (specs, designs, evidence)
+
+### Step 3: Document Evidence
+- Create evidence file at `docs/evidence/{issue_number}-{workflow}-evidence.md`
+- Document key decisions made
+- List deliverables created
+- Note any recommendations for next phase
+
+### Step 4: Prepare Handoff
+- Ensure all work is committed to git
+- Verify documentation is complete
+- Confirm work is ready for human review
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Issue labels updated (`status:needs-review`)
+- ✅ PR created/updated with work summary
+- ✅ Evidence documented
+- ✅ All work committed to git
+- ✅ Ready for human review
+
+### Report Back:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "finalize", 
+  status: "complete",
+  evidence: {
+    labelsApplied: ["status:needs-review"],
+    prUpdated: true,
+    evidenceDocumented: "docs/evidence/{issue_number}-{workflow}-evidence.md",
+    workCommitted: true
+  }
+})
+```

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"
+  }
+})
+```