🚀 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

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

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

fraim setup --key=<your-fraim-key>
# Select "Conversational Mode" when prompted

Integrated Mode: Single platform for both code hosting and issue tracking

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

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:

# 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:

.fraim/
  personalized-employee/
    jobs/
    skills/
    rules/
    templates/

Use fraim override to create a local starting point:

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):

{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian"],
    "env": {
      "JIRA_URL": "https://mycompany.atlassian.net",
      "JIRA_USERNAME": "[email protected]",
      "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:

# 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

# 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 - Star us to follow development
• 🐛 Issue Tracker - 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.

🚀 Ready to become an AI manager? Start with FRAIM today.