fraim-framework 2.0.66 → 2.0.67

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

@@ -0,0 +1,153 @@
+{
+  "workflowType": "implement",
+  "description": "Implementation phase validation ensures that code changes are complete, properly tested with high-quality tests, and ready for production deployment. This phase enforces rigorous testing standards and design completeness.",
+  "validationRules": [
+    {
+      "step": 1,
+      "description": "Verify issue is labeled with phase:implement",
+      "passCriteria": "Issue has 'phase:implement' label applied",
+      "weight": "blocking",
+      "category": "process"
+    },
+    {
+      "step": 2,
+      "description": "Verify all aspects of design are complete",
+      "passCriteria": "All design requirements from spec/RFC are implemented: API contracts, data models, user interfaces, error handling patterns, and integration points. No placeholder code or TODO comments remain for core functionality.",
+      "weight": "blocking",
+      "category": "design-completeness"
+    },
+    {
+      "step": 3,
+      "description": "Verify all test cases from design document are written",
+      "passCriteria": "Every test case specified in the design document/RFC validation plan has a corresponding automated test. Test coverage includes all user scenarios, edge cases, and error conditions outlined in the design.",
+      "weight": "blocking",
+      "category": "test-completeness"
+    },
+    {
+      "step": 4,
+      "description": "Verify all test cases follow architecture standards",
+      "passCriteria": "Tests follow the Shared Server Architecture pattern from docs/architecture/architecture.md: use shared-server-utils.ts, unique API keys per test, proper cleanup in finally blocks, no individual server instances, proper timeouts (5-10s for network calls).",
+      "weight": "blocking",
+      "category": "test-architecture"
+    },
+    {
+      "step": 5,
+      "description": "Verify all test cases have been run and are passing",
+      "passCriteria": "All tests pass successfully. Test output shows 0 failures, 0 timeouts, and all assertions succeed. Tests complete within reasonable time limits (<60s total, <10s per test).",
+      "weight": "blocking",
+      "category": "test-execution"
+    },
+    {
+      "step": 6,
+      "description": "Verify tests do not mock the objects they should be testing",
+      "passCriteria": "Tests validate real functionality, not mocked behavior. Core business logic is tested against actual implementations. Mocks are only used for external dependencies (databases, APIs, file system) not for the code under test.",
+      "weight": "blocking",
+      "category": "test-quality"
+    },
+    {
+      "step": 7,
+      "description": "Verify tests do not default to passing when unable to test",
+      "passCriteria": "No tests contain 'return true' without validation, empty test bodies, or assertions that always pass. Every test performs meaningful validation of expected behavior and will fail if the code is broken.",
+      "weight": "blocking",
+      "category": "test-quality"
+    },
+    {
+      "step": 8,
+      "description": "Verify tests use flow testing instead of static analysis",
+      "passCriteria": "Tests execute actual code paths and validate runtime behavior. Tests call functions, trigger workflows, and verify outcomes. Static analysis (type checking, linting) supplements but does not replace functional testing.",
+      "weight": "blocking",
+      "category": "test-quality"
+    },
+    {
+      "step": 9,
+      "description": "Check TypeScript compilation passes",
+      "command": "npx tsc --noEmit --skipLibCheck",
+      "passCriteria": "TypeScript compilation completes without errors",
+      "weight": "blocking",
+      "category": "code-quality"
+    },
+    {
+      "step": 10,
+      "description": "Check code quality standards",
+      "passCriteria": "No 'as any' type bypassing, proper error handling, consistent code style, meaningful variable names, and appropriate code comments",
+      "weight": "blocking",
+      "category": "code-quality"
+    },
+    {
+      "step": 11,
+      "description": "Verify implementation matches design exactly",
+      "passCriteria": "Implementation follows the technical design/RFC precisely and addresses all specified requirements. API signatures, data structures, and behavior match the design specification.",
+      "weight": "blocking",
+      "category": "design-compliance"
+    },
+    {
+      "step": 12,
+      "description": "Check comprehensive error handling and edge cases",
+      "passCriteria": "Proper error handling implemented for all failure scenarios, edge cases covered with tests, graceful degradation where appropriate, and meaningful error messages",
+      "weight": "blocking",
+      "category": "robustness"
+    },
+    {
+      "step": 13,
+      "description": "Validate API contracts and interfaces",
+      "passCriteria": "All API contracts match specification, proper input validation, consistent response formats, and backward compatibility maintained",
+      "weight": "blocking",
+      "category": "api-compliance"
+    },
+    {
+      "step": 14,
+      "description": "Check security best practices",
+      "passCriteria": "Input sanitization, proper authentication/authorization, no security vulnerabilities, secure handling of sensitive data",
+      "weight": "blocking",
+      "category": "security"
+    },
+    {
+      "step": 15,
+      "description": "Check documentation is updated",
+      "passCriteria": "Code comments, README updates, API documentation, and inline documentation reflect all changes",
+      "weight": "warning",
+      "category": "documentation"
+    },
+    {
+      "step": 16,
+      "description": "Verify performance considerations",
+      "passCriteria": "No obvious performance regressions, efficient algorithms used, proper resource management, and performance tests where applicable",
+      "weight": "warning",
+      "category": "performance"
+    },
+    {
+      "step": 17,
+      "description": "Validate evidence document exists",
+      "command": "find \"docs/evidence\" -name \"*{issue_number}*implementation*\" -type f",
+      "passCriteria": "Implementation evidence document exists with test results, validation details, and proof of all requirements being met",
+      "weight": "warning",
+      "category": "documentation"
+    }
+  ],
+  "gradingCriteria": {
+    "passRequirements": [
+      "ALL blocking validation steps must pass",
+      "At least 80% of warning validation steps should pass",
+      "All design aspects are fully implemented",
+      "All test cases from design document are written and passing",
+      "Tests follow architecture standards and test real functionality",
+      "No tests mock objects under test or default to passing",
+      "Tests use flow testing to validate runtime behavior",
+      "Code is production-ready and maintainable"
+    ],
+    "failRequirements": [
+      "ANY blocking validation step fails",
+      "Design implementation is incomplete",
+      "Test cases from design document are missing",
+      "Tests violate architecture standards",
+      "Tests mock the objects they should be testing",
+      "Tests default to passing without proper validation",
+      "Tests rely on static analysis instead of flow testing",
+      "Code has obvious bugs or security issues"
+    ]
+  },
+  "reportingFormat": {
+    "requiredFields": ["pass", "reasons"],
+    "instructions": "Evaluate each validation step rigorously. Pay special attention to test quality - verify that tests actually test the intended functionality and follow architecture standards. If ANY blocking step fails, you must report pass=false. Focus on design completeness, test quality, and production readiness."
+  }
+}

