fraim-framework 2.0.48 → 2.0.51

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

@@ -177,19 +177,16 @@ Tag tests appropriately to ensure proper test suite execution:
 - **`unit`**: Tests that verify individual functions or classes in isolation
 - **`e2e`**: End-to-end tests that verify complete user workflows
 
-**Smoke Test Execution Rules:**
-If ANY tests are tagged "smoke" or you're modifying core functionality:
-1. **MANDATORY**: Run full smoke test suite: `npm run test-smoke-ci`
-2. **MANDATORY**: Include smoke test output in evidence
-3. **MANDATORY**: All smoke tests must pass before proceeding
-4. **BLOCKING**: Smoke test failures block phase completion
-
 ### Step 7: Basic Compilation Check
 
 **Verify code compiles:**
-```bash
-npx tsc --noEmit --skipLibCheck
-```
+
+**Build Commands**: Always check `.fraim/config.json` first for `customizations.validation.buildCommand`, use that if available, otherwise default to `npm run build`.
+
+**What to Look For**:
+- Exit code 0 (success)
+- No TypeScript compilation errors
+- Clean build output
 
 **Must exit with code 0** (no errors)
 

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

@@ -23,16 +23,17 @@ All technical checks pass, confirming:
 
 ### Step 0: Read Project Validation Commands 📖
 
-**FIRST**: Read your project's validation commands from `.fraim/config.json`:
+**FIRST**: Check your project's custom commands:
 
 ```bash
-# Read the config to get project-specific validation commands
-cat .fraim/config.json
-```
+# Check for custom build command
+cat .fraim/config.json | grep -A 3 "buildCommand"
 
-Look for `customizations.validation.buildCommand` and `customizations.validation.smokeTestCommand`.
+# Check for custom smoke test command  
+cat .fraim/config.json | grep -A 3 "smokeTestCommand"
+```
 
-**Use these commands instead of the generic ones below if they exist.**
+**Use the configured commands if they exist, otherwise use the defaults shown below.**
 
 ### Step 1: Build Compilation Check ✅
 
@@ -43,7 +44,9 @@ Look for `customizations.validation.buildCommand` and `customizations.validation
 
 **Commands to Run** (use customizations.validation.buildCommand from config if available):
 ```bash
-# Run build (use customizations.validation.buildCommand if available, otherwise default)
+# Use project-specific build command from .fraim/config.json if available:
+# - Look for customizations.validation.buildCommand
+# - Use that command if available, otherwise default to:
 npm run build
 ```
 
@@ -164,6 +167,7 @@ npm run build && npm test && git status
 
 ### 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
+- **Config Commands**: Always check `.fraim/config.json` first for `customizations.validation.buildCommand` and `customizations.validation.smokeTestCommand`, use those if available, otherwise use defaults
 - 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`
 
@@ -181,6 +185,9 @@ npm run build && npm test && git status
 
 **Run smoke tests specifically:**
 ```bash
+# Use project-specific command from .fraim/config.json if available
+# Check: cat .fraim/config.json | grep "smokeTestCommand"
+# Use configured command or default to:
 npm run test-smoke-ci
 ```
 

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

@@ -18,6 +18,10 @@ This is THE critical phase where you prove your implementation actually works. N
 
 ## 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)
@@ -86,17 +90,17 @@ grep -r "as any" src/ || echo "✅ No type bypassing found"
 
 **Commands to Run** (check .fraim/config.json for project-specific commands first):
 ```bash
-# 1. FIRST: Read your project's validation commands from .fraim/config.json
-cat .fraim/config.json | grep -A 10 "validation"
+# 1. FIRST: Check for custom test commands
+cat .fraim/config.json | grep -A 5 "validation"
 
-# 2. Run the comprehensive test suite (this runs ALL tests)
+# 2. Run comprehensive test suite for current work
+# Use customizations.validation.testSuiteCommand if available, otherwise:
 npm test
 
