fraim-framework 1.0.12 → 2.0.2

package/README.md

@@ -1,159 +1,385 @@
 # 🚀 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.
 
-**Where humans become AI managers through rigorous methodology**
 
-FRAIM is a framework that empowers human developers to coordinate AI agents using **proven, tested practices** that have been refined through real project experience. This isn't theory - these are the actual rules that have been battle-tested in production environments.
+🚀 **The Problem with AI Coding Today**
 
-## 🎯 What is FRAIM?
+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.
 
-FRAIM transforms you from a solo developer into an **AI manager** who orchestrates multiple AI agents (Cursor, Claude, Windsurf) with enterprise-grade discipline. It's not just about using AI—it's about managing AI teams with the same rigor you'd apply to human teams.
+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
 
-**Key Difference**: FRAIM contains **tested rules from real projects**, not theoretical best practices. Every rule, workflow, and coordination pattern has been proven to work in actual development environments.
+🎯 **Introducing FRAIM: Framework for Rigor-based AI Management**
 
-## 🧠 The RIGOR Methodology
+FRAIM transforms you from a solo developer into an AI manager orchestrating multiple agents with enterprise-grade discipline.
 
-**R**eviews: Structured feedback and approval processes  
-**I**solation: Agents don't interfere with each others' work *unless* you explicitly ask them to  
-**G**itOps: Git as the single source of truth and the glue between you and your agents  
-**O**bservability: Complete visibility into AI activities  
-**R**etrospectives: Continuous learning from mistakes and positive experiences  
+**The Transformation:**
+❌ Before: "It's working now. The login button exists."
+✅ After: "Implementation complete. 12/12 tests pass, API endpoint validated, UI screenshots provided."
 
-## 🚀 Quick Start
+**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
 
-### Option 1: NPX (Recommended)
+**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** (`.ai-agents/rules/integrity-and-test-ethics.md`)
+**Problem**: Agents claim "tests pass" when they actually fail
+**Solution**: Mandatory evidence collection, test immutability rules, and accountability frameworks
 ```bash
-npx fraim-framework init
+# Before FRAIM: "Tests look good!"
+# After FRAIM: "Here's the test output proving all 47 tests pass"
 ```
 
-### Option 2: One-Line Installer
+#### 🧪 **Comprehensive Testing Guidelines** (`.ai-agents/rules/agent-testing-guidelines.md`)
+**Problem**: Superficial testing that misses real issues
+**Solution**: Multi-layer validation (database, API, UI, integration) with mandatory evidence
 ```bash
-curl -sSL https://fraim.dev/install.sh | bash -s -- --repo owner/repository
+# Before: Mock everything, hope it works
+# After: Test real systems, prove it works, show evidence
 ```
 
-### Option 3: Python Package
+#### 🗣️ **Clear Communication Standards** (`.ai-agents/rules/communication.md`)
+**Problem**: Vague progress reports and unclear accountability
+**Solution**: Structured progress updates with concrete evidence and absolute accountability
 ```bash
-pip install fraim-framework
-fraim init
+# Before: "Working on it, almost done"
+# After: "Fixed API timeout, tests passing, evidence attached, ready for review"
+```
+
+#### 🏗️ **Architectural Discipline** (`.ai-agents/rules/architecture.md`)
+**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
 ```
 
-### Option 4: GitHub Action
-Add the FRAIM setup workflow to your repository and run it manually.
+#### 🎯 **Spike-First Development** (`.ai-agents/rules/spike-first-development.md`)
+**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
+```
 