package/dist/registry/ai-manager-rules/retrospective.md

@@ -0,0 +1,116 @@
+# Phase: Retrospective
+
+## INTENT
+To conduct a comprehensive retrospective of the completed work while full context is available, capturing learnings and insights before branch cleanup and resolution. This phase applies to all workflow types (spec, design, implement, test).
+
+## TRIGGER
+This phase is triggered after PR approval (`wait-for-pr-review` completion) and before `resolve` phase for all workflow types.
+
+## CONTEXT ADVANTAGES
+- **Full Work Context**: All changes, decisions, and challenges are fresh in memory
+- **Branch Available**: Can reference specific commits, diffs, and work artifacts
+- **Problem-Solution Mapping**: Clear connection between original problem and completed solution
+- **Fresh Insights**: Recent experience provides accurate reflection on what worked/didn't work
+- **PR Feedback Available**: Can analyze and learn from user feedback received during review
+- **Complete Journey**: Can analyze entire workflow from start to finish
+
+## WORKFLOW
+
+### Step 1: Retrospective Preparation
+- Ensure PR is approved and ready for merge
+- Gather work artifacts (commits, documents, test results, etc.)
+- Review original issue requirements and acceptance criteria
+- **Collect PR feedback**: Review all comments, suggestions, and feedback received during PR review
+- Analyze user feedback patterns and themes
+- Identify key decision points and challenges encountered
+
+### Step 2: Create Retrospective Document
+- Create (or use existing) retrospective file: `retrospectives/issue-{issue-number}-{kebab-title}-postmortem.md`
+- Use retrospective template: `get_fraim_file({ path: "templates/retrospective/RETROSPECTIVE-TEMPLATE.md" })`
+- Document while work context is fresh and complete
+
+### Step 3: Work Analysis
+- **What Went Well**: Successful approaches, tools, and techniques used
+- **What Went Poorly**: Challenges, obstacles, and inefficiencies encountered
+- **Root Cause Analysis**: Why problems occurred, not just what happened
+- **Decision Analysis**: Review key decisions made during the work
+- **PR Feedback Analysis**: What user feedback revealed about the work quality
+- **Process Effectiveness**: How well the workflow supported the work
+
+### Step 4: Learning Extraction
+- **Key Learnings**: Specific insights that can help future work of this type
+- **Process Improvements**: Workflow or rule changes that would help
+- **Tool/Technique Discoveries**: New approaches or tools that proved valuable
+- **Anti-Patterns Identified**: Approaches to avoid in future work
+- **User Feedback Patterns**: Common themes in user feedback to address
+- **Quality Insights**: What contributed to or detracted from work quality
+
+### Step 5: Prevention Measures
+- **Specific Actions**: Concrete steps to prevent similar issues in future work
+- **Rule Updates**: Suggestions for updating FRAIM rules or workflows
+- **Knowledge Sharing**: Insights that should be shared with other agents
+- **Process Enhancements**: Workflow improvements based on experience
+- **Feedback Integration**: How to better incorporate user feedback in future work
+- **Quality Improvements**: Changes to improve work quality
+
+### Step 6: Validation and Completion
+- Ensure retrospective meets quality criteria
+- Validate all template sections are complete
+- Confirm learnings are actionable and specific
+- Verify PR feedback has been analyzed and learned from
+- Check that prevention measures are concrete and implementable
+- Mark phase complete and proceed to resolve
+
+## VALIDATION CRITERIA
+- ✅ Retrospective document created using template
+- ✅ Root cause analysis completed (not just symptoms)
+- ✅ Prevention measures documented and actionable
+- ✅ Key learnings extracted and documented
+- ✅ Process improvements identified
+- ✅ PR feedback analyzed and lessons captured
+- ✅ All template sections completed with substantial content
+- ✅ Retrospective quality meets standards
+- ✅ Learnings are specific to the workflow type and transferable
+
+## PHASE COMPLETION
+This phase is complete when:
+1. Comprehensive retrospective document is created
+2. All validation criteria are met
+3. Learnings are documented for future reference
+4. PR feedback has been systematically analyzed
+5. Prevention measures are specific and actionable
+6. Process improvements are identified
+7. Agent is ready to proceed to resolve phase
+
+## WORKFLOW-SPECIFIC FOCUS AREAS
+
+### Spec Retrospective Focus
+- Requirements gathering effectiveness
+- Stakeholder engagement quality
+- Competitive analysis thoroughness
+- User experience definition clarity
+- Validation plan completeness
+
+### Design Retrospective Focus
+- Technical decision quality
+- Architecture choice rationale
+- Design review feedback incorporation
+- Technical feasibility assessment
+- Implementation guidance clarity
+
+### Implement Retrospective Focus
+- Code quality and maintainability
+- Technical approach effectiveness
+- Testing strategy success
+- Performance considerations
+- Integration challenges
+
+### Test Retrospective Focus
+- Test coverage adequacy
+- Quality assurance approach effectiveness
+- Testing strategy validation
+- Bug detection capability
+- Test maintenance considerations
+
+## NEXT PHASE
+After completing retrospective, proceed to `resolve` phase for final merge and cleanup.

