fraim-framework 2.0.44 → 2.0.46

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

@@ -0,0 +1,100 @@
+# Phase: Implement-Scoping
+
+## INTENT
+To understand the issue requirements and determine whether it's a bug fix or feature implementation.
+
+## OUTCOME
+Clear understanding of:
+- Issue type (bug or feature)
+- All requirements and acceptance criteria
+- Ready to proceed to next phase (repro for bugs, spike for features)
+
+## PRINCIPLES
+- **Thorough Understanding**: Read all linked documents and context
+- **Clear Classification**: Accurately determine bug vs feature
+- **Question Early**: Escalate if requirements are unclear
+
+## RULES FOR THIS PHASE
+
+### Success Criteria
+Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete 5-criteria success framework. Focus especially on **Integrity** (truthfulness in reporting) and **Independence** (smart decision making).
+
+### Simplicity Principles  
+Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key principles for scoping:
+- **Focus on the assigned issue only** - don't scope other issues
+- **Don't over-think it** - understand the specific need being addressed
+
+### 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. Understanding the architecture helps with proper scoping.
+
+## 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 in GitHub (use MCP where available)
+- Note the issue title, labels, and any linked documents
+- Identify if there's a spec, RFC, or design document
+
+### Step 2: Review Linked Documents
+- If spec/RFC exists: Read it thoroughly
+- If design document exists: Review the technical approach
+- Note all acceptance criteria and requirements
+
+### Step 3: Determine Issue Type
+**Bug indicators:**
+- Issue describes broken/incorrect behavior
+- References a regression or failure
+- Has reproduction steps
+- Reports unexpected behavior
+
+**Feature indicators:**
+- Issue describes new functionality
+- Adds capabilities that don't exist
+- Enhances existing features
+- Has acceptance criteria for new behavior
+
+### Step 4: Understand Requirements
+- List all acceptance criteria
+- Identify edge cases mentioned
+- Note any constraints or limitations
+- Understand success criteria
+
+### Step 5: Identify Uncertainties
+If anything is unclear:
+- **DO NOT** make assumptions
+- **DO NOT** hypothesize requirements
+- **ESCALATE** to user with specific questions
+- Wait for clarification before proceeding
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Issue type determined (bug or feature)
+- ✅ All requirements understood
+- ✅ No blocking uncertainties remain
+- ✅ Ready to proceed to next phase
+
+### Report Back:
+When you complete scoping, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-scoping", 
+  status: "complete",
+  findings: {
+    issueType: "bug", // or "feature"
+    requirements: "Brief summary of what you understood",
+    uncertainties: [] // List any unclear aspects, or empty array if none
+  }
+})
+```
+
+The AI Coach will provide instructions for your next phase based on the issue type you determined.

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

@@ -0,0 +1,230 @@
+# Phase: Implement-Smoke
+
+## INTENT
+To run technical health checks ensuring the system is stable: build passes, all tests pass, git status is clean, and core functionality hasn't been broken by the implementation.
+
+## OUTCOME
+All technical checks pass, confirming:
+- Build compiles successfully  
+- All tests pass (100% success rate)
+- Git status is clean
+- Core system functionality intact
+- No regressions in critical paths
+
+**Note**: This phase focuses purely on technical health checks. Manual validation and functional testing are handled in the implement-validate phase.
+
+## PRINCIPLES
+- **Zero Tolerance**: All checks must pass
+- **Technical Focus**: Automated verification only
+- **Fix Immediately**: If any check fails, return to implement phase
+- **Fast Feedback**: Quick automated verification
+
+## 📋 MANDATORY TECHNICAL CHECKS
+
+### Step 0: Read Project Validation Commands 📖
+
+**FIRST**: Read your project's validation commands from `.fraim/config.json`:
+
+```bash
+# Read the config to get project-specific validation commands
+cat .fraim/config.json
+```
+
+Look for `customizations.validation.buildCommand` and `customizations.validation.smokeTestCommand`.
+
+**Use these commands instead of the generic ones below if they exist.**
+
+### Step 1: Build Compilation Check ✅
+
+**Requirements**:
+- TypeScript compiles without errors
+- Build process completes successfully
+- No type errors or warnings
+
+**Commands to Run** (use customizations.validation.buildCommand from config if available):
+```bash
+# Run build (use customizations.validation.buildCommand if available, otherwise default)
+npm run build
+```
+
+**What to Look For**:
+- Exit code 0 (success) for all commands
+- No error messages in output
+- Clean compilation without warnings
+
+### Step 2: Complete Test Suite ✅
+
+**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** (use customizations.validation.smokeTestCommand from config if available):
+```bash
+# Run the comprehensive test suite (use customizations.validation.smokeTestCommand if available)
+npm test
+```
+
+**What to Look For**:
+- "All tests passed" or similar success message
+- No "FAILED" or "ERROR" in output
+- 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: Git Status Check ✅
+
+**Requirements**:
+- Git status is clean
+- Only intended changes present
+- No untracked files (except evidence docs)
+
+**Commands to Run**:
+```bash
+# Check git status
+git status
+
+# Check recent commits
+git log --oneline -3
+```
+
+**What to Look For**:
+- Only intended files are modified
+- No accidentally modified files
+- Clean working directory
+- Meaningful commit messages
+
+### Step 4: Code Quality Verification ✅
+
+**Requirements**:
+- No type bypassing
+- No debugging code remains
+- No task placeholder comments in core functionality
+
+**Commands to Run**:
+```bash
+# Check for type bypassing
+grep -r "as any" src/ || echo "✅ No type bypassing found"
+
+# 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
+grep -r "task-placeholder" src/ || echo "✅ No task placeholders found"
+```
+
+**What to Look For**:
+- Zero instances of "as any" (or only justified ones with comments)
+- No console.log statements (except intentional logging)
+- No task placeholder comments in critical code
+
+## 🛠️ TECHNICAL COMMANDS REFERENCE
+
+### Project-Specific Commands (Read from .fraim/config.json)
+```bash
+# Check your project's custom validation commands:
+cat .fraim/config.json | grep -A 5 "validation"
+```
+
+### Quick Health Check
+```bash
+# One-liner using project defaults (customize based on your config)
+npm run build && npm test && git status
+```
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Build succeeds without errors
+- ✅ All tests pass (100% success rate)
+- ✅ Git status clean (only intended changes)
+- ✅ No "as any" type bypassing
+- ✅ No debugging code remains
+- ✅ No task placeholder comments in core functionality
+- ✅ All technical checks documented
+
+### Phase Incomplete If:
+- ❌ Build fails
+- ❌ ANY test fails
+- ❌ Git status shows unintended changes
+- ❌ Code quality issues found
+
+**If ANY check fails, return to implement-code phase immediately.**
+
+## RULES FOR THIS PHASE
+
+### Technical Standards
+- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full technical standards
+- 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`
+
+### Failure Handling
+- **If ANY technical check fails**: Return to implement-code phase
+- **Do not proceed to regression phase** if smoke tests fail
+- Fix the implementation first, then re-run smoke tests
+
+## SCRIPTS
+
+**Run all technical checks:**
+```bash
+npm run build && npm test && git status
+```
+
+**Run smoke tests specifically:**
+```bash
+npm run test-smoke-ci
+```
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-smoke", 
+  status: "complete",
+  findings: {
+    issueType: "bug" // or "feature" - Required for phase validation
+  },
+  evidence: {
+    buildPassed: "YES", // Did `npm run build` succeed?
+    allTestsPassed: "YES", // Did `npm test` show 100% pass rate?
+    gitStatusClean: "YES", // Does `git status` show only intended changes?
+    noTypeBypass: "YES", // Did `grep -r "as any" src/` find zero instances?
+    noDebugCode: "YES", // Did you remove console.log statements?
+    registryValid: "YES", // Did `npm run validate:registry` pass?
+    commandsRun: "npm run build && npm test && git status",
+    summary: "All technical checks passed. Build succeeds, all tests pass, git status clean."
+  }
+})
+```
+
+If any technical check fails:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "implement",
+  issueNumber: "{issue_number}",
+  currentPhase: "implement-smoke", 
+  status: "incomplete",
+  findings: {
+    issueType: "bug" // or "feature" - Required for phase validation
+  },
+  evidence: {
+    buildPassed: "NO", // Specify what failed
+    allTestsPassed: "NO", // Be specific about failures
+    issues: ["Build failed with TypeScript errors", "3 tests failing"],
+    commandsRun: "npm run build && npm test",
+    nextAction: "Returning to implement phase to fix technical issues"
+  }
+})
+```

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