fraim-framework 1.0.7 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "FRAIM: Framework for Rigor-based AI Management - Where humans become AI managers through rigorous methodology",
   "main": "index.js",
   "bin": {

package/setup.js

@@ -94,6 +94,140 @@ function askQuestion(question, defaultValue = 'y') {
     });
 }
 
+function createProjectStructure() {
+    // Create retrospectives folder
+    ensureDirectory('retrospectives');
+    logSuccess('Created retrospectives folder');
+    
+    // Create docs/rfcs folder
+    ensureDirectory('docs/rfcs');
+    logSuccess('Created docs/rfcs folder');
+    
+    // Create BUGFIX template
+    const bugfixTemplate = `Issue: #<issue>  
+
+## Impact of the Bug
+
+## Repro Steps
+
+## Root Cause
+
+## Fix
+
+## Tests
+- Could be existing tests that are failing and need to be fixed
+- Could be new tests that need to be added into an existing test suite
+- Could be a new test suite
+`;
+    writeFile('docs/rfcs/BUGFIX-TEMPLATE.md', bugfixTemplate);
+    logSuccess('Created BUGFIX-TEMPLATE.md');
+    
+    // Create RFC template
+    const rfcTemplate = `# RFC: <Title>
+
+Issue: #<issue>  
+Owner: <agent>
+
+## Customer 
+
+## Customer Outcome
+
+## Customer Problem being solved
+
+## Solution
+
+## Alternatives
+
+## Design Details
+- User Experience changes (incl. all modalities currently supported: see codebase to know which ones)
+- API surface (OpenAPI) changes
+- Data model / schema changes
+- Failure modes & timeouts
+- Telemetry & analytics
+
+## Test Matrix
+- Unit: modules & edge cases
+- Integration: API <-> DB <-> external
+- E2E: user flows (happy/sad)
+
+## Risks & Mitigations
+
+## Observability (logs, metrics, alerts)
+
+## Phased Delivery Plan
+- Do not incude timelines
+- Do include the following for each phase:
+  - Deliverable
+  - Value delivered by deliverable
+  - What will be tested
+`;
+    writeFile('docs/rfcs/RFC-TEMPLATE.md', rfcTemplate);
+    logSuccess('Created RFC-TEMPLATE.md');
+    
+    logSuccess('Project structure created');
+}
+
+async function setupGitHubCLI() {
+    logStep('GitHub CLI Setup');
+    logInfo('To create GitHub labels automatically, you need GitHub CLI installed and authenticated.');
+    
+    // Check if gh is installed
+    try {
+        execSync('gh --version', { stdio: 'pipe' });
+        logSuccess('GitHub CLI is already installed');
+    } catch (error) {
+        logWarning('GitHub CLI is not installed');
+        logInfo('Installing GitHub CLI...');
+        logInfo('📥 Download from: https://cli.github.com/');
+        logInfo('💻 Or use package manager:');
+        logInfo('   Windows: winget install GitHub.cli');
+        logInfo('   macOS: brew install gh');
+        logInfo('   Ubuntu/Debian: sudo apt install gh');
+        logInfo('   CentOS/RHEL: sudo yum install gh');
+        
+        const waitForInstall = await askQuestion('Press Enter after installing GitHub CLI, or type "skip" to continue without it');
+        if (waitForInstall === 'skip') {
+            return false;
+        }
+        
+        // Check again
+        try {
+            execSync('gh --version', { stdio: 'pipe' });
+            logSuccess('GitHub CLI is now available');
+        } catch (error) {
+            logWarning('GitHub CLI still not available, continuing without it');
+            return false;
+        }
+    }
+    
+    // Check if authenticated
+    try {
+        execSync('gh auth status', { stdio: 'pipe' });
+        logSuccess('GitHub CLI is already authenticated');
+        return true;
+    } catch (error) {
+        logWarning('GitHub CLI is not authenticated');
+        logInfo('You need to authenticate with GitHub to create labels automatically.');
+        logInfo('🔐 Run: gh auth login');
+        logInfo('   This will open a browser for OAuth authentication');
+        
+        const waitForAuth = await askQuestion('Press Enter after authenticating, or type "skip" to continue without authentication');
+        if (waitForAuth === 'skip') {
+            return false;
+        }
+        
+        // Check authentication again
+        try {
+            execSync('gh auth status', { stdio: 'pipe' });
+            logSuccess('GitHub CLI is now authenticated');
+            return true;
+        } catch (error) {
+            logWarning('GitHub CLI authentication failed, continuing without it');
+            return false;
+        }
+    }
+}
+
 function createGitHubLabels() {
     const labels = [
         { name: 'phase:design', color: '0e8a16', description: 'Design phase - RFC creation and review' },
@@ -102,7 +236,6 @@ function createGitHubLabels() {
         { name: 'status:wip', color: 'fbca04', description: 'Work in progress' },
         { name: 'status:needs-review', color: 'd93f0b', description: 'Ready for review' },
         { name: 'status:complete', color: '0e8a16', description: 'Completed and approved' },
-        { name: 'status:approved', color: '0e8a16', description: 'Approved and ready to merge' },
         { name: 'status:changes-requested', color: 'd93f0b', description: 'Changes requested in review' },
         { name: 'ai-agent:cursor', color: '5319e7', description: 'Assigned to Cursor AI agent' },
         { name: 'ai-agent:claude', color: 'c2e0c6', description: 'Assigned to Claude AI agent' },
@@ -136,7 +269,6 @@ function createLabelsConfigFile() {
         { name: 'status:wip', color: 'fbca04', description: 'Work in progress' },
         { name: 'status:needs-review', color: 'd93f0b', description: 'Ready for review' },
         { name: 'status:complete', color: '0e8a16', description: 'Completed and approved' },
-        { name: 'status:approved', color: '0e8a16', description: 'Approved and ready to merge' },
         { name: 'status:changes-requested', color: 'd93f0b', description: 'Changes requested in review' },
         { name: 'ai-agent:cursor', color: '5319e7', description: 'Assigned to Cursor AI agent' },
         { name: 'ai-agent:claude', color: 'c2e0c6', description: 'Assigned to Claude AI agent' },
@@ -288,19 +420,6 @@ async function runWizard() {
         // Check prerequisites
         logStep('Step 1: Checking Prerequisites');
         
-        // Check if gh CLI is available
-        let ghAvailable = false;
-        try {
-            execSync('gh --version', { stdio: 'pipe' });
-            logSuccess('GitHub CLI (gh) is available');
-            ghAvailable = true;
-        } catch (error) {
-            logWarning('GitHub CLI (gh) is not installed or not available');
-            logInfo('You can still set up FRAIM, but GitHub labels will need to be created manually');
-            logInfo('Install GitHub CLI: https://cli.github.com/');
-            ghAvailable = false;
-        }
-
         // Check if we're in a git repository
         try {
             execSync('git rev-parse --git-dir', { stdio: 'pipe' });
@@ -311,8 +430,18 @@ async function runWizard() {
             return;
         }
 
-        // Step 2: AI Agent Setup
-        logStep('Step 2: AI Agent Configuration');
+        // Step 2: Project Structure
+        logStep('Step 2: Project Structure');
+        const setupStructure = await askQuestion('Would you like to create project structure (retrospectives, docs/rfcs with templates)?', 'y');
+        
+        if (setupStructure === 'y' || setupStructure === 'yes') {
+            createProjectStructure();
+        } else {
+            logInfo('Skipping project structure setup');
+        }
+
+        // Step 3: AI Agent Setup
+        logStep('Step 3: AI Agent Configuration');
         const setupAgents = await askQuestion('Would you like to set up AI agent configurations (.cursor, .windsurf, CLAUDE.md)?', 'y');
         
         if (setupAgents === 'y' || setupAgents === 'yes') {
@@ -321,8 +450,8 @@ async function runWizard() {
             logInfo('Skipping AI agent setup');
         }
 
-        // Step 3: GitHub Workflows
-        logStep('Step 3: GitHub Workflows');
+        // Step 4: GitHub Workflows
+        logStep('Step 4: GitHub Workflows');
         const setupWorkflows = await askQuestion('Would you like to set up GitHub workflows for automation?', 'y');
         
         if (setupWorkflows === 'y' || setupWorkflows === 'yes') {
@@ -332,34 +461,29 @@ async function runWizard() {
             logInfo('Skipping GitHub workflow setup');
         }
 
-        // Step 4: GitHub Labels
-        logStep('Step 4: GitHub Labels');
-        if (ghAvailable) {
-            const setupLabels = await askQuestion('Would you like to create GitHub labels for FRAIM?', 'y');
-            
-            if (setupLabels === 'y' || setupLabels === 'yes') {
+        // Step 5: GitHub Labels
+        logStep('Step 5: GitHub Labels');
+        const setupLabels = await askQuestion('Would you like to create GitHub labels for FRAIM?', 'y');
+        
+        if (setupLabels === 'y' || setupLabels === 'yes') {
+            const ghAvailable = await setupGitHubCLI();
+            if (ghAvailable) {
                 createGitHubLabels();
             } else {
-                logInfo('Skipping GitHub label setup');
+                logInfo('GitHub CLI not available - creating labels configuration file instead');
+                createLabelsConfigFile();
             }
         } else {
-            logInfo('GitHub CLI not available - creating labels configuration file instead');
-            createLabelsConfigFile();
+            logInfo('Skipping GitHub label setup');
         }
 
-        // Step 5: Summary
-        logStep('Step 5: Setup Summary');
+        // Step 6: Summary
+        logStep('Step 6: Setup Summary');
         logHeader('🎉 Setup Complete!');
         logSuccess('FRAIM has been successfully set up in your repository!');
         logInfo('Next steps:');
         logInfo('1. Commit and push these files to GitHub');
-        
-        if (ghAvailable) {
-            logInfo('2. GitHub labels have been created automatically');
-        } else {
-            logInfo('2. Import GitHub labels from .github/labels.json using the web interface');
-        }
-        
+        logInfo('2. Import GitHub labels from .github/labels.json using the web interface');
         logInfo('3. Create your first issue with phase labels');
         logInfo('4. Start coordinating your AI agents!');
         
@@ -381,14 +505,6 @@ function runSetup() {
 
     try {
         // Check prerequisites
-        try {
-            execSync('gh --version', { stdio: 'pipe' });
-        } catch (error) {
-            logError('GitHub CLI (gh) is not installed or not available');
-            logInfo('Please install GitHub CLI: https://cli.github.com/');
-            process.exit(1);
-        }
-
         try {
             execSync('git rev-parse --git-dir', { stdio: 'pipe' });
         } catch (error) {
@@ -398,16 +514,17 @@ function runSetup() {
         }
 
         // Create everything at once
+        createProjectStructure();
         ensureDirectory('.github/workflows');
         createAgentFolders();
         createGitHubWorkflows();
-        createGitHubLabels();
+        createLabelsConfigFile();
 
         logHeader('🎉 Setup Complete!');
         logSuccess('FRAIM has been successfully set up in your repository!');
         logInfo('Next steps:');
         logInfo('1. Commit and push these files to GitHub');
-        logInfo('2. The GitHub labels have been created automatically');
+        logInfo('2. Import GitHub labels from .github/labels.json using the web interface');
         logInfo('3. Create your first issue with phase labels');
         logInfo('4. Start coordinating your AI agents!');
         
@@ -428,4 +545,4 @@ if (require.main === module) {
     runSetup();
 }
 
-module.exports = { runSetup, runWizard };
+module.exports = { runSetup, runWizard, createProjectStructure };

package/docs/guides/getting-started.md

@@ -1,175 +0,0 @@
-# 🚀 Getting Started with FRAIM
-
-**Framework for Rigor-based AI Management**
-
-Welcome to FRAIM! This guide will transform you from a developer into an AI manager in under 30 seconds.
-
-## 🚀 Quick Start (30 seconds)
-
-### 1. Navigate to Your Repository
-```bash
-cd your-project
-```
-
-### 2. Setup FRAIM
-```bash
-npx @fraim/framework init
-```
-
-### 3. Create Your First AI-Managed Issue
-```bash
-gh issue create --title "Add user authentication" --label "phase:design,ai-agent:claude"
-```
-
-### 4. Watch the Magic Happen! 🎉
-
-GitHub automatically:
-- 🔄 Creates branch: `feature/1-add-user-authentication`
-- 🔄 Creates draft PR
-- 🔄 Sets status: `status:wip`
-- 🤖 Claude starts working on RFC
-
-## 🤖 AI Agent Coordination
-
-FRAIM coordinates three types of AI agents, each with specific roles:
-
-### Cursor (IDE Development)
-- **Role**: Implementation and testing
-- **Strengths**: Code generation, testing, IDE integration
-- **Best For**: `phase:impl` tasks
-
-### Claude (Conversational AI)
-- **Role**: Design and RFC creation
-- **Strengths**: Natural language, documentation, architecture
-- **Best For**: `phase:design` tasks
-
-### Windsurf (Code Understanding)
-- **Role**: Performance and integration
-- **Strengths**: Code analysis, optimization, system integration
-- **Best For**: `phase:tests` and optimization tasks
-
-## 📋 Workflow Phases
-
-### Phase 1: Design (`phase:design`)
-1. **Create Issue**: Describe the feature or bug
-2. **Add Labels**: `phase:design` + `ai-agent:claude`
-3. **AI Action**: Claude creates RFC and architecture docs
-4. **Review**: Stakeholders review and approve design
-5. **Transition**: Change to `phase:impl` + `ai-agent:cursor`
-
-### Phase 2: Implementation (`phase:impl`)
-1. **AI Action**: Cursor implements the feature
-2. **Testing**: Comprehensive test coverage
-3. **Documentation**: Code comments and updates
-4. **Review**: Code review and validation
-5. **Transition**: Change to `phase:tests` + `ai-agent:windsurf`
-
-### Phase 3: Testing (`phase:tests`)
-1. **AI Action**: Windsurf validates implementation
-2. **Performance**: Performance testing and optimization
-3. **Integration**: System integration testing
-4. **Validation**: Final validation against requirements
-5. **Completion**: Mark as `status:complete`
-
-## 🏷️ Label System
-
-### Phase Labels
-- `phase:design` - Design and RFC creation
-- `phase:impl` - Implementation and development
-- `phase:tests` - Testing and validation
-
-### Status Labels
-- `status:wip` - Work in progress
-- `status:needs-review` - Ready for review
-- `status:complete` - Work completed
-
-### Agent Labels
-- `ai-agent:cursor` - Assigned to Cursor
-- `ai-agent:claude` - Assigned to Claude
-- `ai-agent:windsurf` - Assigned to Windsurf
-
-### Priority Labels (Optional)
-- `priority:critical` - Critical priority
-- `priority:high` - High priority
-- `priority:medium` - Medium priority
-- `priority:low` - Low priority
-
-## 🔧 Advanced Setup
-
-### Interactive Wizard
-```bash
-npx @fraim/framework wizard
-```
-
-The wizard will ask you:
-- Which AI agents to enable
-- Whether to enable deployment workflows
-- Whether to run in dry-run mode first
-
-### Custom Configuration
-```bash
-npx @fraim/framework setup owner/repository --config custom-config.json
-```
-
-### Partial Setup
-```bash
-# Only create labels
-npx @fraim/framework setup owner/repository --labels-only
-
-# Only setup workflows
-npx @fraim/framework setup owner/repository --workflows-only
-```
-
-## 📚 Next Steps
-
-### 1. Explore Documentation
-- [🧠 RIGOR Methodology](../../README.md#-the-rigor-methodology)
-- [🤖 AI Agent Rules](../../agents/)
-- [🏗️ Framework Overview](../../README.md#-framework-structure)
-
-### 2. Try Different Workflows
-- Create issues with different phase/agent combinations
-- Experiment with the label system
-- Practice phase transitions
-
-### 3. Customize for Your Team
-- Adjust agent assignments based on team strengths
-- Customize workflows for your development process
-- Add team-specific labels and processes
-
-### 4. Scale Up
-- Apply FRAIM to multiple repositories
-- Train your team on the methodology
-- Integrate with existing CI/CD pipelines
-
-## 🎯 Success Metrics
-
-### Individual Level
-- **Setup Time**: < 30 seconds to get started
-- **Issue Resolution**: Faster development cycles
-- **Code Quality**: Higher quality through AI coordination
-- **Learning**: Better understanding of AI capabilities
-
-### Team Level
-- **Coordination**: Seamless AI agent collaboration
-- **Consistency**: Standardized development processes
-- **Visibility**: Clear progress tracking and status
-- **Efficiency**: Reduced manual coordination overhead
-
-### Organization Level
-- **Scalability**: Framework grows with your organization
-- **Compliance**: Audit trails and process documentation
-- **Innovation**: Faster adoption of new AI capabilities
-- **Competitive Advantage**: Professional AI management capabilities
-
-## 🚀 Ready to Become an AI Manager?
-
-```bash
-npx @fraim/framework init
-```
-
-**FRAIM: Where humans become AI managers through rigorous methodology**
-
----
-
-*Need help? Check the [main README](../../README.md) or [contact the team](https://github.com/mathursrus/Ashley-Calendar-AI/issues).*