package/dist/registry/ai-manager-rules/shared-phases/address-pr-feedback.md

@@ -0,0 +1,188 @@
+# Phase: address-pr-feedback
+
+## INTENT
+To systematically address all PR feedback items by making targeted changes, replying to comments, and preparing for re-validation.
+
+## OUTCOME
+All PR feedback addressed with:
+- Targeted changes made for each feedback item
+- Feedback file updated with resolutions
+- PR comments replied to with explanations
+- Changes validated and ready for re-review
+
+## 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** (document all changes made)
+- **Correctness** (address feedback accurately)
+- **Completeness** (address every UNADDRESSED item)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Critical for feedback phase:
+- **Targeted Changes**: Make minimal changes to address specific feedback
+- **Manual Validation**: Test changes manually before updating PR
+- **Clear Communication**: Reply to each comment with clear explanations
+
+## PRINCIPLES
+- **Feedback-Driven**: Address only the specific issues raised in PR comments
+- **Minimal Changes**: Avoid scope creep or unnecessary refactoring
+- **Clear Communication**: Explain resolutions clearly to reviewers
+- **Validation**: Ensure changes work before updating PR
+
+## 📋 WORKFLOW
+
+### Step 1: Read PR Feedback File
+
+**MANDATORY**: Read the feedback file created by `wait-for-pr-review`:
+- File location: `docs/evidence/{issue_number}-{workflow_type}-feedback.md`
+- Identify all UNADDRESSED feedback items
+- Understand the context and requirements for each item
+
+### Step 2: Address Each Feedback Item
+
+**For each UNADDRESSED item:**
+
+1. **Understand the Feedback**:
+   - Read the comment carefully
+   - Identify what specific change is requested
+   - Determine the scope of the change needed
+
+2. **Make Targeted Changes**:
+   - Make minimal, focused changes to address the specific feedback
+   - Avoid unrelated changes or improvements
+   - Keep changes as small as possible while fully addressing the feedback
+
+3. **Update Feedback File**:
+   - Change status from UNADDRESSED to ADDRESSED
+   - Document your resolution approach
+   - Include details of what you changed
+
+**Feedback File Update Format**:
+```markdown
+### Comment X - ADDRESSED
+- **Author**: reviewer_name
+- **Type**: pr_comment|review_comment|review
+- **File**: file_path (if applicable)
+- **Line**: line_number (if applicable)
+- **Comment**: Original feedback text
+- **Status**: ADDRESSED
+- **Resolution**: Detailed explanation of how you addressed this feedback
+- **Changes Made**: Specific files/lines modified
+```
+
+### Step 3: Validate Changes
+
+**Test your changes:**
+- Run compilation check: `npx tsc --noEmit --skipLibCheck`
+- Run relevant tests to ensure no regressions
+- Test manually if the feedback involves UI/API behavior
+- Verify the specific issue mentioned in feedback is resolved
+
+### Step 4: Reply to PR Comments
+
+**For each addressed comment:**
+- Reply to the original PR comment
+- Explain what you changed and how it addresses their concern
+- Reference specific files/lines if helpful
+- Be clear and professional in your communication
+
+**Example reply format**:
+```
+✅ **Addressed**: [Brief description of what you changed]
+
+**Changes made**:
+- [Specific change 1]
+- [Specific change 2]
+
+**Files modified**: `path/to/file.ts`, `path/to/test.ts`
+
+This should resolve the [specific issue mentioned]. Please let me know if you need any clarification!
+```
+
+### Step 5: Commit and Push Changes
+
+**Commit your changes:**
+- Use clear commit messages that reference the feedback
+- Example: `Address PR feedback: Fix error handling in auth service`
+- Push changes to the PR branch
+
+## 📸 EVIDENCE REQUIREMENTS
+
+You MUST provide concrete evidence for all claims:
+
+1. **All Feedback Addressed**: Every UNADDRESSED item in feedback file is now ADDRESSED
+2. **Changes Made**: Specific code changes made for each feedback item
+3. **Validation Complete**: Tests pass and changes work as expected
+4. **PR Updated**: Changes committed, pushed, and comments replied to
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ All UNADDRESSED items in feedback file are now ADDRESSED
+- ✅ Feedback file updated with resolution details for each item
+- ✅ Targeted changes made to address each specific feedback
+- ✅ Changes validated (compilation, tests, manual testing)
+- ✅ PR comments replied to with clear explanations
+- ✅ Changes committed and pushed to PR branch
+
+### Phase Incomplete If:
+- ❌ Any UNADDRESSED items remain in feedback file
+- ❌ Changes don't actually address the feedback given
+- ❌ Tests failing after changes
+- ❌ Compilation errors introduced
+- ❌ PR comments not replied to
+- ❌ Changes not committed/pushed
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekMentoring({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "address-pr-feedback",
+  status: "complete",
+  findings: {
+    feedbackItemsAddressed: {total_items_addressed},
+    changesValidated: true
+  },
+  evidence: {
+    feedbackFileUpdated: "All UNADDRESSED items now ADDRESSED with resolutions",
+    changesMade: "Brief summary of changes made",
+    validationResults: "Compilation and tests pass",
+    prCommentsReplied: "Replied to all PR comments with explanations"
+  }
+})
+```
+
+If feedback addressing incomplete, iterate:
+```javascript
+seekMentoring({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "address-pr-feedback",
+  status: "incomplete",
+  findings: {
+    uncertainties: ["Issues encountered", "What needs to be fixed"]
+  }
+})
+```
+
+## SCRIPTS
+
+**Compile TypeScript:**
+```bash
+npx tsc --noEmit --skipLibCheck
+```
+
+**Run tests:**
+```bash
+npm test
+```
+
+**Check git status:**
+```bash
+git status
+git diff
+```

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

@@ -0,0 +1,169 @@
+# 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
+
+## PRINCIPLES
+- **Complete Documentation**: Evidence shows all work done
+- **Proper Labels**: Issue status reflects readiness
+- **Clear Communication**: PR and evidence are clear
+- **Ready for Review**: No blockers for human reviewer
+
+## RULES FOR THIS PHASE
+
+### Success Criteria
+Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus on:
+- **Integrity** (honest documentation of all work completed)
+- **Completeness** (all finalization steps completed)
+
+### Simplicity Principles
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key for finalization:
+- **Focus on the assigned issue only** - document only relevant work
+- **Clear communication** - evidence should be easy to understand
+
+### 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.
+
+## WORKFLOW
+
+### Step 1: Update Issue Labels
+
+**Remove:**
+- `status:wip`
+- Any phase-specific labels (e.g., `phase:spec`, `phase:design`, `phase:impl`)
+
+**Add:**
+- `status:needs-review`
+
+**GitHub Repository Context:**
+Read `.fraim/config.json` for:
+- `git.repoOwner` - GitHub repository owner
+- `git.repoName` - GitHub repository name
+
+Use GitHub MCP tools to update labels.
+
+### Step 2: Create Evidence Document
+
+**File location:**
+```
+docs/evidence/{issue_number}-{workflow_type}-evidence.md
+```
+
+**Evidence document should include:**
+
+#### Summary
+- Issue number and title
+- Workflow type (spec, design, implement, test)
+- Brief description of work completed
+
+#### Work Completed
+**For Spec Workflow:**
+- Specification document created
+- High-fidelity HTML mocks (if UI changes)
+- Requirements coverage
+
+**For Design Workflow:**
+- Technical design document
+- Architecture decisions
+- API specifications
+- Database schema (if applicable)
+
+**For Implement Workflow:**
+- Implementation details
+- Key files changed
+- Approach taken
+- Testing completed
+
+**For Test Workflow:**
+- Test suite created/enhanced
+- Coverage metrics
+- Test results
+
+#### Validation
+- How work was validated
+- Validation results
+- Screenshots/output (if applicable)
+
+#### Quality Checks
+- All deliverables complete
+- Documentation clear and professional
+- Work ready for next phase or review
+
+#### Phase Completion
+- All phases completed for this workflow
+- Evidence from each phase
+- Any iterations or challenges
+
+### Step 3: Verify PR Exists
+
+**Verify PR:**
+- PR exists for the feature branch
+- PR title reflects the issue and workflow
+- PR description includes context and links to deliverables
+
+**If PR doesn't exist:**
+- Create PR manually
+- Link to issue
+- Add evidence document link
+
+### Step 4: Add PR Comment
+
+Add comment to PR with link to evidence:
+```
+{Workflow_type} workflow complete. Evidence document: docs/evidence/{issue_number}-{workflow_type}-evidence.md
+
+All phases completed:
+{workflow_specific_phases_checklist}
+
+Ready for human review.
+```
+
+### Step 5: Final Verification
+
+**Checklist:**
+- ✅ Issue labels updated
+- ✅ Evidence document created and complete
+- ✅ PR exists and is ready
+- ✅ PR comment added with evidence link
+- ✅ All deliverables complete
+- ✅ Git status clean
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Issue has `status:needs-review` label
+- ✅ Issue does not have workflow phase labels
+- ✅ Evidence document exists and is complete
+- ✅ PR exists and is ready for review
+- ✅ PR has comment linking to evidence
+- ✅ All previous phases complete
+
+### Phase Incomplete If:
+- ❌ Labels not updated
+- ❌ Evidence document missing or incomplete
+- ❌ PR not ready
+- ❌ Previous phases not complete
+
+### Report Back:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "finalize", 
+  status: "complete",
+  evidence: {
+    labelsUpdated: "Issue has status:needs-review label",
+    evidenceDocument: "docs/evidence/{issue_number}-{workflow_type}-evidence.md created",
+    prStatus: "PR ready for review",
+    prComment: "PR comment added with evidence link",
+    allPhasesComplete: "All {workflow_type} phases completed successfully"
+  }
+})
+```