-## 📁 Framework Structure
+#### 🔄 **Continuous Learning System** (`.ai-agents/rules/continuous-learning.md`)
+**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** (`.ai-agents/rules/simplicity.md`)
+**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** (`.ai-agents/rules/git-safe-commands.md`)
+**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** (`.ai-agents/rules/merge-requirements.md`)
+**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** (`.ai-agents/rules/successful-debugging-patterns.md`)
+**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** (`.ai-agents/scripts/` and `sample_package.json`)
+**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**
 
 ```
 FRAIM/
-├── README.md                    # This file - framework overview
-├── package.json                 # Node.js package configuration
-├── setup.py                     # Python package configuration
-├── index.js                     # Main entry point
-├── setup.js                     # Cross-platform setup script
-├── install.sh                   # One-line bash installer
-├── test-config.json             # Example configuration
-│
-├── bin/                         # Command-line interface
-│   └── fraim.js                 # FRAIM CLI with full functionality
-│
-├── agents/                      # AI agent configurations
-│   ├── cursor/                  # Cursor IDE rules (TESTED)
-│   │   ├── .cursorrules         # Main configuration
-│   │   └── rules/               # Modular rule files
-│   ├── claude/                  # Claude agent configuration (TESTED)
-│   │   ├── CLAUDE.md            # Main configuration
-│   │   └── rules/               # Modular rule files
-│   └── windsurf/                # Windsurf agent configuration (TESTED)
-│       ├── .windsurfrules       # Main configuration
-│       └── rules/               # Modular rule files
+├── 🧠 .ai-agents/rules/          # Guardrails - The "HR Handbook" for AI agents
+│   ├── integrity-and-test-ethics.md    # Prevents "fake it till you make it"
+│   ├── agent-testing-guidelines.md     # Ensures real validation, not claims
+│   ├── communication.md                # Clear accountability and progress
+│   ├── architecture.md                 # Prevents technical debt
+│   ├── spike-first-development.md      # Validates before building
+│   ├── continuous-learning.md          # Learns from mistakes
+│   ├── simplicity.md                   # Prevents over-engineering
+│   ├── git-safe-commands.md            # Prevents agent hangs on Git commands
+│   ├── merge-requirements.md           # Safe branch management and rebasing
+│   ├── successful-debugging-patterns.md # Systematic debugging approach
+│   ├── local-development.md            # Local development best practices
+│   ├── pr-workflow-completeness.md     # PR workflow validation
+│   └── software-development-lifecycle.md # Full SDLC integration
 │
-├── workflows/                    # GitHub Actions workflows
-│   └── setup-fraim.yml          # Automated FRAIM setup
+├── 🔄 .ai-agents/workflows/      # Process - The "Project Management Office"
+│   ├── spec.md                   # Specification and requirements phase
+│   ├── design.md                 # Structured design phase
+│   ├── implement.md              # Implementation with validation
+│   ├── test.md                   # Comprehensive testing
+│   ├── resolve.md                # Issue resolution workflow
+│   └── retrospect.md             # Learning and improvement
 │
-├── scripts/                      # Python package scripts
-│   ├── __init__.py              # Package initialization
-│   ├── cli.py                   # Python CLI implementation
-│   └── setup.py                 # Python setup module
+├── 📋 .ai-agents/templates/      # Human Interfaces - The "Standard Operating Procedures"
+│   ├── evidence/                 # Proof of work templates
+│   ├── retrospective/            # Learning capture templates
+│   └── specs/                    # Specification templates
 │
-├── docs/                         # Documentation and guides
-│   ├── rfcs/                    # RFC documents
-│   └── guides/                  # Getting started guides
-│
-└── examples/                     # Example implementations
-    └── simple-webapp/            # Sample project with FRAIM config
-        ├── README.md             # Project documentation
-        └── fraim-config.json    # Sample configuration
+└── 🛠️ Scripts & Automation      # Determinism - The "DevOps Pipeline"
+    ├── prep-issue.sh             # Issue preparation
+    ├── exec-with-timeout.ts      # Command execution with timeout & output visibility
+    └── cleanup-branch.ts         # Branch management
 ```
 
-## 🤖 Supported AI Agents
+## 🚀 **Get Started in 60 Seconds**
 
-- **Cursor**: IDE-integrated development and testing (with tested rules)
-- **Claude**: Conversational AI and design assistance (with tested rules)
-- **Windsurf**: Advanced code understanding and optimization (with tested rules)
+### **Install & Initialize**
+```bash
+npm install -g fraim-framework
+fraim init
+```
 
-## 🔧 Core Features
+### **🔧 Customize for Your Project**
 
-- **Proven Rules**: Every rule has been tested in real projects
-- **Automated Setup**: Single command to bootstrap FRAIM in any repository
-- **GitHub Integration**: Native GitHub workflows, labels, and automation
-- **Agent Coordination**: Seamless coordination between multiple AI agents
-- **Phase Management**: Structured design → implementation → testing workflows
-- **Enterprise Ready**: Observability, rollbacks, and audit trails built-in
+After installation, customize these files for your specific project:
 
-## 📚 Documentation
+#### **1. Architecture Rules** (`.ai-agents/rules/architecture.md`)
+- **Purpose**: Define your system's architectural patterns and boundaries
+- **Customize**: Replace generic examples with your specific architecture patterns
+- **Example**: Add your database patterns, API structures, service boundaries
 
