fraim-framework 2.0.55 → 2.0.57

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

@@ -1,121 +0,0 @@
-# Phase: Implement-Spike (Features Only)
-
-## INTENT
-To build a proof-of-concept that validates the technical approach, tests uncertain or risky aspects, and confirms the design is viable before full implementation.
-
-## OUTCOME
-A working POC that:
-- Validates key technical assumptions
-- Tests risky or uncertain aspects
-- Gets user approval
-- Informs any necessary design updates
-
-## PRINCIPLES
-- **Spike-First Development**: Follow the spike-first rule for unfamiliar technology
-- **Risk Reduction**: Focus on highest-risk or most uncertain aspects
-- **Quick Validation**: Build minimal POC, not production code
-- **User Approval**: Get explicit approval before proceeding
-- **Design Updates**: Update design doc with findings
-
-## WORKFLOW
-
-### Step 1: Review Design Document
-- Read the technical design/RFC thoroughly
-- Identify technical assumptions
-- Note any unfamiliar technologies or patterns
-- List risky or uncertain aspects
-
-### Step 2: Identify Spike Scope
-**Focus on:**
-- Unfamiliar technology or libraries
-- Integration points with external systems
-- Performance-critical components
-- Complex algorithms or logic
-- Uncertain technical feasibility
-
-**Do NOT spike:**
-- Well-understood patterns
-- Standard CRUD operations
-- Simple UI changes
-- Routine implementations
-
-### Step 3: Build Proof-of-Concept
-- Create minimal code to test assumptions
-- Focus on proving/disproving technical approach
-- Don't worry about production quality
-- Document what you're testing
-
-### Step 4: Test Key Assumptions
-- Run the POC
-- Verify it works as expected
-- Test edge cases if relevant
-- Document findings
-
-### Step 5: Get User Approval
-- Present POC to user
-- Explain what was validated
-- Share any findings or concerns
-- **Wait for explicit approval** before proceeding
-
-### Step 6: Update Design Document
-If POC revealed:
-- Better approaches
-- Technical constraints
-- Performance considerations
-- Integration challenges
-
-**Update the design document** with findings
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ POC built and tested
-- ✅ Key technical assumptions validated
-- ✅ User has approved the approach
-- ✅ Design document updated (if needed)
-- ✅ Ready to proceed with full implementation
-
-### Phase Incomplete If:
-- ❌ POC doesn't work as expected
-- ❌ Technical approach not viable
-- ❌ User hasn't approved
-- ❌ Significant findings not documented
-
-## RULES FOR THIS PHASE
-
-### Spike-First Development
-Read `registry/rules/spike-first-development.md` via `get_fraim_file` for complete spike methodology.
-
-### Architecture Compliance
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full architecture guidelines.
-
-### Git Operations (if needed)
-When using git commands directly (if MCP tools unavailable), read `rules/git-safe-commands.md` via `get_fraim_file` to avoid interactive commands that hang agents.
-
-## SCRIPTS
-Run POC:
-```bash
-npm run spike  # or appropriate command
-node spike/your-poc.js
-```
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-spike", 
-  status: "complete",
-  findings: {
-    issueType: "feature" // Required for phase validation
-  },
-  evidence: {
-    pocLocation: "spike/auth-flow.ts",
-    validationResults: "OAuth2 integration works as expected",
-    userApproval: "User approved approach on [date]",
-    designUpdates: "Updated design doc with token refresh findings"
-  }
-})
-```

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

@@ -1,375 +0,0 @@
-# Phase: Implement-Validate
-
-## INTENT
-To verify that the implementation works correctly by testing it in appropriate ways: browser testing for UI changes, API testing for backend changes, and command-line testing for CLI changes.
-
-## OUTCOME
-Confirmation that:
-- Implementation works as expected
-- All acceptance criteria are met
-- Edge cases are handled
-- No obvious bugs or issues
-
-## 🎯 VALIDATION MINDSET
-
-This is THE critical phase where you prove your implementation actually works. No shortcuts, no assumptions.
-
-**Your Mission**: Prove beyond doubt that a real user can successfully use this feature.
-
-## RULES FOR THIS PHASE
-
-### Config-Aware Testing
-**CRITICAL**: Always check `.fraim/config.json` first for project-specific test commands:
-- `customizations.validation.testSuiteCommand` - Use this for comprehensive testing (default: `npm test`)
-
-### Success Criteria
-Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus on:
-- **Integrity** (honest reporting of validation results - never claim something works if you didn't test it)
-- **Correctness** (implementation actually works as expected)
-- **Completeness** (all acceptance criteria validated, edge cases tested)
-
-### Simplicity Principles
-Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Critical for validation:
-- **Manual Validation Required** - This is THE manual validation phase
-- **Prototype-First** - Validate the working solution before engineering tests
-- **Resource Waste Prevention** - Efficient testing approach
-
-### Architecture Compliance
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full architecture guidelines. Ensure implementation follows architectural patterns.
-
-### Debugging and Git Operations
-- Use Successful Debugging Patterns from `rules/successful-debugging-patterns.md` via `get_fraim_file`
-- When using git commands directly (if MCP tools unavailable), read `rules/git-safe-commands.md` via `get_fraim_file` to avoid interactive commands that hang agents.
-
-### Failure Handling
-- **If validation fails**: Return to implement-code phase
-- **Do not proceed to smoke tests** if validation fails
-- Fix the implementation first, then re-validate
-
-## PRINCIPLES
-- **Real Testing**: Test actual functionality, not mocks
-- **Appropriate Tools**: Use browser for UI, curl for APIs, CLI for commands
-- **Complete Coverage**: Test all acceptance criteria
-- **Edge Cases**: Test boundary conditions and error scenarios
-- **Evidence**: Document validation results
-
-## 📋 MANDATORY VALIDATION STEPS
-
-### Step 1: Build and Compilation Check ✅
-
-**Requirements**:
-- TypeScript compiles without errors
-- Build process completes successfully
-- No type errors or warnings
-
-**Commands to Run**:
-```bash
-# Check TypeScript compilation
-npx tsc --noEmit --skipLibCheck
-
-# Run full build (includes validation)
-npm run build
-
-# Check for any 'as any' type bypassing
-grep -r "as any" src/ || echo "✅ No type bypassing found"
-```
-
-**What to Look For**:
-- Exit code 0 (success) for all commands
-- No error messages in output
-- Clean compilation without warnings
-
-### Step 2: Test Suite Validation 📊
-
-**Requirements**:
-- ALL existing tests pass (100% success rate) - not just tests you created
-- No timeouts or hanging tests
-- Comprehensive test coverage validation
-
-**CRITICAL**: You must run the COMPLETE test suite, including all existing tests, smoke tests, and any tests you created. Do not run only the tests you wrote.
-
-**Commands to Run** (check .fraim/config.json for project-specific commands first):
-```bash
-# 1. FIRST: Check for custom test commands
-cat .fraim/config.json | grep -A 5 "validation"
-
-# 2. Run comprehensive test suite for current work
-# Use customizations.validation.testSuiteCommand if available, otherwise:
-npm test
-
-# 3. Run targeted tests for your specific changes (if applicable)
-# Example: If you modified user authentication, run auth-related tests
-# npm run test -- --grep "auth"
-# OR: npm run test test-{issue-number}-*.ts
-```
-
-**What to Look For**:
-- "All tests passed" or similar success message for ALL commands
-- No "FAILED" or "ERROR" in output from any test run
-- Test count should include existing tests + any new tests you added
-- No timeout messages
-- Verify that existing functionality tests are included in the run
-
-**Example Expected Output**:
-```
-✅ Running 45 tests (including existing + new tests)
-✅ All tests passed
-✅ Test suite completed successfully
-```
-
-### Step 3: Manual Functionality Testing 🧪
-
-**Requirements**:
-- Test actual user workflows end-to-end
-- Verify all acceptance criteria manually
-- Test both happy path and error scenarios
-
-**For UI Changes**:
-```bash
-# Start development server
-npm run dev
-# Then manually test in browser at http://localhost:3000
-```
-
-**For API Changes**:
-```bash
-# Test API endpoints
-curl -X GET http://localhost:3000/health
-curl -X POST http://localhost:3000/api/test -H "Content-Type: application/json" -d '{"test":"data"}'
-```
-
-**For CLI Changes**:
-```bash
-# Test CLI commands
-node bin/fraim.js --help
-node bin/fraim.js sync --dry-run
-```
-
-**What to Document**:
-- Specific steps you performed
-- What you clicked/typed/tested
-- Results you observed
-- Any errors encountered and how they were handled
-
-### Step 4: Git and Code Quality Check 🔍
-
-**Requirements**:
-- Git status is clean
-- No debugging code remains
-- Code follows quality standards
-
-**Commands to Run**:
-```bash
-# Check git status
-git status
-
-# Look for debugging code
-grep -r "console.log" src/ | grep -v "logger" | grep -v "// OK" || echo "✅ No debug logs found"
-
-# Check for task placeholder comments in core functionality
-grep -r "task-placeholder" src/ || echo "✅ No task placeholders found"
-
-# Validate registry paths (if applicable)
-npm run validate:registry
-```
-
-**What to Look For**:
-- Only intended files are modified
-- No console.log statements (except intentional logging)
-- No task placeholder comments in critical code
-- Clean working directory
-
-### Step 5: Bug-Specific Validation (For Bug Fixes) 🐛
-
-**Requirements**:
-- Original reproduction test now passes
-- Bug symptoms are gone
-- No regressions introduced
-
-**Commands to Run**:
-```bash
-# Run the specific repro test
-npm test -- path/to/repro/test.test.ts
-
-# Test the original bug scenario manually
-# (Follow the original reproduction steps)
-```
-
-**What to Verify**:
-- Repro test that was failing now passes
-- Original bug behavior is fixed
-- Related functionality still works
-
-### Step 6: Feature-Specific Validation (For Features) ✨
-
-**Requirements**:
-- New functionality works as specified
-- Integration with existing features works
-- All acceptance criteria met
-
-**What to Test**:
-- Main user scenarios from the spec
-- Edge cases and error conditions
-- Integration points with existing code
-- Performance (if applicable)
-
-## 🛠️ VALIDATION COMMANDS REFERENCE
-
-### Quick Health Check
-```bash
-# One-liner to check basic health
-npx tsc --noEmit --skipLibCheck && npm test && git status
-```
-
-### Comprehensive Validation
-```bash
-# Full validation suite
-npm run build && npm run test-all-ci && npm run validate:registry
-```
-
-### API Testing
-```bash
-# Test API health and basic functionality
-curl -f http://localhost:3000/health && echo "✅ API healthy"
-```
-
-### Build Verification
-```bash
-# Verify build artifacts are created correctly
-npm run build && ls -la dist/ && echo "✅ Build artifacts present"
-```
-
-## WORKFLOW
-
-### Step 1: Identify Validation Method
-
-**For UI Changes:**
-- Use browser to navigate and test
-- Verify visual correctness
-- Test user interactions
-- Check responsive behavior
-
-**For API Changes:**
-- Use curl or similar tools
-- Test all endpoints
-- Verify request/response formats
-- Test error handling
-
-**For Backend/CLI Changes:**
-- Run relevant commands
-- Test with various inputs
-- Verify output correctness
-- Test error conditions
-
-### Step 2: Test All Acceptance Criteria
-- Review acceptance criteria from implement-scoping phase
-- Test each criterion systematically
-- Document results for each
-- Verify all are met
-
-### Step 3: Test Edge Cases
-**Common edge cases:**
-- Empty inputs
-- Invalid inputs
-- Boundary values
-- Error conditions
-- Concurrent operations (if applicable)
-
-### Step 4: Document Results
-In evidence, include:
-- What was tested
-- How it was tested
-- Results of each test
-- Any issues found and fixed
-- Screenshots/output (if applicable)
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ All acceptance criteria tested and passing
-- ✅ Edge cases handled correctly
-- ✅ For bugs: repro test now passes
-- ✅ For features: new functionality works
-- ✅ No obvious bugs or issues
-- ✅ Validation results documented with evidence
-- ✅ All servers running without errors
-- ✅ 100% test success rate
-- ✅ Error scenarios tested and handled
-
-### Phase Incomplete If:
-- ❌ Acceptance criteria not met
-- ❌ For bugs: repro test still fails
-- ❌ For features: functionality doesn't work
-- ❌ Edge cases not handled
-- ❌ Obvious bugs found
-- ❌ Missing evidence for claims
-- ❌ Server errors present
-- ❌ Any tests failing
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-validate", 
-  status: "complete",
-  findings: {
-    issueType: "bug" // or "feature" - Required for phase validation
-  },
-  evidence: {
-    buildPassed: "YES", // Did `npm run build` succeed?
-    testsPassed: "YES", // Did `npm test` show 100% pass rate?
-    manualValidationDone: "YES", // Did you manually test the functionality?
-    serversStarted: "YES", // Did servers start without errors?
-    reproTestPassed: "YES", // (For bugs) Does the repro test now pass?
-    featureWorking: "YES", // (For features) Does the new functionality work?
-    commandsRun: "npm run build && npm test", // What validation commands did you run?
-    summary: "All validation steps completed successfully. Build passes, all 15 tests pass, manual testing confirmed functionality works as expected."
-  }
-})
-```
-
-If validation reveals issues, report back with status "incomplete":
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-validate", 
-  status: "incomplete",
-  findings: {
-    issueType: "bug" // or "feature" - Required for phase validation
-  },
-  evidence: {
-    buildPassed: "NO", // Specify what failed
-    testsPassed: "NO", // Be specific about failures
-    issues: ["Build failed with TypeScript errors", "3 tests failing", "Manual testing revealed login button not working"],
-    commandsRun: "npm run build && npm test",
-    nextAction: "Need to return to implement phase to fix these issues"
-  }
-})
-```
-
-## SCRIPTS
-
-**Browser testing:**
-```bash
-npm run dev  # Start dev server
-# Then manually test in browser
-```
-
-**API testing:**
-```bash
-curl -X POST http://localhost:3000/api/endpoint -d '{"data": "value"}'
-```
-
-**CLI testing:**
-```bash
-npm run cli -- command --flag value
-```
-
-**Run all tests:**
-```bash
-npm test
-```

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

@@ -1,116 +0,0 @@
-# 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.