fraim-framework 2.0.55 → 2.0.57

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+
+## [2.1.0] - 2026-02-04
+
+### 🔄 Workflow Refinement
+- **Consolidated Workflows**: Inlined all phase content into main workflow files (`spec.md`, `design.md`, `implement.md`) for better context retention and reduced file scatter.
+- **Removed Redundant Files**: Deleted separate phase folders (`design-phases`, `implement-phases`, `spec-phases`, etc.) to streamline repository structure.
+- **Terminology Update**: Renamed "AI Coach" to "AI Mentor" across all workflows to align with new branding.
+- **Enhanced Spec Workflow**: Added `spec-competitor-analysis` phase and inlined validation steps.
+- **Retrospective Integration**: Inlined retrospective phase content into all major workflows.
+
 ## [2.0.0] - 2024-12-19
 
 ### 🚀 Major Release: FRAIM v2 - The Future of AI-Assisted Development

package/dist/src/cli/commands/init-project.js

@@ -39,18 +39,24 @@ const runInitProject = async () => {
     if (!fs_1.default.existsSync(configPath)) {
         const remoteInfo = (0, git_utils_1.getGitRemoteInfo)();
         // Git remote is optional for project init
+        const repoOwner = remoteInfo.owner || 'your-username';
+        const repoName = remoteInfo.repo || path_1.default.basename(projectRoot);
+        const repoUrl = remoteInfo.owner && remoteInfo.repo
+            ? `https://github.com/${remoteInfo.owner}/${remoteInfo.repo}.git`
+            : `https://github.com/${repoOwner}/${repoName}.git`;
         const config = {
             ...types_1.DEFAULT_FRAIM_CONFIG,
             version: (0, version_utils_1.getFraimVersion)(),
             project: {
                 ...types_1.DEFAULT_FRAIM_CONFIG.project,
-                name: remoteInfo.repo || path_1.default.basename(projectRoot)
+                name: repoName
             },
             repository: {
                 provider: 'github',
-                owner: remoteInfo.owner || 'your-username',
-                name: remoteInfo.repo || path_1.default.basename(projectRoot),
-                defaultBranch: 'main'
+                owner: repoOwner,
+                name: repoName,
+                url: repoUrl,
+                defaultBranch: remoteInfo.defaultBranch || 'main'
             }
         };
         fs_1.default.writeFileSync(configPath, JSON.stringify(config, null, 2));

package/dist/src/cli/setup/mcp-config-generator.js

@@ -18,9 +18,11 @@ const generateStandardMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            serverUrl: "https://fraim.wellnessatwork.me",
-            headers: {
-                "x-api-key": fraimKey
+            command: "npx",
+            args: ["-y", "fraim-mcp"],
+            env: {
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }
@@ -44,10 +46,11 @@ const generateClaudeMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            type: "http",
-            url: "https://fraim.wellnessatwork.me",
-            headers: {
-                "x-api-key": fraimKey
+            command: "npx",
+            args: ["-y", "fraim-mcp"],
+            env: {
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }
@@ -70,9 +73,11 @@ const generateKiroMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            url: "https://fraim.wellnessatwork.me",
-            headers: {
-                "x-api-key": fraimKey
+            command: "npx",
+            args: ["-y", "fraim-mcp"],
+            env: {
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }
@@ -92,10 +97,12 @@ command = "npx"
 args = ["-y", "@playwright/mcp"]
 
 [mcp_servers.fraim]
-url = "https://fraim.wellnessatwork.me/"
+command = "npx"
+args = ["-y", "fraim-mcp"]
 
-[mcp_servers.fraim.headers]
-x-api-key = "${fraimKey}"
+[mcp_servers.fraim.env]
+FRAIM_API_KEY = "${fraimKey}"
+FRAIM_REMOTE_URL = "https://fraim.wellnessatwork.me"
 `;
 exports.generateCodexMCPServers = generateCodexMCPServers;
 const generateWindsurfMCPServers = (fraimKey, githubToken) => ({
@@ -117,9 +124,10 @@ const generateWindsurfMCPServers = (fraimKey, githubToken) => ({
         },
         fraim: {
             command: "npx",
-            args: ["-y", "@modelcontextprotocol/server-fetch", "https://fraim.wellnessatwork.me"],
+            args: ["-y", "fraim-mcp"],
             env: {
-                FRAIM_API_KEY: fraimKey
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }

package/dist/src/local-mcp-server/stdio-server.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * FRAIM Local MCP Server - STDIO Version
+ *
+ * Simple proxy that:
+ * 1. Accepts MCP requests via stdin/stdout
+ * 2. Proxies to remote FRAIM server
+ * 3. Performs template substitution using local .fraim/config.json
+ * 4. Returns processed content to agent
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FraimLocalMCPServer = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const axios_1 = __importDefault(require("axios"));
+class FraimLocalMCPServer {
+    constructor() {
+        this.config = null;
+        this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        this.apiKey = process.env.FRAIM_API_KEY || '';
+        if (!this.apiKey) {
+            this.logError('❌ FRAIM_API_KEY environment variable is required');
+            process.exit(1);
+        }
+        this.loadConfig();
+        this.log('🚀 FRAIM Local MCP Server starting...');
+        this.log(`📡 Remote server: ${this.remoteUrl}`);
+        this.log(`🔑 API key: ${this.apiKey.substring(0, 10)}...`);
+    }
+    log(message) {
+        // Log to stderr (stdout is reserved for MCP protocol)
+        console.error(`[FRAIM] ${message}`);
+    }
+    logError(message) {
+        console.error(`[FRAIM ERROR] ${message}`);
+    }
+    loadConfig() {
+        try {
+            const configPath = (0, path_1.join)(process.cwd(), '.fraim', 'config.json');
+            if ((0, fs_1.existsSync)(configPath)) {
+                const configContent = (0, fs_1.readFileSync)(configPath, 'utf8');
+                this.config = JSON.parse(configContent);
+                this.log('✅ Loaded local .fraim/config.json');
+            }
+            else {
+                this.log('⚠️ No .fraim/config.json found - template substitution disabled');
+            }
+        }
+        catch (error) {
+            this.logError(`Failed to load config: ${error}`);
+            this.config = null;
+        }
+    }
+    /**
+     * Substitute template variables in content
+     * Replaces {{config.path.to.value}} with actual values from config
+     */
+    substituteTemplates(content) {
+        if (!this.config)
+            return content;
+        return content.replace(/\{\{config\.([^}]+)\}\}/g, (match, path) => {
+            try {
+                const keys = path.split('.');
+                let value = this.config;
+                for (const key of keys) {
+                    if (value && typeof value === 'object' && key in value) {
+                        value = value[key];
+                    }
+                    else {
+                        // Keep original placeholder if path not found
+                        return match;
+                    }
+                }
+                return String(value);
+            }
+            catch (error) {
+                // Keep original placeholder on error
+                return match;
+            }
+        });
+    }
+    /**
+     * Process template substitution in MCP response
+     */
+    processResponse(response) {
+        if (!response.result)
+            return response;
+        // Process content fields that might contain templates
+        const processValue = (value) => {
+            if (typeof value === 'string') {
+                return this.substituteTemplates(value);
+            }
+            else if (Array.isArray(value)) {
+                return value.map(processValue);
+            }
+            else if (value && typeof value === 'object') {
+                const processed = {};
+                for (const [key, val] of Object.entries(value)) {
+                    processed[key] = processValue(val);
+                }
+                return processed;
+            }
+            return value;
+        };
+        return {
+            ...response,
+            result: processValue(response.result)
+        };
+    }
+    /**
+     * Proxy request to remote FRAIM server
+     */
+    async proxyToRemote(request) {
+        try {
+            const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, request, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                timeout: 30000
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.logError(`Remote request failed: ${error.message}`);
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: -32603,
+                    message: `Remote server error: ${error.message}`
+                }
+            };
+        }
+    }
+    /**
+     * Handle incoming MCP request
+     */
+    async handleRequest(request) {
+        this.log(`📥 ${request.method}`);
+        // Proxy to remote server
+        const response = await this.proxyToRemote(request);
+        // Process template substitution
+        const processedResponse = this.processResponse(response);
+        this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
+        return processedResponse;
+    }
+    /**
+     * Start STDIO server
+     */
+    start() {
+        let buffer = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', async (chunk) => {
+            buffer += chunk;
+            // Process complete JSON-RPC messages (newline-delimited)
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line) {
+                    try {
+                        const request = JSON.parse(line);
+                        const response = await this.handleRequest(request);
+                        // Send response to stdout
+                        process.stdout.write(JSON.stringify(response) + '\n');
+                    }
+                    catch (error) {
+                        this.logError(`Request processing failed: ${error.message}`);
+                        // Send error response
+                        const errorResponse = {
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32700,
+                                message: `Parse error: ${error.message}`
+                            }
+                        };
+                        process.stdout.write(JSON.stringify(errorResponse) + '\n');
+                    }
+                }
+            }
+        });
+        process.stdin.on('end', () => {
+            this.log('🛑 Stdin closed, shutting down...');
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            this.log('🛑 SIGTERM received, shutting down...');
+            process.exit(0);
+        });
+        process.on('SIGINT', () => {
+            this.log('🛑 SIGINT received, shutting down...');
+            process.exit(0);
+        });
+        this.log('✅ FRAIM Local MCP Server ready');
+    }
+}
+exports.FraimLocalMCPServer = FraimLocalMCPServer;
+// Start server if run directly
+if (require.main === module) {
+    const server = new FraimLocalMCPServer();
+    server.start();
+}

package/dist/src/utils/validate-workflows.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAllWorkflows = validateAllWorkflows;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const workflow_parser_js_1 = require("./workflow-parser.js");
+/**
+ * Validate all workflows in the registry
+ */
+function validateAllWorkflows(registryPath) {
+    const errors = [];
+    const workflowFiles = [];
+    function findWorkflows(dir) {
+        if (!(0, fs_1.existsSync)(dir))
+            return;
+        const entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory()) {
+                findWorkflows(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                const content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+                if (content.includes('"initialPhase"')) {
+                    workflowFiles.push(fullPath);
+                }
+            }
+        }
+    }
+    findWorkflows(registryPath);
+    console.log(`🔍 Validating ${workflowFiles.length} workflows...`);
+    for (const filePath of workflowFiles) {
+        const relativePath = filePath.replace(registryPath, '');
+        try {
+            const wf = workflow_parser_js_1.WorkflowParser.parse(filePath);
+            if (!wf) {
+                errors.push(`❌ ${relativePath}: Failed to parse. Ensure JSON metadata is present and valid.`);
+                continue;
+            }
+            const { metadata, phases } = wf;
+            // 1. Initial Phase check
+            if (!phases.has(metadata.initialPhase)) {
+                errors.push(`❌ ${relativePath}: initialPhase "${metadata.initialPhase}" does not exist in phases.`);
+            }
+            // 2. Validate Phase Flow
+            for (const [phaseId, flow] of Object.entries(metadata.phases)) {
+                // Check if phase exists in markdown
+                if (!phases.has(phaseId)) {
+                    errors.push(`❌ ${relativePath}: Phase "${phaseId}" defined in metadata but missing in markdown.`);
+                }
+                // Check Success transition
+                if (flow.onSuccess && flow.onSuccess !== 'null') {
+                    if (typeof flow.onSuccess === 'string') {
+                        if (!phases.has(flow.onSuccess)) {
+                            errors.push(`❌ ${relativePath}: Phase "${phaseId}" transition onSuccess -> "${flow.onSuccess}" target not found.`);
+                        }
+                    }
+                    else {
+                        // Validate each branch of conditional success
+                        for (const [branch, target] of Object.entries(flow.onSuccess)) {
+                            if (target && target !== 'null' && !phases.has(target)) {
+                                errors.push(`❌ ${relativePath}: Phase "${phaseId}" conditional transition onSuccess[${branch}] -> "${target}" target not found.`);
+                            }
+                        }
+                    }
+                }
+                // Check Failure transition
+                if (flow.onFailure && !phases.has(flow.onFailure)) {
+                    errors.push(`❌ ${relativePath}: Phase "${phaseId}" transition onFailure -> "${flow.onFailure}" target not found.`);
+                }
+            }
+            // 3. Check for orphaned phases in markdown
+            for (const phaseId of phases.keys()) {
+                if (!metadata.phases[phaseId]) {
+                    errors.push(`⚠️  ${relativePath}: Phase "${phaseId}" exists in markdown but is NOT defined in JSON metadata.`);
+                }
+            }
+        }
+        catch (e) {
+            errors.push(`❌ ${relativePath}: Unexpected error: ${e.message}`);
+        }
+    }
+    return {
+        valid: errors.filter(e => e.startsWith('❌')).length === 0,
+        errors
+    };
+}
+// Run if called directly
+if (process.argv[1]?.includes('validate-workflows')) {
+    const registryPath = process.argv[2] || (0, path_1.join)(process.cwd(), 'registry');
+    const result = validateAllWorkflows(registryPath);
+    result.errors.forEach(err => console.error(err));
+    if (result.valid) {
+        console.log('✅ All workflows validated successfully.');
+        process.exit(0);
+    }
+    else {
+        console.error('❌ Workflow validation failed.');
+        process.exit(1);
+    }
+}

package/dist/src/utils/workflow-parser.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowParser = void 0;
+const fs_1 = require("fs");
+class WorkflowParser {
+    /**
+     * Parse a workflow markdown file into a structured definition
+     */
+    static parse(filePath) {
+        if (!(0, fs_1.existsSync)(filePath))
+            return null;
+        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        // 1. Extract JSON Metadata
+        const metadataMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+        if (!metadataMatch)
+            return null;
+        let metadata;
+        try {
+            metadata = JSON.parse(metadataMatch[1]);
+        }
+        catch (e) {
+            console.error(`❌ Failed to parse JSON metadata in ${filePath}:`, e);
+            return null;
+        }
+        // 2. Extract Overview (Content after metadata but before first phase header)
+        const contentAfterMetadata = content.substring(metadataMatch[0].length).trim();
+        const firstPhaseIndex = contentAfterMetadata.search(/^##\s+Phase:/m);
+        let overview = '';
+        let restOfContent = '';
+        if (firstPhaseIndex !== -1) {
+            overview = contentAfterMetadata.substring(0, firstPhaseIndex).trim();
+            restOfContent = contentAfterMetadata.substring(firstPhaseIndex);
+        }
+        else {
+            overview = contentAfterMetadata;
+        }
+        // 3. Extract Phases (id -> content)
+        const phases = new Map();
+        const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
+        // Skip the first part (empty or overview overlap)
+        for (let i = 1; i < phaseSections.length; i++) {
+            const section = phaseSections[i];
+            const sectionLines = section.split('\n');
+            const firstLine = sectionLines[0].trim();
+            // Extract phase ID (slug before any (Phase X) or space)
+            const id = firstLine.split(/[ (]/)[0].trim().toLowerCase();
+            // The content includes the header (we'll reconstruct it for the agent or just return the body)
+            // But usually, the agent wants the whole section including the Phase ID header.
+            // We'll store the whole section but prepend the header because split removed it.
+            phases.set(id, `## Phase: ${section.trim()}`);
+        }
+        return {
+            metadata,
+            overview,
+            phases
+        };
+    }
+    /**
+     * Extract description for listing workflows (intent or first para of overview)
+     */
+    static extractDescription(filePath) {
+        const wf = this.parse(filePath);
+        if (!wf)
+            return '';
+        // Try to find Intent section in overview
+        const intentMatch = wf.overview.match(/## Intent\s+([\s\S]+?)(?:\r?\n##|$)/);
+        if (intentMatch)
+            return intentMatch[1].trim().split(/\r?\n/)[0];
+        // Fallback to first non-header line
+        const firstPara = wf.overview.split(/\r?\n/).find(l => l.trim() !== '' && !l.startsWith('#'));
+        return firstPara ? firstPara.trim() : '';
+    }
+    /**
+     * Get just the overview for an agent starting a workflow
+     */
+    static getOverview(filePath) {
+        const wf = this.parse(filePath);
+        return wf ? wf.overview : null;
+    }
+}
+exports.WorkflowParser = WorkflowParser;

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.55",
+  "version": "2.0.57",
   "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": {
     "fraim": "./index.js",
-    "fraim-setup": "./index.js"
+    "fraim-mcp": "./bin/fraim-mcp.js"
   },
   "scripts": {
-    "setup": "node setup.js",
     "dev": "tsx --watch src/fraim-mcp-server.ts",
     "build": "tsc && node scripts/copy-ai-manager-rules.js && npm run build:stubs && npm run validate:registry",
     "build:stubs": "tsx scripts/build-stub-registry.ts",
@@ -26,7 +25,8 @@
     "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",
     "test-all-ci": "tsx --test tests/test-*.ts",
-    "validate:registry": "tsx scripts/verify-registry-paths.ts"
+    "validate:registry": "tsx scripts/verify-registry-paths.ts && npm run validate:workflows",
+    "validate:workflows": "tsx scripts/validate-workflows.ts"
   },
   "repository": {
     "type": "git",
@@ -69,14 +69,19 @@
     "typescript": "^5.0.0"
   },
   "files": [
-    "dist/",
+    "dist/src/local-mcp-server/",
+    "dist/src/cli/",
+    "dist/src/fraim/",
+    "dist/src/utils/",
     "registry/stubs/",
     "registry/scripts/",
-    "bin/",
-    "*.js",
-    "*.ts",
-    "*.md",
-    "*.json"
+    "bin/fraim.js",
+    "bin/fraim-mcp.js",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "package.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -92,7 +97,7 @@
     "markdown-it-highlightjs": "^4.2.0",
     "mongodb": "^7.0.0",
     "prompts": "^2.4.2",
-    "puppeteer": "^24.35.0",
+    "puppeteer": "^24.36.1",
     "sharp": "^0.34.5",
     "tree-kill": "^1.2.2"
   }