fraim-framework 2.0.66 → 2.0.67

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

@@ -0,0 +1,121 @@
+# 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
+seekMentoring({
+  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

@@ -0,0 +1,375 @@
+# 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
+seekMentoring({
+  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
+seekMentoring({
+  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
+```