fraim-hub 2.0.280 → 2.0.283

package/README.md

@@ -1,467 +1,467 @@
-# 🚀 FRAIM — AI Workforce Infrastructure
-**"Brilliant AI isn't how industries get built. Organizations are."** — FRAIM transforms every layer of the AI-powered company at once: **AI agents** become an accountable, improving workforce; **their operators** become capable AI managers who hold the line on quality, delegation, and evidence; and **executives** gain clear optics on AI proficiency across the entire organization.
-
-
-🚀 **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 jobs, skills, and rules 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 jobs
-• 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 transforms every layer of your AI-powered company: agents become an accountable workforce, operators become capable AI managers, and executives gain clear optics on AI proficiency across the whole org.
-
-
-
-### The Human-Developer Parallel
-
-| **Human Development** | **AI Agent Development** | **FRAIM Solution** |
-|----------------------|-------------------------|-------------------|
-| **Code Reviews** | Random quality checks | Structured review jobs 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 jobs, skills, 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 discipline 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 jobs 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@latest setup --key=<your-fraim-key>
-
-# Optional: Create alias for convenience
-echo 'alias fraim="npx fraim"' >> ~/.bashrc
-source ~/.bashrc
-```
-
-**Alternative: Global install**
-```bash
-npm install -g fraim
-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**: FRAIM job guidance 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 jobs, skills, rules, and templates
-```
-
-**💡 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.
-
-### **Which Job Should I Run?**
-
-FRAIM's primary execution unit is a **job**. Jobs define the phased path. Skills and rules support the job; they are not the thing you "run" first.
-
-Use these defaults:
-- `feature-specification` when the request is still fuzzy or needs clarified requirements, UX, or acceptance criteria.
-- `technical-design` after the spec is approved and you need the implementation plan, file touchpoints, and risk handling.
-- `feature-implementation` for code changes, bug fixes, and documentation updates that should be executed and validated.
-- `test-execution` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
-- `browser-application-validation` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
-- `implementation-feature-review` when you need to verify the delivered behavior matches the feature spec.
-- `implementation-design-review` when you need to verify the code matches the approved technical design.
-- `issue-retrospective` after the work is complete and you want durable learnings captured.
-
-Typical path for a larger feature:
-- `feature-specification` -> `technical-design` -> `feature-implementation` -> review job -> `issue-retrospective`
-
-Typical path for a small bug fix:
-- `feature-implementation` -> review job if needed -> `issue-retrospective`
-
-Once FRAIM is connected in your IDE, ask your agent to `list FRAIM jobs` or name the specific job directly, for example: `Run the feature-implementation job for issue #123`.
-
-### **🧩 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, job, skill, and pattern has been tested in real projects. This isn't theoretical—it is 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 transforms every layer of your AI-powered company: agents become an accountable workforce, operators become capable AI managers, and executives gain clear optics on AI proficiency across the whole org.**
-
-Stop fighting with AI agents. Start building your AI organization.
-
-**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.svg)](https://www.npmjs.com/package/fraim)
-[![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>
+# 🚀 FRAIM — AI Workforce Infrastructure
+**"Brilliant AI isn't how industries get built. Organizations are."** — FRAIM transforms every layer of the AI-powered company at once: **AI agents** become an accountable, improving workforce; **their operators** become capable AI managers who hold the line on quality, delegation, and evidence; and **executives** gain clear optics on AI proficiency across the entire organization.
+
+
+🚀 **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 jobs, skills, and rules 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 jobs
+• 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 transforms every layer of your AI-powered company: agents become an accountable workforce, operators become capable AI managers, and executives gain clear optics on AI proficiency across the whole org.
+
+
+
+### The Human-Developer Parallel
+
+| **Human Development** | **AI Agent Development** | **FRAIM Solution** |
+|----------------------|-------------------------|-------------------|
+| **Code Reviews** | Random quality checks | Structured review jobs 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 jobs, skills, 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 discipline 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 jobs 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@latest setup --key=<your-fraim-key>
+
+# Optional: Create alias for convenience
+echo 'alias fraim="npx fraim"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Alternative: Global install**
+```bash
+npm install -g fraim
+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**: FRAIM job guidance 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 jobs, skills, rules, and templates
+```
+
+**💡 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.
+
+### **Which Job Should I Run?**
+
+FRAIM's primary execution unit is a **job**. Jobs define the phased path. Skills and rules support the job; they are not the thing you "run" first.
+
+Use these defaults:
+- `feature-specification` when the request is still fuzzy or needs clarified requirements, UX, or acceptance criteria.
+- `technical-design` after the spec is approved and you need the implementation plan, file touchpoints, and risk handling.
+- `feature-implementation` for code changes, bug fixes, and documentation updates that should be executed and validated.
+- `test-execution` when you need reproduction coverage, missing tests, or stronger regression protection before implementation.
+- `browser-application-validation` or `ui-polish-validation` after user-facing UI changes or when the ask is explicitly browser validation.
+- `implementation-feature-review` when you need to verify the delivered behavior matches the feature spec.
+- `implementation-design-review` when you need to verify the code matches the approved technical design.
+- `issue-retrospective` after the work is complete and you want durable learnings captured.
+
+Typical path for a larger feature:
+- `feature-specification` -> `technical-design` -> `feature-implementation` -> review job -> `issue-retrospective`
+
+Typical path for a small bug fix:
+- `feature-implementation` -> review job if needed -> `issue-retrospective`
+
+Once FRAIM is connected in your IDE, ask your agent to `list FRAIM jobs` or name the specific job directly, for example: `Run the feature-implementation job for issue #123`.
+
+### **🧩 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, job, skill, and pattern has been tested in real projects. This isn't theoretical—it is 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 transforms every layer of your AI-powered company: agents become an accountable workforce, operators become capable AI managers, and executives gain clear optics on AI proficiency across the whole org.**
+
+Stop fighting with AI agents. Start building your AI organization.
+
+**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.svg)](https://www.npmjs.com/package/fraim)
+[![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>