-- **Getting Started**: `/docs/guides/getting-started.md`
-- **RFC Template**: `/docs/rfcs/`
-- **Distribution Guide**: `DISTRIBUTION.md`
-- **Agent Rules**: `/agents/` directory (all tested and proven)
+#### **2. Branch Cleanup Script** (`.ai-agents/scripts/cleanup-branch.ts`)
+- **Purpose**: Project-specific cleanup when branches are deleted
+- **Customize**: Add your cleanup logic in the `insertYourCodeHere()` method
+- **Example**: Database cleanup, cache invalidation, temporary file removal
 
-## 🚀 Usage Examples
+#### **3. Package Scripts** (`sample_package.json` → `package.json`)
+- **Purpose**: Testing and build scripts for your project
+- **Adopt**: Copy relevant scripts from `sample_package.json` into your main `package.json`
+- **Customize**: Update test commands, build processes, and framework-specific commands
+- **Example**: Replace `baml-cli generate` with your framework's generate command
 
-### Basic Setup
-```bash
-# Initialize FRAIM in current repository
-npx fraim-framework init
+#### **4. Test Utilities** (`test-utils.ts` → your project)
+- **Purpose**: Generic test framework with tagging system
+- **Adopt**: Copy `test-utils.ts` into your project and import in your test files
+- **Customize**: Extend `BaseTestCase` interface for your specific test needs
+- **Example**: Create domain-specific test cases using the tagging system
+
+#### **5. Test Structure** (`examples/simple-webapp/example-test.ts`)
+- **Purpose**: Example test cases with proper tagging
+- **Adopt**: Use as a template for your project's test structure
+- **Customize**: Replace with your project's test cases and domain-specific tags
+- **Example**: Add your specific test scenarios and validation patterns
 
-# Learn about RIGOR methodology
-npx fraim-framework rigor
+## 🎯 **The Transformation: From Developer to AI Manager**
 
-# Interactive setup wizard
-npx fraim-framework wizard
+### **Phase 1: Setup (5 minutes)**
+```bash
+npx fraim-framework init
+# ✅ Repository configured with AI management rules
+# ✅ Agents assigned to specific roles (Design, Implementation, Testing)
+# ✅ Workflows and templates installed
 ```
 
-### Agent Coordination
+### **Phase 2: Issue Management (30 seconds per issue)**
 ```bash
-# Create issue with phase labels
-gh issue create --title "Add user auth" --label "phase:design,ai-agent:claude"
+gh issue create --title "Add user authentication" --label "ai-agent:cursor"
+# ✅ Git issue is centralized coordination point
+# ✅ Agent assignment handled
+# ✅ Ready for work 
+```
 
-# AI agents automatically coordinate through GitHub state
-# Claude creates RFC → Cursor implements → Windsurf optimizes
+### **Phase 3: Orchestrated Development**
+```bash
+scripts/development/prep-issue.sh #issue_number
+# ✅ Local clone and new branch created
+# ✅ Coding agent initiated
+# ✅ Tell coding agent which phase it should proceed with 
 ```
 
-## 🎯 Success Metrics
+## 🌟 **Why FRAIM is the Future**
 
-- **Setup Time**: < 5 minutes from zero to production-ready
-- **Agent Coordination**: Zero conflicts between multiple AI agents
-- **Workflow Efficiency**: 50% reduction in development cycle time
-- **Quality**: Built-in reviews and validation at every phase
-- **Reliability**: Tested rules prevent common coordination failures
+### **1. Proven in Production**
+Every rule, workflow, and pattern has been tested in real projects. This isn't theoretical—it's battle-tested.
 
-## 🔗 Quick Links
+### **2. Enterprise Discipline**
+The same rigor you'd apply to managing human developers, applied to AI agents.
 
-- **Repository**: [GitHub](https://github.com/mathursrus/Ashley-Calendar-AI/tree/master/FRAIM)
-- **Issues**: [GitHub Issues](https://github.com/mathursrus/Ashley-Calendar-AI/issues)
-- **Documentation**: [Framework Docs](https://github.com/mathursrus/Ashley-Calendar-AI/tree/master/FRAIM/docs)
-- **Distribution**: [DISTRIBUTION.md](DISTRIBUTION.md)
+### **3. Continuous Improvement**
+Built-in learning systems that make your AI agents better over time.
 
-## 🚀 Ready to Become an AI Manager?
+### **4. Complete Transparency**
+Full visibility into what each agent is doing, with evidence-based validation.
 
-FRAIM transforms the way you work with AI agents. Instead of managing code, you'll be managing AI teams with enterprise-grade discipline.
+### **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**
 
-**Start your journey today:**
 ```bash
-npx fraim-framework init
+# 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
+
 ---
 
