fraim 2.0.100

package/README.md

@@ -0,0 +1,445 @@
+# 🚀 FRAIM: Framework for Rigor-based AI Management
+**"FRAIM is a step towards the future of how we work."** - Transforming ideas into production code by converting you into an AI manager orchestrating multiple agents with enterprise-grade discipline.
+
+
+🚀 **The Problem with AI Coding Today**
+
+Current "vibe coding" frameworks are great at getting from idea to prototype. They fail spectacularly at going from prototype to production or evolving complex codebases.
+
+AI agents are like brilliant but inexperienced developers. They need:
+• Clear guardrails to prevent costly mistakes
+• Structured workflows to avoid chaos
+• Evidence-based validation (not "looks good" claims)
+• Learning systems to improve over time
+• Balance between determinism and creativity
+
+🎯 **Introducing FRAIM: Framework for Rigor-based AI Management**
+
+FRAIM transforms you from a solo developer into an AI manager orchestrating multiple agents with enterprise-grade discipline.
+
+**The Transformation:**
+❌ Before: "It's working now. The login button exists."
+✅ After: "Implementation complete. 12/12 tests pass, API endpoint validated, UI screenshots provided."
+
+**Real Results:**
+• Dramatic reduction in AI-generated code that needs rework
+• Faster delivery through structured workflows
+• Higher test coverage through mandatory evidence collection
+• Zero agent conflicts through phase-based coordination
+
+**The RIGOR Methodology:**
+R - Reviews: Structured feedback with evidence
+I - Isolation: Agents don't interfere unless coordinated
+G - GitOps: Git as single source of truth
+O - Observability: Complete visibility into AI activities
+R - Retrospectives: Continuous learning from experience
+
+🤖 **Works with any AI agent** (Cursor, Claude, Windsurf) - no vendor lock-in.
+
+**The bottom line:** FRAIM isn't just about using AI—it's about managing AI teams with the same discipline you'd apply to human developers.
+
+
+
+### The Human-Developer Parallel
+
+| **Human Development** | **AI Agent Development** | **FRAIM Solution** |
+|----------------------|-------------------------|-------------------|
+| **Code Reviews** | Random quality checks | Structured review workflows with evidence requirements |
+| **Testing Standards** | "Looks good" claims | Mandatory test evidence with failure reproduction |
+| **Team Coordination** | Agent conflicts and overlaps | Phase-based isolation with clear handoffs |
+| **Learning Culture** | Repeated mistakes | Retrospective-driven improvement system |
+| **Process Discipline** | Ad-hoc approaches | Proven workflows and deterministic scripts from real projects |
+| **Quality Gates** | Unreliable outcomes | Deterministic validation with rollback capabilities |
+
+
+## 🔥 The Problems FRAIM Solves
+
+### ❌ **The Current State of AI Development**
+- **"Looks Good" Syndrome**: Agents claim success without evidence
+- **Quality Lottery**: Inconsistent code quality and reliability
+- **Agent Chaos**: Multiple agents stepping on each other's work
+- **No Learning**: Repeated mistakes without improvement
+- **Ad-hoc Processes**: Every project reinvents the wheel
+- **False Confidence**: Broken code marked as "working"
+- **Hanging Agents**: Commands that hang requiring human intervention
+- **Lost Output**: No visibility into long-running task progress
+
+### ✅ **The FRAIM Solution**
+
+#### 🛡️ **Agent Integrity & Test Ethics** 
+**Problem**: Agents claim "tests pass" when they actually fail
+**Solution**: Mandatory evidence collection, test immutability rules, and accountability frameworks
+```bash
+# Before FRAIM: "Tests look good!"
+# After FRAIM: "Here's the test output proving all 47 tests pass"
+```
+
+#### 🧪 **Comprehensive Testing Guidelines** 
+**Problem**: Superficial testing that misses real issues
+**Solution**: Multi-layer validation (database, API, UI, integration) with mandatory evidence
+```bash
+# Before: Mock everything, hope it works
+# After: Test real systems, prove it works, show evidence
+```
+
+#### 🗣️ **Clear Communication Standards** 
+**Problem**: Vague progress reports and unclear accountability
+**Solution**: Structured progress updates with concrete evidence and absolute accountability
+```bash
+# Before: "Working on it, almost done"
+# After: "Fixed API timeout, tests passing, evidence attached, ready for review"
+```
+
+#### 🏗️ **Architectural Discipline** 
+**Problem**: Agents create architectural chaos and technical debt
+**Solution**: Clean separation of concerns, type safety, and testability patterns
+```bash
+# Before: Spaghetti code with mixed responsibilities
+# After: Clean layers with proper boundaries and validation
+```
+
+#### 🎯 **Spike-First Development** 
+**Problem**: Agents build complex solutions without validating assumptions
+**Solution**: 5-15 minute proof-of-concepts before major implementation
+```bash
+# Before: Build 3-week solution, discover it doesn't work
+# After: 10-minute spike, validate approach, then build confidently
+```
+
+#### 🔄 **Continuous Learning System** 
+**Problem**: Same mistakes repeated across projects
+**Solution**: Retrospective-driven knowledge capture and pattern recognition
+```bash
+# Before: Every agent learns the same lessons from scratch
+# After: Knowledge accumulates, patterns emerge, quality improves
+```
+
+#### 🧹 **Simplicity Discipline** 
+**Problem**: Over-engineered solutions that are hard to maintain
+**Solution**: "Keep it simple" principles with complexity budgets
+```bash
+# Before: 500-line solution to a 10-line problem
+# After: Minimal, focused solution that actually works
+```
+
+#### 🔧 **Git Safety & Timeout Management**
+**Problem**: Agents hang on interactive Git commands and long-running tasks, requiring human intervention
+**Solution**: Safe Git commands and timeout scripts with output visibility
+```bash
+# Before: Agent hangs on "git log" (opens pager) or tests run forever
+# After: Non-interactive commands with timeouts and log files for visibility
+# Example: exec-with-timeout.ts runs tests with timeout and saves output to files
+```
+
+#### 🔄 **Merge Requirements & Branch Safety** 
+**Problem**: Agents accidentally overwrite master branch or create merge conflicts
+**Solution**: Mandatory rebase workflows with conflict resolution patterns
+```bash
+# Before: Force pushes that destroy other work
+# After: Rebase-on-master with force-with-lease for safety
+```
+
+#### 🐛 **Systematic Debugging Patterns** 
+**Problem**: Agents struggle with complex debugging and repeat the same mistakes
+**Solution**: Structured debugging methodology with evidence collection and pattern recognition
+```bash
+# Before: Random debugging attempts, no learning
+# After: Systematic approach with documented patterns and regression tests
+```
+
+#### 📋 **Package Scripts & Output Visibility**
+**Problem**: Long-running tasks hang agents and provide no visibility into progress
+**Solution**: Background execution with log files and timeout management
+```bash
+# Before: "npm test" hangs agent, no output visibility
+# After: "npm test" runs in background, saves to test.log, agent can observe progress
+# Example: exec-with-timeout.ts prevents hangs and provides output visibility
+```
+
+## 🚀 **Proven Benefits from Real Projects**
+
+- **Dramatic reduction** in AI-generated code that needs rework through evidence-based validation
+- **Faster delivery** through structured workflows and clear handoffs
+- **Higher test coverage** through mandatory testing guidelines and evidence collection
+- **Zero agent conflicts** through phase-based isolation and coordination
+- **Complete accountability** - agents fix their own mistakes with evidence
+
+## 🎬 **The FRAIM Experience: From Chaos to Clarity**
+
+### **Before FRAIM: Single Agent Chaos**
+```bash
+# You: "Add user authentication to the app"
+# Agent: "I'll add login functionality"
+# 
+# 10 minutes later...
+# Agent: "I've designed the UX to be modern and beautiful. What do you think?"
+# You: "It's way too complex and does not work with the rest of the product. Just make it simple"
+# Agent: "You are right. I've made it too complex, let me simplify it right now"
+# You: "I've told you this 10 times already!!!! "
+# 
+# 1 hour later...
+# Agent: "Implementation complete. Solution looks good."
+# You: "I get an error on the first screen."
+# Agent: "What error do you see? Can you write it out for me or give me a screenshot?"
+# You: "C'mon, do this yourself."
+# 
+# 2 hours later...
+# Agent: <Stuck waiting for a playwright test which hasn't relinquished control>
+# You: "You've made no progress"
+# Agent: "You are right. I keep getting stuck. Could you test the implementation for me?"
+# 
+# 3 hours later...
+# Agent: "Ok I'm all done, test cases are passing"
+# You: "Wait, what... you changed existing tests to make them pass ... everything is broken!!"
+```
+
+### **After FRAIM: Single Agent Excellence**
+```bash
+# You: "Add user authentication to the app"
+# Agent: "Starting design phase. Creating RFC with UX mockups, validation rules, and API specs"
+# 
+# 10 minutes later...
+# Agent: "Design complete. UX mockups created, validation rules defined, API endpoints specified. 
+#         Evidence: 3 mockup images, validation requirements document, API spec ready for review"
+# You: "Looks good, proceed to implementation"
+# 
+# 1 hour later...
+# Agent: "Implementation complete. Code written, tests created, all tests passing.
+#         Evidence: Test output showing existing 120/120 tests pass, new 12/12 tests pass, API endpoint tested with curl,
+#         UI tested with screenshots showing login form and error states"
+# During PR review...
+# Reviewer: "Password validation is too strict"
+# Agent: "Fixed password validation rules, updated tests, evidence provided.
+#         Evidence: New test output showing updated validation, UI screenshots with new rules"
+# 
+# Result: In best case, hours of frustration, rework saved. In worst case, reputation saved from deploying broken code to production.
+```
+
+## 🏗️ **Enterprise-Grade Framework Structure**
+
+## 🚀 **Get Started in 60 Seconds**
+
+### **⚠️ Prerequisites**
+
+**Shell Requirements:**
+- **Windows**: Must use Git Bash (install from https://git-scm.com/download/win)
+- **macOS/Linux**: Default terminal works fine
+
+**Why Git Bash on Windows?** All FRAIM scripts use Unix-style paths and Bash commands. Git Bash ensures consistent behavior across platforms.
+
+### **Install & Initialize**
+
+**Recommended: Use npx (no installation needed)**
+```bash
+npx fraim-framework@latest setup --key=<your-fraim-key>
+
+# Optional: Create alias for convenience
+echo 'alias fraim="npx fraim-framework"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Alternative: Global install**
+```bash
+npm install -g fraim-framework
+fraim setup --key=<your-fraim-key>
+```
+
+> **💡 Why npx?** Works with any Node version (16+), no conflicts when switching Node versions, always uses correct dependencies, and identical functionality to global install. Perfect for users with nvm, volta, or multiple Node versions.
+
+The setup command supports three modes:
+
+**Conversational Mode**: AI workflows only, no platform integration required
+```bash
+fraim setup --key=<your-fraim-key>
+# Select "Conversational Mode" when prompted
+```
+
+**Integrated Mode**: Single platform for both code hosting and issue tracking
+```bash
+fraim setup --key=<your-fraim-key>
+# Select "Integrated Mode" when prompted
+# Choose platform: GitHub, Azure DevOps, or GitLab
+```
+
+**Split Mode**: Separate platforms for code hosting and issue tracking
+```bash
+fraim setup --key=<your-fraim-key>
+# Select "Split Mode" when prompted
+# Choose code repository platform: GitHub, Azure DevOps, or GitLab
+# Choose issue tracking platform: GitHub, Azure DevOps, GitLab, or Jira
+```
+
+Common Split mode combinations:
+- GitHub (code) + Jira (issues)
+- GitLab (code) + Jira (issues)
+- Azure DevOps (code) + GitHub (issues)
+
+### **🔧 Additional Commands**
+
+After initial setup, you can use these commands:
+
+```bash
+# Add FRAIM to additional IDEs (after initial setup)
+fraim add-ide --ide claude          # Configure specific IDE
+fraim add-ide --ide antigravity     # Configure Gemini Antigravity
+fraim add-ide --all                 # Configure all detected IDEs
+fraim add-ide --list                # List supported IDEs
+
+# Add platform integrations to existing setup
+fraim setup --github                # Add GitHub integration
+fraim setup --ado                   # Add Azure DevOps integration
+fraim setup --gitlab                # Add GitLab integration
+fraim setup --jira                  # Add Jira integration
+
+# Project initialization
+fraim init-project                  # Initialize FRAIM in current project
+
+# Testing and validation
+fraim doctor --test-mcp            # Test MCP server connections
+fraim doctor                        # Diagnose configuration issues
+
+# Sync and maintenance
+fraim sync                          # Sync latest workflows and rules
+```
+
+**💡 Pro Tip**: Use `fraim add-ide` when you install a new IDE after initial setup. It reuses your existing FRAIM and platform tokens, making it much faster than running full setup again.
+
+### **🧩 Personalized Jobs, Skills, and Rules**
+
+Project-specific customization now lives under `.fraim/personalized-employee/`.
+
+Recommended layout:
+
+```text
+.fraim/
+  personalized-employee/
+    jobs/
+    skills/
+    rules/
+    templates/
+```
+
+Use `fraim override` to create a local starting point:
+
+```bash
+fraim override --inherit jobs/product-building/feature-implementation.md
+fraim override --copy rules/engineering/architecture-standards.md
+```
+
+Guidance:
+- Put phased job customizations in `.fraim/personalized-employee/jobs/...`
+- Put reusable local capability snippets in `.fraim/personalized-employee/skills/...`
+- Put broad team conventions in `.fraim/personalized-employee/rules/...`
+- Put local deliverable tweaks in `.fraim/personalized-employee/templates/...`
+- Do not edit synced content under `.fraim/ai-employee/` or `.fraim/ai-manager/`; `fraim sync` will overwrite it
+- Legacy `.fraim/overrides/` is still read for compatibility, but new work should go in `.fraim/personalized-employee/`
+
+### **🔧 Jira Integration Setup**
+
+FRAIM uses the official Model Context Protocol (MCP) server for Jira integration. The setup command automatically configures the correct format.
+
+**Jira API Token Requirements**:
+1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
+2. Click "Create API token"
+3. Give it a name (e.g., "FRAIM Integration")
+4. Copy the token (starts with ATATT3...)
+5. Use this token during `fraim setup`
+
+**Correct MCP Configuration** (automatically generated):
+```json
+{
+  "jira": {
+    "command": "uvx",
+    "args": ["mcp-atlassian"],
+    "env": {
+      "JIRA_URL": "https://mycompany.atlassian.net",
+      "JIRA_USERNAME": "user@mycompany.com",
+      "JIRA_API_TOKEN": "your-token-here"
+    }
+  }
+}
+```
+
+**⚠️ Common Issues**:
+- **Old package name**: If you see `@modelcontextprotocol/server-jira` in your config, this package doesn't exist. Run `fraim setup --jira` to update to the correct `mcp-atlassian` package.
+- **Token format**: Jira API tokens typically start with `ATATT3`. If your token doesn't match this format, verify you created an API token (not a personal access token).
+- **First run slow**: The first time `uvx` runs the Jira MCP server, it downloads the package. This is normal and only happens once.
+
+**Troubleshooting**:
+```bash
+# Test Jira MCP connection
+fraim doctor --test-mcp
+
+# Reconfigure Jira integration
+fraim setup --jira
+
+# Check configuration
+cat ~/.kiro/settings/mcp.json  # For Kiro IDE
+cat ~/Library/Application\ Support/Claude/claude_desktop_config.json  # For Claude Desktop (macOS)
+```
+
+
+## 🌟 **Why FRAIM is the Future**
+
+### **1. Proven in Production**
+Every rule, workflow, and pattern has been tested in real projects. This isn't theoretical—it's battle-tested.
+
+### **2. Enterprise Discipline**
+The same rigor you'd apply to managing human developers, applied to AI agents.
+
+### **3. Continuous Improvement**
+Built-in learning systems that make your AI agents better over time.
+
+### **4. Complete Transparency**
+Full visibility into what each agent is doing, with evidence-based validation.
+
+### **5. Zero Vendor Lock-in**
+Works with any AI agent (Cursor, Claude, Windsurf, future agents).
+
+
+## 🚀 **Ready to Transform Your Development?**
+
+### **Start Your AI Management Journey**
+
+```bash
+# Watch the magic happen
+gh issue create --title "Add API rate limiting" --label "phase:design"
+# → Agent: "RFC created, architecture validated, ready for implementation"
+
+gh issue edit 123 --remove-label "phase:design" --add-label "phase:impl"
+# → Agent: "Implementation complete, tests passing, evidence provided"
+
+gh issue edit 123 --remove-label "phase:impl" --add-label "phase:tests"
+# → Agent: "Performance validated, security checked, ready for production"
+
+# Result: Production-ready feature in 2 hours instead of 2 days
+```
+
+
+
+### **Join the Future of Development**
+
+- 🌟 [**GitHub Repository**](https://github.com/mathursrus/FRAIM) - Star us to follow development
+- 🐛 [**Issue Tracker**](https://github.com/mathursrus/FRAIM/issues) - Report bugs or request features
+
+---
+
+## 🎯 **The Bottom Line**
+
+**FRAIM isn't just about using AI—it's about managing AI teams with the same discipline you'd apply to human teams.**
+
+Stop fighting with AI agents. Start orchestrating them.
+
+**This is the future of how we work.**
+
+---
+
+<div align="center">
+
+**🚀 Ready to become an AI manager? Start with FRAIM today.**
+
+[![npm version](https://img.shields.io/npm/v/fraim-framework.svg)](https://www.npmjs.com/package/fraim-framework)
+[![GitHub stars](https://img.shields.io/github/stars/mathursrus/FRAIM.svg)](https://github.com/mathursrus/FRAIM/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>

package/bin/fraim.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * FRAIM Framework CLI Entry Point
+ *
+ * This file delegates to the compiled TypeScript implementation.
+ */
+
+try {
+    // In production/installed package, code is in dist/
+    require('../dist/src/cli/fraim.js');
+} catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') {
+        // In development (local clone), we might use tsx if dist is missing
+        // But typically we should just tell user to build.
+        console.error('❌ Could not find FRAIM CLI implementation.');
+        console.error('   If you are running from source, please run "npm run build" first.');
+        console.error(`   Error details: ${error.message}`);
+        process.exit(1);
+    } else {
+        throw error;
+    }
+}

package/dist/src/cli/api/get-provider-client.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProviderClient = getProviderClient;
+// Helper to get provider client with FRAIM key from config
+const provider_client_1 = require("./provider-client");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+/**
+ * Get user FRAIM directory
+ */
+function getUserFraimDir() {
+    return process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim');
+}
+/**
+ * Get provider client using FRAIM key from global config
+ * Throws error if no config found - caller should handle and use local fallback
+ */
+function getProviderClient() {
+    const globalConfigPath = path_1.default.join(getUserFraimDir(), 'config.json');
+    if (!fs_1.default.existsSync(globalConfigPath)) {
+        throw new Error('No FRAIM configuration found');
+    }
+    try {
+        const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
+        const fraimKey = config.apiKey;
+        if (!fraimKey) {
+            throw new Error('FRAIM API key not found in config');
+        }
+        // Use FRAIM_REMOTE_URL if set (for tests or custom deployments)
+        // Otherwise ProviderClient will use its default
+        const serverUrl = process.env.FRAIM_REMOTE_URL || undefined;
+        return new provider_client_1.ProviderClient(fraimKey, serverUrl);
+    }
+    catch (error) {
+        throw new Error(`Failed to load FRAIM configuration: ${error.message}`);
+    }
+}

package/dist/src/cli/api/provider-client.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderClient = void 0;
+// CLI client for fetching provider metadata from server
+const axios_1 = __importDefault(require("axios"));
+class ProviderClient {
+    constructor(fraimKey, serverUrl) {
+        this.serverUrl = serverUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        this.client = axios_1.default.create({
+            baseURL: this.serverUrl,
+            headers: {
+                'x-api-key': fraimKey,
+                'Content-Type': 'application/json'
+            },
+            timeout: 10000 // 10 second timeout
+        });
+    }
+    /**
+     * Get all providers from server
+     */
+    async getAllProviders() {
+        try {
+            const response = await this.client.get('/api/providers');
+            return response.data.providers;
+        }
+        catch (error) {
+            if (error.response) {
+                // Server responded with error status
+                throw new Error(`Failed to fetch providers: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+            }
+            else if (error.request) {
+                // Request was made but no response
+                throw new Error(`Failed to fetch providers: No response from server`);
+            }
+            else {
+                // Something else happened
+                throw new Error(`Failed to fetch providers: ${error.message}`);
+            }
+        }
+    }
+    /**
+     * Get a specific provider by ID
+     */
+    async getProvider(id) {
+        const providers = await this.getAllProviders();
+        return providers.find(p => p.id === id) || null;
+    }
+    /**
+     * Get provider config schema
+     */
+    async getProviderSchema(id) {
+        try {
+            const response = await this.client.get(`/api/providers/${id}/schema`);
+            return response.data;
+        }
+        catch (error) {
+            if (error.response?.status === 404) {
+                throw new Error(`Provider '${id}' not found`);
+            }
+            throw new Error(`Failed to fetch provider schema: ${error.message}`);
+        }
+    }
+    /**
+     * Validate provider config
+     */
+    async validateProviderConfig(id, config) {
+        try {
+            const response = await this.client.post(`/api/providers/${id}/validate`, config);
+            return response.data;
+        }
+        catch (error) {
+            throw new Error(`Failed to validate provider config: ${error.message}`);
+        }
+    }
+    /**
+     * Get all provider IDs
+     */
+    async getAllProviderIds() {
+        const providers = await this.getAllProviders();
+        return providers.map(p => p.id);
+    }
+    /**
+     * Get providers with a specific capability
+     */
+    async getProvidersWithCapability(capability) {
+        const providers = await this.getAllProviders();
+        return providers.filter(p => p.capabilities.includes(capability));
+    }
+    /**
+     * Check if a provider has a specific capability
+     */
+    async providerHasCapability(providerId, capability) {
+        const provider = await this.getProvider(providerId);
+        return provider ? provider.capabilities.includes(capability) : false;
+    }
+    /**
+     * Check if provider requires additional config
+     */
+    async requiresAdditionalConfig(providerId) {
+        const provider = await this.getProvider(providerId);
+        return provider?.hasAdditionalConfig || false;
+    }
+}
+exports.ProviderClient = ProviderClient;