-# 3. Also run smoke tests specifically to verify core functionality
-npm run test-smoke-ci
-
-# 4. Run all tests in CI mode for complete coverage
-npm run test-all-ci
+# 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**:

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
+seekCoachingOnNextStep({
+  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
+seekCoachingOnNextStep({
+  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/spec-phases/spec-competitor-analysis.md

@@ -0,0 +1,105 @@
+# Phase: spec-competitor-analysis
+
+## INTENT
+To conduct systematic competitive research and analysis for the feature being specified, ensuring comprehensive understanding of competitive landscape and clear differentiation strategy.
+
+## OUTCOME
+A comprehensive competitive analysis that:
+- Documents all configured competitors and their approaches
+- Identifies new competitors through systematic research
+- Proposes configuration updates with user approval
+- Defines clear differentiation strategy and competitive positioning
+- Updates the specification with complete competitive landscape analysis
+
+## TRIGGER
+This phase is triggered after `spec-spec` completion and before `spec-completeness-review`.
+
+## CONTEXT ADVANTAGES
+- **Full Feature Context**: Complete understanding of proposed feature and requirements
+- **Fresh Research**: Current competitive landscape information
+- **Strategic Positioning**: Ability to influence feature design based on competitive insights
+- **Configuration-Driven**: Systematic analysis of known competitors plus discovery of new ones
+
+## WORKFLOW
+
+### Step 1: Load Competitor Configuration
+- Read `.fraim/config.json` competitors section
+- Extract configured competitors and their competitive spaces
+- Note any existing competitive intelligence
+
+### Step 2: Research Configured Competitors
+For each competitor in config:
+- Research their current solution for this feature area
+- Analyze their strengths and weaknesses in this space
+- Gather customer feedback and reviews
+- Assess market position and pricing approach
+- Document findings in structured format
+
+### Step 3: Discover Additional Competitors
+- Use web search to find other competitors in the feature space
+- Research market for competitors not in configuration
+- Identify direct, adjacent, and emerging competitors
+- Focus on competitors specifically relevant to this feature
+
+### Step 4: Competitor Configuration Updates
+- **Identify New Competitors**: Present newly discovered competitors to user
+- **Configuration Proposal**: Suggest adding relevant competitors to `.fraim/config.json`
+- **User Approval**: Ask user to approve additions: "Found new competitor 'X' in space 'Y'. Add to config?"
+- **Auto-Update**: If user approves, automatically update configuration file
+- **Documentation**: Note configuration changes in competitive analysis
+
+### Step 5: Competitive Analysis
+- Compare competitor approaches to our proposed solution
+- Identify competitive advantages and disadvantages
+- Develop differentiation strategy
+- Plan competitive response strategies
+- Define market positioning approach
+
+### Step 6: Update Specification
+- Update Competitive Landscape section with findings
+- Ensure all configured competitors are covered
+- Include newly discovered competitors
+- Add competitive positioning strategy
+- Document research sources and methodology
+- Validate analysis completeness
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ All configured competitors analyzed
+- ✅ Additional competitors discovered through research
+- ✅ User consulted on adding new competitors to config
+- ✅ Configuration updated with user-approved competitors
+- ✅ Competitive positioning strategy defined
+- ✅ Differentiation advantages clearly articulated
+- ✅ Research sources documented
+- ✅ Analysis covers both configured and discovered competitors
+- ✅ Specification competitive landscape section updated
+
+### Report Back:
+When this phase is complete, call:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "spec",
+  issueNumber: "your-issue-number",
+  currentPhase: "spec-competitor-analysis",
+  status: "complete",
+  evidence: {
+    competitorsAnalyzed: ["competitor1", "competitor2"],
+    newCompetitorsFound: ["new-competitor1"],
+    configurationUpdated: true,
+    differentiationStrategy: "summary of strategy",
+    specificationUpdated: true
+  }
+})
+```
+
+### Phase Incomplete If:
+- Configuration competitors not fully researched
+- No additional competitor discovery attempted
+- User not consulted on configuration updates
+- Competitive positioning strategy missing
+- Specification not updated with findings
+
+## NEXT PHASE
+After completing competitor-analysis, proceed to `spec-completeness-review` phase.

package/dist/src/ai-manager/ai-manager.js

@@ -155,8 +155,11 @@ ${this.getValidPhasesForIssueType(issueType).join(' → ')}
      * Generate completion message for completed phases
      */
     async generateCompletionMessage(args) {
-        // Handle workflow completion for wait-for-pr-review phase when PR is approved
-        if (args.currentPhase === 'wait-for-pr-review') {
+        // Determine next phase and provide its instructions
+        const issueType = this.extractIssueType(args.findings, args.evidence);
+        const nextPhase = (0, phase_flow_js_1.getNextPhase)(args.currentPhase, args.workflowType, issueType);
+        if (!nextPhase) {
+            // This is the final phase - show completion message
             return `# 🎉 ${args.workflowType.charAt(0).toUpperCase() + args.workflowType.slice(1)} Complete!
 
 **Congratulations!** You have successfully completed all ${args.workflowType} phases for issue #${args.issueNumber}.
@@ -165,30 +168,11 @@ ${this.getValidPhasesForIssueType(issueType).join(' → ')}
 ${this.getAccomplishmentsForWorkflow(args.workflowType)}
 
 ## 📋 Final Evidence Summary
-${JSON.stringify(args.evidence || {}, null, 2)}
+${JSON.stringify(args.evidence || args.findings || {}, null, 2)}
 
 `;
         }
         else {
-            // Determine next phase and provide its instructions
-            const issueType = this.extractIssueType(args.findings, args.evidence);
-            const nextPhase = (0, phase_flow_js_1.getNextPhase)(args.currentPhase, args.workflowType, issueType);
-            if (!nextPhase) {
-                return `# 🎉 Phase Complete!
-
-**Phase:** ${args.currentPhase}
-**Status:** Complete
-
-Great work! You've completed the ${args.currentPhase} phase.
-
-## Evidence Summary
-${JSON.stringify(args.evidence || args.findings || {}, null, 2)}
-
-## 🚨 Error: No Next Phase Found
-Unable to determine the next phase. This might indicate an issue with the phase flow logic.
-Please check your workflow type and current phase.
-`;
-            }
             // Get instructions for the next phase
             const nextPhaseInstructions = await this.getPhaseInstructions(nextPhase, args.workflowType);
             return `# 🎉 Phase Complete!
@@ -351,9 +335,20 @@ Remember: Take your time and follow each step carefully. The phase guidance cont
      */
     async getPhaseInstructions(phase, workflowType) {
         try {
-            // Read phase instructions from .md files based on workflow type
+            // Special handling for shared phases
+            const sharedPhases = ['retrospective', 'submit-pr', 'wait-for-pr-review', 'address-pr-feedback'];
             let phasePath;
-            if (workflowType === 'implement') {
+            if (sharedPhases.includes(phase)) {
+                // Check if it's in root ai-manager-rules directory (like retrospective)
+                if (phase === 'retrospective') {
+                    phasePath = `ai-manager-rules/${phase}.md`;
+                }
+                else {
+                    // Other shared phases are in shared-phases subdirectory
+                    phasePath = `ai-manager-rules/shared-phases/${phase}.md`;
+                }
+            }
+            else if (workflowType === 'implement') {
                 phasePath = `ai-manager-rules/implement-phases/${phase}.md`;
             }
             else {
@@ -364,26 +359,35 @@ Remember: Take your time and follow each step carefully. The phase guidance cont
             if (phaseFile && (0, fs_1.existsSync)(phaseFile.fullPath)) {
                 return (0, fs_1.readFileSync)(phaseFile.fullPath, 'utf8');
             }
-            // If not found in workflow-specific directory, try shared-phases
-            const sharedPhasePath = `ai-manager-rules/shared-phases/${phase}.md`;
-            phaseFile = this.fileIndex.get(sharedPhasePath);
-            if (phaseFile && (0, fs_1.existsSync)(phaseFile.fullPath)) {
-                return (0, fs_1.readFileSync)(phaseFile.fullPath, 'utf8');
+            // If not found and not a shared phase, try shared-phases directory
+            if (!sharedPhases.includes(phase)) {
+                const sharedPhasePath = `ai-manager-rules/shared-phases/${phase}.md`;
+                phaseFile = this.fileIndex.get(sharedPhasePath);
+                if (phaseFile && (0, fs_1.existsSync)(phaseFile.fullPath)) {
+                    return (0, fs_1.readFileSync)(phaseFile.fullPath, 'utf8');
+                }
             }
             // Fallback: try to read directly from filesystem
             const { join } = require('path');
-            const possiblePaths = [
-                // Try workflow-specific paths first
-                join(process.cwd(), 'dist', 'registry', phasePath),
-                join(process.cwd(), 'registry', phasePath),
-                join(__dirname, '..', '..', 'registry', phasePath),
-                join(__dirname, '..', 'registry', phasePath),
-                // Try shared-phases paths
-                join(process.cwd(), 'dist', 'registry', sharedPhasePath),
-                join(process.cwd(), 'registry', sharedPhasePath),
-                join(__dirname, '..', '..', 'registry', sharedPhasePath),
-                join(__dirname, '..', 'registry', sharedPhasePath)
-            ];
+            const possiblePaths = [];
+            if (sharedPhases.includes(phase)) {
+                if (phase === 'retrospective') {
+                    // Retrospective is in root ai-manager-rules directory
+                    possiblePaths.push(join(process.cwd(), 'dist', 'registry', `ai-manager-rules/${phase}.md`), join(process.cwd(), 'registry', `ai-manager-rules/${phase}.md`), join(__dirname, '..', '..', 'registry', `ai-manager-rules/${phase}.md`), join(__dirname, '..', 'registry', `ai-manager-rules/${phase}.md`));
+                }
+                else {
+                    // Other shared phases are in shared-phases subdirectory
+                    const sharedPhasePath = `ai-manager-rules/shared-phases/${phase}.md`;
+                    possiblePaths.push(join(process.cwd(), 'dist', 'registry', sharedPhasePath), join(process.cwd(), 'registry', sharedPhasePath), join(__dirname, '..', '..', 'registry', sharedPhasePath), join(__dirname, '..', 'registry', sharedPhasePath));
+                }
+            }
+            else {
+                // For workflow-specific phases
+                possiblePaths.push(join(process.cwd(), 'dist', 'registry', phasePath), join(process.cwd(), 'registry', phasePath), join(__dirname, '..', '..', 'registry', phasePath), join(__dirname, '..', 'registry', phasePath));
+                // Also try shared-phases directory
+                const sharedPhasePath = `ai-manager-rules/shared-phases/${phase}.md`;
+                possiblePaths.push(join(process.cwd(), 'dist', 'registry', sharedPhasePath), join(process.cwd(), 'registry', sharedPhasePath), join(__dirname, '..', '..', 'registry', sharedPhasePath), join(__dirname, '..', 'registry', sharedPhasePath));
+            }
             for (const fullPath of possiblePaths) {
                 if ((0, fs_1.existsSync)(fullPath)) {
                     console.log(`📖 AI Coach: Reading phase file from ${fullPath}`);
@@ -392,7 +396,7 @@ Remember: Take your time and follow each step carefully. The phase guidance cont
             }
             return `# Phase: ${phase}
 
-**Error**: Phase instructions not found at ${phasePath} or ${sharedPhasePath}
+**Error**: Phase instructions not found
 
 Tried paths:
 ${possiblePaths.map(p => `- ${p}`).join('\n')}