-*FRAIM: Where humans become AI managers through rigorous methodology*
+## 🎯 **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)
 
-**Note**: All rules and workflows in FRAIM have been tested and proven in real project environments. This isn't theory - it's battle-tested practice.
+</div>

package/bin/fraim.js

@@ -28,7 +28,7 @@ function showHelp() {
     console.log('  O - Observability: Complete visibility into AI activities');
     console.log('  R - Retrospectives: Continuous learning from experience\n');
 
-    console.log('📚 Documentation: https://github.com/mathursrus/Ashley-Calendar-AI/tree/master/FRAIM');
+    console.log('📚 Documentation: https://github.com/mathursrus/FRAIM');
     console.log('🎯 Ready to become an AI manager? Run: npx fraim-framework init');
 }
 
@@ -70,6 +70,42 @@ function showRigor() {
     console.log('✨ Every rule has been tested and proven in real project environments.');
 }
 
+function showStructure() {
+    console.log(banner);
+    console.log('📁 FRAIM Framework Structure\n');
+
+    console.log('📂 /rules/ - Centralized rules for all AI agents');
+    console.log('  • integrity-and-test-ethics.md - Core ethical principles');
+    console.log('  • simplicity.md - Keep solutions simple and focused');
+    console.log('  • architecture.md - Technical architecture principles');
+    console.log('  • continuous-learning.md - Learn from retrospectives and RFCs');
+    console.log('  • successful-debugging-patterns.md - Debug issues systematically\n');
+
+    console.log('📂 /workflows/ - Development phase workflows');
+    console.log('  • design.md - Design phase workflow');
+    console.log('  • implement.md - Implementation phase workflow');
+    console.log('  • test.md - Testing phase workflow');
+    console.log('  • resolve.md - Issue resolution workflow');
+    console.log('  • retrospect.md - Retrospective workflow\n');
+
+    console.log('📂 /templates/ - Standardized templates');
+    console.log('  • /evidence/ - Test evidence templates');
+    console.log('  • /retrospective/ - Retrospective templates');
+    console.log('  • /specs/ - Specification templates');
+    console.log('  • /help/ - Help documentation templates\n');
+
+    console.log('📂 /.github/ - GitHub configuration');
+    console.log('  • /workflows/ - GitHub Actions workflows');
+    console.log('  • pull_request_template.md - PR template\n');
+
+    console.log('📂 /scripts/ - Automation scripts');
+    console.log('  • ensure-tests-present.sh - Test validation script');
+    console.log('  • exec-with-timeout.sh - Command execution with timeout');
+    console.log('  • prep-issue.sh - Issue preparation for AI agents\n');
+
+    console.log('🎯 This structure provides a comprehensive framework for AI agent management!');
+}
+
 async function runSetup() {
     try {
         // Import and run the setup script
@@ -109,6 +145,11 @@ async function main() {
         return;
     }
 
+    if (args.includes('structure')) {
+        showStructure();
+        return;
+    }
+
     if (args.includes('init') || args.includes('setup')) {
         console.log(banner);
         console.log('🚀 Setting up FRAIM in current repository...\n');
@@ -129,5 +170,10 @@ async function main() {
     showHelp();
 }
 
-// Run the CLI
-main();
+// Export the main function for use in other files
+module.exports = { main };
+
+// Run the CLI if this file is executed directly
+if (require.main === module) {
+    main();
+}

package/index.js

@@ -35,6 +35,33 @@ module.exports.FRAIM_INFO = {
         'Retrospectives: Continuous learning from mistakes and positive experiences'
     ],
     supportedAgents: ['cursor', 'claude', 'windsurf'],
-    repository: 'https://github.com/mathursrus/Ashley-Calendar-AI/tree/master/FRAIM',
-    note: 'All rules and workflows have been tested and proven in real project environments'
-};
+    repository: 'https://github.com/mathursrus/FRAIM',
+    note: 'All rules and workflows have been tested and proven in real project environments',
+    
+    // New structure information
+    structure: {
+        rules: '/rules/',
+        workflows: '/workflows/',
+        templates: '/templates/',
+        scripts: '/scripts/',
+        github: '/.github/'
+    },
+    
+    // Centralized rules
+    centralizedRules: [
+        'integrity-and-test-ethics.md',
+        'simplicity.md',
+        'architecture.md',
+        'continuous-learning.md',
+        'successful-debugging-patterns.md'
+    ],
+    
+    // Workflow templates
+    workflowTemplates: [
+        'design.md',
+        'implement.md',
+        'test.md',
+        'resolve.md',
+        'retrospect.md'
+    ]
+};