fraim-framework 2.0.49 → 2.0.52

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/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')}

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

@@ -23,6 +23,7 @@ const BUG_PHASE_FLOW = [
     'implement-completeness-review',
     'submit-pr',
     'wait-for-pr-review',
+    'retrospective',
 ];
 const FEATURE_PHASE_FLOW = [
     'implement-scoping',
@@ -34,24 +35,29 @@ const FEATURE_PHASE_FLOW = [
     'implement-completeness-review',
     'submit-pr',
     'wait-for-pr-review',
+    'retrospective',
 ];
 const SPEC_PHASE_FLOW = [
     'spec-spec',
+    'spec-competitor-analysis',
     'spec-completeness-review',
     'submit-pr',
     'wait-for-pr-review',
+    'retrospective',
 ];
 const DESIGN_PHASE_FLOW = [
     'design-design',
     'design-completeness-review',
     'submit-pr',
     'wait-for-pr-review',
+    'retrospective',
 ];
 const TEST_PHASE_FLOW = [
     'test-test',
     'test-validate',
     'submit-pr',
     'wait-for-pr-review',
+    'retrospective',
 ];
 /**
  * Get the next phase in the workflow
@@ -169,6 +175,9 @@ function getPhaseOnFailure(failedPhase, workflowType, issueType // eslint-disabl
             case 'wait-for-pr-review':
                 // PR feedback should go to address-pr-feedback phase
                 return 'address-pr-feedback';
+            case 'retrospective':
+                // If retrospective fails, retry the same phase
+                return 'retrospective';
             case 'address-pr-feedback':
                 // If addressing PR feedback fails, retry the same phase
                 return 'address-pr-feedback';
@@ -181,12 +190,16 @@ function getPhaseOnFailure(failedPhase, workflowType, issueType // eslint-disabl
         switch (failedPhase) {
             case 'spec-spec':
                 return 'spec-spec'; // Start over at spec
+            case 'spec-competitor-analysis':
+                return 'spec-spec'; // Go back to improve spec if competitive analysis fails
             case 'spec-completeness-review':
-                return 'spec-spec'; // Go back to improve spec
+                return 'spec-spec'; // Go back to improve competitive analysis
             case 'submit-pr':
                 return 'spec-completeness-review';
             case 'wait-for-pr-review':
                 return 'address-pr-feedback'; // PR feedback goes to address phase
+            case 'retrospective':
+                return 'retrospective'; // Retry retrospective if it fails
             case 'address-pr-feedback':
                 return 'address-pr-feedback'; // Retry addressing feedback
             default:
@@ -204,6 +217,8 @@ function getPhaseOnFailure(failedPhase, workflowType, issueType // eslint-disabl
                 return 'design-completeness-review';
             case 'wait-for-pr-review':
                 return 'address-pr-feedback'; // PR feedback goes to address phase
+            case 'retrospective':
+                return 'retrospective'; // Retry retrospective if it fails
             case 'address-pr-feedback':
                 return 'address-pr-feedback'; // Retry addressing feedback
             default:
@@ -221,6 +236,8 @@ function getPhaseOnFailure(failedPhase, workflowType, issueType // eslint-disabl
                 return 'test-validate';
             case 'wait-for-pr-review':
                 return 'address-pr-feedback'; // PR feedback goes to address phase
+            case 'retrospective':
+                return 'retrospective'; // Retry retrospective if it fails
             case 'address-pr-feedback':
                 return 'address-pr-feedback'; // Retry addressing feedback
             default:

package/dist/src/cli/commands/sync.js

@@ -20,8 +20,15 @@ const runSync = async (options) => {
     const workflowsRelativePath = config.customizations?.workflowsPath || '.fraim/workflows';
     const workflowsDir = path_1.default.resolve(projectRoot, workflowsRelativePath);
     const digestPath = path_1.default.join(fraimDir, '.digest');
-    // Check for CLI updates first
-    await checkAndUpdateCLI();
+    // Check for CLI updates first (but skip during installation to prevent loops)
+    const isPostInstall = process.env.npm_lifecycle_event === 'postinstall' ||
+        process.env.npm_lifecycle_script === 'postinstall';
+    if (!options.skipUpdates && !isPostInstall) {
+        await checkAndUpdateCLI();
+    }
+    else if (isPostInstall) {
+        console.log(chalk_1.default.gray('⏭️ Skipping auto-update check during installation to prevent loops.'));
+    }
     // In npm package, stubs are in node_modules/@fraim/framework/registry/stubs/workflows
     // We need to handle both "running from source" (src/cli/commands) and "running from dist" (dist/src/cli/commands)
     // Try 4 levels up (dist/src/cli/commands -> root)
@@ -168,6 +175,14 @@ const runSync = async (options) => {
 exports.runSync = runSync;
 async function checkAndUpdateCLI() {
     try {
+        // Additional safety: check if we're in a global npm install context
+        const isGlobalInstall = process.env.npm_config_global === 'true' ||
+            process.env.npm_config_prefix ||
+            process.cwd().includes('node_modules');
+        if (isGlobalInstall) {
+            console.log(chalk_1.default.gray('⏭️ Skipping auto-update during global installation.'));
+            return;
+        }
         console.log(chalk_1.default.blue('🔍 Checking for FRAIM CLI updates...'));
         const currentVersion = (0, version_utils_1.getFraimVersion)();
         const latestVersion = await getLatestNpmVersionHttp('fraim-framework');
@@ -270,4 +285,5 @@ async function updateGlobalPackageHttp(packageName, version) {
 exports.syncCommand = new commander_1.Command('sync')
     .description('Sync workflow stubs from the framework registry')
     .option('-f, --force', 'Force sync even if digest matches')
+    .option('--skip-updates', 'Skip checking for CLI updates')
     .action(exports.runSync);

package/dist/tests/test-ai-coach-edge-cases.js

@@ -289,11 +289,16 @@ const phase_flow_js_1 = require("../src/ai-manager/phase-flow.js");
             }
         });
         (0, node_test_1.it)('should handle boundary conditions in phase flows', () => {
-            // Test last phase in each workflow
-            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'spec'), null);
-            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'design'), null);
-            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'implement', 'bug'), null);
-            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'implement', 'feature'), null);
+            // Test last phase in each workflow - retrospective is now the final phase
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('retrospective', 'spec'), null);
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('retrospective', 'design'), null);
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('retrospective', 'implement', 'bug'), null);
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('retrospective', 'implement', 'feature'), null);
+            // Test that wait-for-pr-review transitions to retrospective
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'spec'), 'retrospective');
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'design'), 'retrospective');
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'implement', 'bug'), 'retrospective');
+            node_assert_1.default.strictEqual((0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'implement', 'feature'), 'retrospective');
         });
     });
     (0, node_test_1.describe)('Concurrent Access Handling', () => {

package/dist/tests/test-ai-coach-mcp-integration.js

@@ -157,7 +157,7 @@ const shared_server_utils_js_1 = require("./shared-server-utils.js");
             node_assert_1.default.strictEqual(response.status, 200);
             const content = response.data.result.content[0];
             node_assert_1.default.ok(content.text.includes('Phase Complete!'), 'Should indicate phase completion');
-            node_assert_1.default.ok(content.text.includes('Next Phase: spec-completeness-review'), 'Should provide next phase');
+            node_assert_1.default.ok(content.text.includes('Next Phase: spec-competitor-analysis'), 'Should provide next phase');
         });
         (0, node_test_1.it)('should handle incomplete phase with help message', async () => {
             const axios = require('axios');
@@ -196,12 +196,11 @@ const shared_server_utils_js_1 = require("./shared-server-utils.js");
                     arguments: {
                         workflowType: 'spec',
                         issueNumber: '123',
-                        currentPhase: 'wait-for-pr-review',
+                        currentPhase: 'retrospective',
                         status: 'complete',
                         evidence: {
                             issueType: 'feature',
-                            prApproved: true,
-                            reviewComplete: true
+                            retrospectiveComplete: true
                         }
                     }
                 }
@@ -369,7 +368,7 @@ const shared_server_utils_js_1 = require("./shared-server-utils.js");
             });
             node_assert_1.default.strictEqual(response.status, 200);
             content = response.data.result.content[0];
-            node_assert_1.default.ok(content.text.includes('Next Phase: spec-completeness-review'), 'Should transition to review');
+            node_assert_1.default.ok(content.text.includes('Next Phase: spec-competitor-analysis'), 'Should transition to review');
             // Complete review phase
             response = await axios.post((0, shared_server_utils_js_1.getMcpEndpoint)(), {
                 jsonrpc: '2.0',
@@ -426,6 +425,25 @@ const shared_server_utils_js_1 = require("./shared-server-utils.js");
             });
             node_assert_1.default.strictEqual(response.status, 200);
             content = response.data.result.content[0];
+            node_assert_1.default.ok(content.text.includes('Next Phase: retrospective'), 'Should transition to retrospective');
+            // Complete retrospective
+            response = await axios.post((0, shared_server_utils_js_1.getMcpEndpoint)(), {
+                jsonrpc: '2.0',
+                id: 6,
+                method: 'tools/call',
+                params: {
+                    name: 'seekCoachingOnNextStep',
+                    arguments: {
+                        workflowType: 'spec',
+                        issueNumber: '999',
+                        currentPhase: 'retrospective',
+                        status: 'complete',
+                        evidence: { issueType: 'feature', retrospectiveComplete: true }
+                    }
+                }
+            });
+            node_assert_1.default.strictEqual(response.status, 200);
+            content = response.data.result.content[0];
             node_assert_1.default.ok(content.text.includes('Spec Complete!'), 'Should show completion');
         });
     });

package/dist/tests/test-ai-coach-performance.js

@@ -75,17 +75,17 @@ const path_1 = require("path");
                 evidence: { issueType: 'feature', specComplete: true }
             });
             const duration = Date.now() - startTime;
-            node_assert_1.default.ok(result.includes('Next Phase: spec-completeness-review'));
+            node_assert_1.default.ok(result.includes('Next Phase: spec-competitor-analysis'));
             node_assert_1.default.ok(duration < 1000, `Phase transition should complete within 1 second (took ${duration}ms)`);
         });
         (0, node_test_1.it)('should handle completion messages efficiently', async () => {
             const startTime = Date.now();
             const result = await coach.handleCoachingRequest({
                 workflowType: 'spec',
-                currentPhase: 'wait-for-pr-review',
+                currentPhase: 'retrospective',
                 status: 'complete',
                 issueNumber: '123',
-                evidence: { issueType: 'feature', prApproved: true }
+                evidence: { issueType: 'feature', retrospectiveComplete: true }
             });
             const duration = Date.now() - startTime;
             node_assert_1.default.ok(result.includes('Spec Complete!'));

package/dist/tests/test-ai-coach-workflows.js

@@ -53,35 +53,44 @@ const path_1 = require("path");
     });
     (0, node_test_1.describe)('Phase Flow Logic', () => {
         (0, node_test_1.it)('should return correct next phase for implement bug workflow', () => {
-            const phases = ['implement-scoping', 'implement-repro', 'implement-code', 'implement-validate', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const phases = ['implement-scoping', 'implement-repro', 'implement-code', 'implement-validate', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             for (let i = 0; i < phases.length - 1; i++) {
                 const nextPhase = (0, phase_flow_js_1.getNextPhase)(phases[i], 'implement', 'bug');
                 node_assert_1.default.strictEqual(nextPhase, phases[i + 1], `Next phase after ${phases[i]} should be ${phases[i + 1]}`);
             }
             // Last phase should return null
-            const lastPhase = (0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'implement', 'bug');
-            node_assert_1.default.strictEqual(lastPhase, null, 'wait-for-pr-review phase should return null as next phase');
+            const lastPhase = (0, phase_flow_js_1.getNextPhase)('retrospective', 'implement', 'bug');
+            node_assert_1.default.strictEqual(lastPhase, null, 'retrospective phase should return null as next phase');
         });
         (0, node_test_1.it)('should return correct next phase for implement feature workflow', () => {
-            const phases = ['implement-scoping', 'implement-spike', 'implement-code', 'implement-validate', 'implement-smoke', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const phases = ['implement-scoping', 'implement-spike', 'implement-code', 'implement-validate', 'implement-smoke', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             for (let i = 0; i < phases.length - 1; i++) {
                 const nextPhase = (0, phase_flow_js_1.getNextPhase)(phases[i], 'implement', 'feature');
                 node_assert_1.default.strictEqual(nextPhase, phases[i + 1], `Next phase after ${phases[i]} should be ${phases[i + 1]}`);
             }
+            // Last phase should return null
+            const lastPhase = (0, phase_flow_js_1.getNextPhase)('retrospective', 'implement', 'feature');
+            node_assert_1.default.strictEqual(lastPhase, null, 'retrospective phase should return null as next phase');
         });
         (0, node_test_1.it)('should return correct next phase for spec workflow', () => {
-            const phases = ['spec-spec', 'spec-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const phases = ['spec-spec', 'spec-competitor-analysis', 'spec-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             for (let i = 0; i < phases.length - 1; i++) {
                 const nextPhase = (0, phase_flow_js_1.getNextPhase)(phases[i], 'spec');
                 node_assert_1.default.strictEqual(nextPhase, phases[i + 1], `Next phase after ${phases[i]} should be ${phases[i + 1]}`);
             }
+            // Last phase should return null
+            const lastPhase = (0, phase_flow_js_1.getNextPhase)('retrospective', 'spec');
+            node_assert_1.default.strictEqual(lastPhase, null, 'retrospective phase should return null as next phase');
         });
         (0, node_test_1.it)('should return correct next phase for design workflow', () => {
-            const phases = ['design-design', 'design-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const phases = ['design-design', 'design-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             for (let i = 0; i < phases.length - 1; i++) {
                 const nextPhase = (0, phase_flow_js_1.getNextPhase)(phases[i], 'design');
                 node_assert_1.default.strictEqual(nextPhase, phases[i + 1], `Next phase after ${phases[i]} should be ${phases[i + 1]}`);
             }
+            // Last phase should return null
+            const lastPhase = (0, phase_flow_js_1.getNextPhase)('retrospective', 'design');
+            node_assert_1.default.strictEqual(lastPhase, null, 'retrospective phase should return null as next phase');
         });
         (0, node_test_1.it)('should validate phases correctly for each workflow type', () => {
             // Test implement workflow phases
@@ -110,16 +119,16 @@ const path_1 = require("path");
         });
         (0, node_test_1.it)('should return correct phases for each workflow type', () => {
             const bugPhases = (0, phase_flow_js_1.getPhasesForWorkflow)('implement', 'bug');
-            const expectedBugPhases = ['implement-scoping', 'implement-repro', 'implement-code', 'implement-validate', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const expectedBugPhases = ['implement-scoping', 'implement-repro', 'implement-code', 'implement-validate', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             node_assert_1.default.deepStrictEqual(bugPhases, expectedBugPhases);
             const featurePhases = (0, phase_flow_js_1.getPhasesForWorkflow)('implement', 'feature');
-            const expectedFeaturePhases = ['implement-scoping', 'implement-spike', 'implement-code', 'implement-validate', 'implement-smoke', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const expectedFeaturePhases = ['implement-scoping', 'implement-spike', 'implement-code', 'implement-validate', 'implement-smoke', 'implement-regression', 'implement-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             node_assert_1.default.deepStrictEqual(featurePhases, expectedFeaturePhases);
             const specPhases = (0, phase_flow_js_1.getPhasesForWorkflow)('spec');
-            const expectedSpecPhases = ['spec-spec', 'spec-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const expectedSpecPhases = ['spec-spec', 'spec-competitor-analysis', 'spec-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             node_assert_1.default.deepStrictEqual(specPhases, expectedSpecPhases);
             const designPhases = (0, phase_flow_js_1.getPhasesForWorkflow)('design');
-            const expectedDesignPhases = ['design-design', 'design-completeness-review', 'submit-pr', 'wait-for-pr-review'];
+            const expectedDesignPhases = ['design-design', 'design-completeness-review', 'submit-pr', 'wait-for-pr-review', 'retrospective'];
             node_assert_1.default.deepStrictEqual(designPhases, expectedDesignPhases);
         });
         (0, node_test_1.it)('should throw error for invalid workflow types', () => {
@@ -213,16 +222,16 @@ const path_1 = require("path");
                 evidence: { issueType: 'feature', specComplete: true }
             });
             node_assert_1.default.ok(result.includes('Phase Complete!'), 'Should indicate phase completion');
-            node_assert_1.default.ok(result.includes('Next Phase: spec-completeness-review'), 'Should provide next phase instructions');
-            node_assert_1.default.ok(result.includes('Phase: Spec-Completeness-Review'), 'Should include next phase content');
+            node_assert_1.default.ok(result.includes('Next Phase: spec-competitor-analysis'), 'Should provide next phase instructions');
+            node_assert_1.default.ok(result.includes('Phase: spec-competitor-analysis'), 'Should include next phase content');
         });
         (0, node_test_1.it)('should provide completion message for wait-for-pr-review phase', async () => {
             const result = await coach.handleCoachingRequest({
                 workflowType: 'spec',
-                currentPhase: 'wait-for-pr-review',
+                currentPhase: 'retrospective',
                 status: 'complete',
                 issueNumber: '123',
-                evidence: { issueType: 'feature', prApproved: true }
+                evidence: { issueType: 'feature', retrospectiveComplete: true }
             });
             node_assert_1.default.ok(result.includes('Spec Complete!'), 'Should show workflow completion message');
             node_assert_1.default.ok(result.includes('Congratulations!'), 'Should include congratulations');
@@ -326,10 +335,10 @@ const path_1 = require("path");
             for (const workflow of workflows) {
                 const result = await coach.handleCoachingRequest({
                     workflowType: workflow.type,
-                    currentPhase: 'wait-for-pr-review',
+                    currentPhase: 'retrospective',
                     status: 'complete',
                     issueNumber: '123',
-                    evidence: { issueType: 'feature', prApproved: true }
+                    evidence: { issueType: 'feature', retrospectiveComplete: true }
                 });
                 node_assert_1.default.ok(result.includes(workflow.expectedText), `${workflow.type} workflow should show correct accomplishments`);
             }
@@ -398,6 +407,15 @@ const path_1 = require("path");
                 issueNumber,
                 evidence: { issueType: 'feature', specComplete: true }
             });
+            node_assert_1.default.ok(result.includes('Next Phase: spec-competitor-analysis'), 'Should transition to competitor analysis');
+            // Complete competitor analysis
+            result = await coach.handleCoachingRequest({
+                workflowType,
+                currentPhase: 'spec-competitor-analysis',
+                status: 'complete',
+                issueNumber,
+                evidence: { issueType: 'feature', competitorAnalysisComplete: true }
+            });
             node_assert_1.default.ok(result.includes('Next Phase: spec-completeness-review'), 'Should transition to completeness review');
             // Complete completeness review
             result = await coach.handleCoachingRequest({
@@ -425,14 +443,23 @@ const path_1 = require("path");
                 issueNumber,
                 evidence: { issueType: 'feature', prApproved: true }
             });
+            node_assert_1.default.ok(result.includes('Next Phase: retrospective'), 'Should transition to retrospective');
+            // Complete retrospective
+            result = await coach.handleCoachingRequest({
+                workflowType,
+                currentPhase: 'retrospective',
+                status: 'complete',
+                issueNumber,
+                evidence: { issueType: 'feature', retrospectiveComplete: true }
+            });
             node_assert_1.default.ok(result.includes('Spec Complete!'), 'Should show completion message');
         });
         (0, node_test_1.it)('should complete full implement bug workflow', async () => {
             const issueNumber = '456';
             const workflowType = 'implement';
             const issueType = 'bug';
-            // Test key phases in bug workflow
-            const phases = ['implement-scoping', 'implement-repro', 'implement-code', 'wait-for-pr-review'];
+            // Test key phases in bug workflow including retrospective
+            const phases = ['implement-scoping', 'implement-repro', 'implement-code', 'wait-for-pr-review', 'retrospective'];
             for (let i = 0; i < phases.length; i++) {
                 const phase = phases[i];
                 const isLast = i === phases.length - 1;

package/dist/tests/test-pr-review-workflow.js

@@ -25,7 +25,9 @@ async function testPRReviewPhaseFlow() {
         const nextAfterSubmitPR = (0, phase_flow_js_1.getNextPhase)('submit-pr', 'implement', 'bug');
         node_assert_1.strict.equal(nextAfterSubmitPR, 'wait-for-pr-review', 'After submit-pr should go to wait-for-pr-review');
         const nextAfterWaitPR = (0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', 'implement', 'bug');
-        node_assert_1.strict.equal(nextAfterWaitPR, null, 'wait-for-pr-review should be the last phase');
+        node_assert_1.strict.equal(nextAfterWaitPR, 'retrospective', 'After wait-for-pr-review should go to retrospective');
+        const nextAfterRetrospective = (0, phase_flow_js_1.getNextPhase)('retrospective', 'implement', 'bug');
+        node_assert_1.strict.equal(nextAfterRetrospective, null, 'retrospective should be the last phase');
         console.log('✅ PR review phase flow tests passed');
         return true;
     }
@@ -187,8 +189,10 @@ async function testRealWorldPRReviewScenario() {
             currentPhase = nextPhase;
         }
         // Test PR review completion (approved)
-        const finalPhase = (0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', workflowType, issueType);
-        node_assert_1.strict.equal(finalPhase, null, 'wait-for-pr-review should be final phase when approved');
+        const nextPhaseAfterPR = (0, phase_flow_js_1.getNextPhase)('wait-for-pr-review', workflowType, issueType);
+        node_assert_1.strict.equal(nextPhaseAfterPR, 'retrospective', 'wait-for-pr-review should go to retrospective when approved');
+        const finalPhase = (0, phase_flow_js_1.getNextPhase)('retrospective', workflowType, issueType);
+        node_assert_1.strict.equal(finalPhase, null, 'retrospective should be final phase when approved');
         // Test PR review with changes requested (failure scenario)
         const failurePhase = (0, phase_flow_js_1.getPhaseOnFailure)('wait-for-pr-review', workflowType, issueType);
         node_assert_1.strict.equal(failurePhase, 'address-pr-feedback', 'PR changes requested should route to address-pr-feedback');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.49",
+  "version": "2.0.52",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -21,7 +21,7 @@
     "view-signups": "tsx scripts/view-signups.ts",
     "fraim:init": "npm run build && node bin/fraim.js init",
     "fraim:sync": "node bin/fraim.js sync",
-    "postinstall": "fraim sync || echo 'FRAIM setup skipped.'",
+    "postinstall": "fraim sync --skip-updates || echo 'FRAIM setup skipped.'",
     "prepublishOnly": "npm run build",
     "release": "npm version patch && npm publish",
     "test-smoke-ci": "tsx --test tests/test-genericization.ts tests/test-cli.ts tests/test-stub-registry.ts tests/test-sync-stubs.ts",