fraim-framework 2.0.3 → 2.0.5

package/.ai-agents/workflows/test.md

@@ -1,90 +1,90 @@
-# Testing Phase
-
-## INTENT
-To create comprehensive test coverage that accurately reproduces issues and validates solutions, ensuring robust testing through proper test structure, failure verification, and systematic test execution.
-
-## PRINCIPLES
-- **Test-Driven**: Write tests that reproduce the issue before fixing
-- **Comprehensive Coverage**: Ensure all scenarios are tested
-- **Failure Verification**: Confirm tests fail before implementation
-- **Proper Structure**: Use established test patterns and frameworks
-- **Systematic Execution**: Follow consistent testing procedures
-
-## TESTING WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {slug}); confirm target branch feature/{issue_number}-{slug}.
-
-### Step 2: Phase Initiation
-Label the issue 'phase:tests'. (GitHub Action will automatically label the issue `status:wip` and update the existing draft PR)
-
-### Step 3: Environment Setup
-**IMPORTANT**: The user has already run `prep-issue.sh` which has:
-- ✅ Created the feature branch
-- ✅ Checked out the branch
-- ✅ Created draft PR
-- ✅ Indexed the codebase with Serena
-- ✅ Opened the editor in the prepared workspace
-
-You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
-
-### Step 4: Work Location
-You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working. 
-
-### Step 5: Testing Work
-Your work entails the following:
-
-- Review the RFC associated with this issue.
-- Determine whether tests need to be added to an existing test suite, or a new one needs to be created.
-- **CRITICAL: Write INTEGRATION tests that demonstrate the REAL USER SCENARIO**
-  - Test the actual end-to-end user experience, not unit tests for hypothetical fixes
-  - Use real services and APIs where possible (not mocks)
-  - Verify the issue occurs in the real system as described in the issue
-  - Example: For messaging threading issues, actually send messages and verify they appear as new messages vs replies
-- Run the test cases to ensure they fail (demonstrating the issue exists)
-- Flip issue to 'status:needs-review' and remove 'status:wip'
-
-**❌ DO NOT:**
-- Write unit tests for code that doesn't exist yet
-- Test hypothetical fixes or solutions
-- Create mock tests that don't use real services
-- Test individual components in isolation
-
-**✅ DO:**
-- Test the complete user workflow end-to-end
-- Use real APIs and services when possible
-- Verify the actual problem described in the issue
-- Create tests that will pass AFTER the fix is implemented
-
-### Step 6: Iteration
-If workflow actions or reviewer feedback indicates more work is needed, ensure the issue is set back to `status:wip` and continue working as above.
-
-## EXAMPLES
-
-### Good: Comprehensive Testing Process
-```
-Issue #84: "Fix API integration timeout"
-1. ✅ Identified: Issue #84, branch feature/84-fix-api
-2. ✅ Phase: Set phase:tests, PR created
-3. ✅ Environment: User ran prep-issue.sh, ready to work
-4. ✅ Location: Working in prepared workspace with Serena indexing
-5. ✅ RFC Review: Read docs/rfcs/84-fix-api-timeout.md
-6. ✅ Analysis: Determined need to add timeout tests
-7. ✅ Test Creation: Added test cases for timeout scenarios
-8. ✅ Failure Verification: Confirmed tests fail before fix
-9. ✅ Review: Set status:needs-review
-10. ✅ Iteration: Incorporated feedback, updated tests
-Result: Comprehensive test coverage with proper structure
-```
-
-### Bad: Incomplete Testing Process
-```
-Issue #84: "Fix API integration timeout"
-1. ✅ Identified: Issue #84
-2. ❌ Skip: Didn't review RFC
-3. ❌ Skip: Started testing without understanding requirements
-4. ❌ Skip: No test cases written
-5. ❌ Skip: Didn't verify tests fail
-6. ❌ Skip: No test structure followed
-Result: Incomplete, ineffective testing
+# Testing Phase
+
+## INTENT
+To create comprehensive test coverage that accurately reproduces issues and validates solutions, ensuring robust testing through proper test structure, failure verification, and systematic test execution.
+
+## PRINCIPLES
+- **Test-Driven**: Write tests that reproduce the issue before fixing
+- **Comprehensive Coverage**: Ensure all scenarios are tested
+- **Failure Verification**: Confirm tests fail before implementation
+- **Proper Structure**: Use established test patterns and frameworks
+- **Systematic Execution**: Follow consistent testing procedures
+
+## TESTING WORKFLOW
+
+### Step 1: Issue Identification
+Ask for {issue_number} (and optional {slug}); confirm target branch feature/{issue_number}-{slug}.
+
+### Step 2: Phase Initiation
+Label the issue 'phase:tests'. (GitHub Action will automatically label the issue `status:wip` and update the existing draft PR)
+
+### Step 3: Environment Setup
+**IMPORTANT**: The user has already run `prep-issue.sh` which has:
+- ✅ Created the feature branch
+- ✅ Checked out the branch
+- ✅ Created draft PR
+- ✅ Indexed the codebase with Serena
+- ✅ Opened the editor in the prepared workspace
+
+You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
+
+### Step 4: Work Location
+You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working. 
+
+### Step 5: Testing Work
+Your work entails the following:
+
+- Review the RFC associated with this issue.
+- Determine whether tests need to be added to an existing test suite, or a new one needs to be created.
+- **CRITICAL: Write INTEGRATION tests that demonstrate the REAL USER SCENARIO**
+  - Test the actual end-to-end user experience, not unit tests for hypothetical fixes
+  - Use real services and APIs where possible (not mocks)
+  - Verify the issue occurs in the real system as described in the issue
+  - Example: For messaging threading issues, actually send messages and verify they appear as new messages vs replies
+- Run the test cases to ensure they fail (demonstrating the issue exists)
+- Flip issue to 'status:needs-review' and remove 'status:wip'
+
+**❌ DO NOT:**
+- Write unit tests for code that doesn't exist yet
+- Test hypothetical fixes or solutions
+- Create mock tests that don't use real services
+- Test individual components in isolation
+
+**✅ DO:**
+- Test the complete user workflow end-to-end
+- Use real APIs and services when possible
+- Verify the actual problem described in the issue
+- Create tests that will pass AFTER the fix is implemented
+
+### Step 6: Iteration
+If workflow actions or reviewer feedback indicates more work is needed, ensure the issue is set back to `status:wip` and continue working as above.
+
+## EXAMPLES
+
+### Good: Comprehensive Testing Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84, branch feature/84-fix-api
+2. ✅ Phase: Set phase:tests, PR created
+3. ✅ Environment: User ran prep-issue.sh, ready to work
+4. ✅ Location: Working in prepared workspace with Serena indexing
+5. ✅ RFC Review: Read docs/rfcs/84-fix-api-timeout.md
+6. ✅ Analysis: Determined need to add timeout tests
+7. ✅ Test Creation: Added test cases for timeout scenarios
+8. ✅ Failure Verification: Confirmed tests fail before fix
+9. ✅ Review: Set status:needs-review
+10. ✅ Iteration: Incorporated feedback, updated tests
+Result: Comprehensive test coverage with proper structure
+```
+
+### Bad: Incomplete Testing Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84
+2. ❌ Skip: Didn't review RFC
+3. ❌ Skip: Started testing without understanding requirements
+4. ❌ Skip: No test cases written
+5. ❌ Skip: Didn't verify tests fail
+6. ❌ Skip: No test structure followed
+Result: Incomplete, ineffective testing
 ```

package/examples/simple-webapp/TESTING.md

@@ -0,0 +1,62 @@
+# Testing with FRAIM Framework
+
+This directory contains example test cases that demonstrate how to use the FRAIM testing framework with proper tagging and structure.
+
+## Test Structure
+
+The example test file (`example-test.ts`) demonstrates:
+
+- **BaseTestCase Interface**: All test cases extend the `BaseTestCase` interface
+- **Tagging System**: Tests are tagged with categories like `smoke`, `integration`, `performance`, etc.
+- **Test Organization**: Tests are organized by functionality and complexity
+- **Mock Functions**: Example mock functions for common scenarios
+
+## Recommended Test Tags (you can add others to your preference)
+
+- **`smoke`**: Critical tests that must pass for basic functionality
+- **`flaky`**: Tests that may be unreliable or environment-dependent
+- **`failing`**: Tests that are currently failing and need debugging
+
+## Running Tests
+
+### Run All Tests
+```bash
+npx run test example-test.ts
+```
+
+### Run Only Smoke Tests
+```bash
+npx run test-smoke example-test.ts
+```
+
+### Run Only Flaky Tests
+```bash
+npx run test-flkay *test*.ts
+```
+
+## Best Practices
+
+1. **Always use tags**: Tag your tests appropriately for easy filtering
+2. **Include descriptions**: Provide clear descriptions of what each test does
+3. **Use meaningful names**: Test names should clearly indicate what's being tested
+4. **Handle errors gracefully**: Catch and report errors appropriately
+5. **Use mocks for external dependencies**: Don't rely on external services in tests
+6. **Test both success and failure cases**: Ensure your tests cover edge cases
+
+## Integration with FRAIM
+
+This testing framework integrates with FRAIM's agent coordination system:
+
+- **AI Agents**: Use these tests during implementation phase
+- **CI/CD**: Automated test execution with proper tagging
+- **Evidence Collection**: Test results are collected as evidence for reviews
+
+## Customization
+
+To adapt this testing framework for your project:
+
+1. **Update mock functions**: Replace example mocks with your actual functions
+2. **Add project-specific tags**: Define tags relevant to your domain
+3. **Customize test structure**: Modify the test case interface as needed
+4. **Add setup/teardown**: Include any necessary test setup or cleanup
+5. **Configure CI integration**: Set up automated test execution in your CI pipeline

package/examples/simple-webapp/example-test.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env tsx
+
+/**
+ * Example Test Case for FRAIM Framework
+ * 
+ * This demonstrates how to write test cases using the FRAIM testing framework
+ * with proper tagging and structure.
+ */
+
+import { BaseTestCase, runTests } from '../../test-utils';
+
+// Example test case interface extending BaseTestCase
+interface ExampleTestCase extends BaseTestCase {
+  description: string;
+  testFunction: () => Promise<boolean>;
+}
+
+// Example test cases with different tags
+const EXAMPLE_TEST_CASES: ExampleTestCase[] = [
+  {
+    name: 'test_basic_functionality',
+    tags: ['smoke', 'basic'],
+    description: 'Should verify basic application functionality works',
+    testFunction: async () => {
+      console.log('🧪 Testing basic functionality...');
+      
+      // Example: Test that a basic function works
+      const result = await basicFunction();
+      
+      if (result !== 'success') {
+        console.log(`❌ Expected 'success', got '${result}'`);
+        return false;
+      }
+      
+      console.log('✅ Basic functionality test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_user_authentication',
+    tags: ['smoke', 'auth'],
+    description: 'Should verify user authentication works correctly',
+    testFunction: async () => {
+      console.log('🧪 Testing user authentication...');
+      
+      // Example: Test authentication flow
+      const authResult = await authenticateUser('test@example.com', 'password123');
+      
+      if (!authResult.success) {
+        console.log(`❌ Authentication failed: ${authResult.error}`);
+        return false;
+      }
+      
+      console.log('✅ User authentication test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_api_integration',
+    tags: ['integration', 'api'],
+    description: 'Should verify API integration works correctly',
+    testFunction: async () => {
+      console.log('🧪 Testing API integration...');
+      
+      // Example: Test API call
+      const apiResult = await callExternalAPI('https://api.example.com/data');
+      
+      if (!apiResult || !apiResult.data) {
+        console.log('❌ API integration failed - no data returned');
+        return false;
+      }
+      
+      console.log('✅ API integration test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_database_operations',
+    tags: ['database', 'integration'],
+    description: 'Should verify database operations work correctly',
+    testFunction: async () => {
+      console.log('🧪 Testing database operations...');
+      
+      // Example: Test database operations
+      const dbResult = await performDatabaseOperation();
+      
+      if (!dbResult.success) {
+        console.log(`❌ Database operation failed: ${dbResult.error}`);
+        return false;
+      }
+      
+      console.log('✅ Database operations test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_performance_benchmark',
+    tags: ['performance', 'flaky'],
+    description: 'Should verify performance meets requirements (may be flaky)',
+    testFunction: async () => {
+      console.log('🧪 Testing performance benchmark...');
+      
+      const startTime = Date.now();
+      await performExpensiveOperation();
+      const endTime = Date.now();
+      
+      const duration = endTime - startTime;
+      const maxDuration = 1000; // 1 second
+      
+      if (duration > maxDuration) {
+        console.log(`❌ Performance test failed: ${duration}ms > ${maxDuration}ms`);
+        return false;
+      }
+      
+      console.log(`✅ Performance test passed: ${duration}ms`);
+      return true;
+    }
+  },
+  {
+    name: 'test_failing_scenario',
+    tags: ['failing', 'debug'],
+    description: 'This test is currently failing and needs debugging',
+    testFunction: async () => {
+      console.log('🧪 Testing failing scenario...');
+      
+      // This test is intentionally failing to demonstrate the failing tag
+      console.log('❌ This test is currently failing for demonstration');
+      return false;
+    }
+  }
+];
+
+// Mock functions for demonstration
+async function basicFunction(): Promise<string> {
+  // Simulate some work
+  await new Promise(resolve => setTimeout(resolve, 10));
+  return 'success';
+}
+
+async function authenticateUser(email: string, password: string): Promise<{success: boolean, error?: string}> {
+  // Simulate authentication
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  if (email === 'test@example.com' && password === 'password123') {
+    return { success: true };
+  }
+  
+  return { success: false, error: 'Invalid credentials' };
+}
+
+async function callExternalAPI(url: string): Promise<{data?: any}> {
+  // Simulate API call
+  await new Promise(resolve => setTimeout(resolve, 100));
+  
+  return {
+    data: {
+      id: 1,
+      name: 'Test Data',
+      timestamp: new Date().toISOString()
+    }
+  };
+}
+
+async function performDatabaseOperation(): Promise<{success: boolean, error?: string}> {
+  // Simulate database operation
+  await new Promise(resolve => setTimeout(resolve, 75));
+  
+  return { success: true };
+}
+
+async function performExpensiveOperation(): Promise<void> {
+  // Simulate expensive operation
+  await new Promise(resolve => setTimeout(resolve, 500));
+}
+
+// Test runner function
+const runExampleTest = async (testCase: ExampleTestCase): Promise<boolean> => {
+  try {
+    return await testCase.testFunction();
+  } catch (error) {
+    console.log(`❌ Test ${testCase.name} threw an error: ${error}`);
+    return false;
+  }
+};
+
+await runTests(EXAMPLE_TEST_CASES, runExampleTest, 'Example Test Suite');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -49,6 +49,15 @@
     "tsx": "^4.0.0",
     "dotenv": "^16.0.0"
   },
+  "files": [
+    ".ai-agents/",
+    "examples/",
+    "bin/",
+    "*.js",
+    "*.ts",
+    "*.md",
+    "*.json"
+  ],
   "publishConfig": {
     "access": "public"
   }

package/setup.js

@@ -935,6 +935,14 @@ function copyAdditionalFiles() {
         'tsconfig.json'
     ];
     
+    // Copy GitHub workflow files
+    const workflowFiles = [
+        '.github/workflows/ci.yml',
+        '.github/workflows/phase-change.yml',
+        '.github/workflows/status-change.yml',
+        '.github/workflows/sync-on-pr-review.yml'
+    ];
+    
     additionalFiles.forEach(file => {
         try {
             const sourcePath = path.join(__dirname, file);
@@ -951,6 +959,27 @@ function copyAdditionalFiles() {
         }
     });
     
+    // Copy GitHub workflow files
+    workflowFiles.forEach(file => {
+        try {
+            const sourcePath = path.join(__dirname, file);
+            const destPath = file;
+            
+            // Ensure the .github/workflows directory exists
+            const destDir = path.dirname(destPath);
+            ensureDirectory(destDir);
+            
+            if (fs.existsSync(sourcePath)) {
+                fs.copyFileSync(sourcePath, destPath);
+                logSuccess(`Copied ${file}`);
+            } else {
+                console.log(`⚠️  Warning: ${file} not found in package`);
+            }
+        } catch (error) {
+            console.log(`⚠️  Warning: Could not copy ${file}: ${error.message}`);
+        }
+    });
+    
     // Copy examples
     try {
         const examplesSource = path.join(__dirname, 'examples', 'simple-webapp');

package/.cursor/rules/cursor-rules.mdc

@@ -1,8 +0,0 @@
----
-description: Centralized AI agent rules for Cursor
-alwaysApply: true
----
-
-# Cursor AI Agent Rules
-
-Thoroughly review `.ai-agents/agent-guardrails.md`

package/.cursor/rules/design.mdc

@@ -1,4 +0,0 @@
----
-alwaysApply: false
----
-Follow instructions in `.ai-agents/workflows/design.md`

package/.cursor/rules/implement.mdc

@@ -1,6 +0,0 @@
----
-
-alwaysApply: false
----
-
-Follow instructions in `.ai-agents/workflows/implement.md`

package/.cursor/rules/resolve.mdc

@@ -1,5 +0,0 @@
----
-alwaysApply: false
----
-
-Follow instructions in `.ai-agents/workflows/resolve.md`

package/.cursor/rules/retrospect.mdc

@@ -1,4 +0,0 @@
----
-alwaysApply: false
----
-Follow instructions in `.ai-agents/workflows/retrospect.md`

package/.cursor/rules/spec.mdc

@@ -1,4 +0,0 @@
----
-alwaysApply: false
----
-Follow instructions in `.ai-agents/workflows/spec.md`

package/.cursor/rules/test.mdc

@@ -1,5 +0,0 @@
----
-alwaysApply: false
----
-
-Follow instructions in `.ai-agents/workflows/test.md`

package/.windsurf/rules/windsurf-rules.md

@@ -1,7 +0,0 @@
----
-trigger: always_on
----
-
-# Windsurf AI Agent Rules
-
-Thoroughly review `.ai-agents/agent-guardrails.md`

package/.windsurf/workflows/resolve-issue.md

@@ -1,6 +0,0 @@
----
-description: Resolve issue (once confirmed complete)
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/resolve.md`

package/.windsurf/workflows/retrospect.md

@@ -1,6 +0,0 @@
----
-description: Resolve issue (once confirmed complete)
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/retrospect.md`

package/.windsurf/workflows/start-design.md

@@ -1,6 +0,0 @@
----
-description: Start working on the issue
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/design.md`

package/.windsurf/workflows/start-impl.md

@@ -1,6 +0,0 @@
----
-description: Implement issue
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/implement.md`

package/.windsurf/workflows/start-spec.md

@@ -1,6 +0,0 @@
----
-description: Spec Issue
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/spec.md`

package/.windsurf/workflows/start-tests.md

@@ -1,6 +0,0 @@
----
-description: Start writing tests
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/test.md`

package/CODEOWNERS

@@ -1,24 +0,0 @@
-# This file defines the code owners for the FRAIM repository
-# Code owners are automatically requested for review when someone opens a PR that modifies code they own
-# See: https://docs.github.com/en/repositories/managing-your-codebase-in-github/about-code-owners
-
-# Default owners for everything in the repo
-*       @mathursrus
-
-# Specific ownership for different parts of the codebase
-/agents/         @mathursrus
-/rules/          @mathursrus
-/workflows/      @mathursrus
-/templates/      @mathursrus
-/scripts/        @mathursrus
-/.github/        @mathursrus
-
-# Documentation
-/docs/           @mathursrus
-*.md             @mathursrus
-
-# Configuration files
-*.json           @mathursrus
-*.jsonc          @mathursrus
-*.yml            @mathursrus
-*.yaml           @mathursrus

package/DISTRIBUTION.md

@@ -1,187 +0,0 @@
-# 🚀 FRAIM Distribution Guide
-
-**Framework for Rigor-based AI Management - Where humans become AI managers through rigorous methodology**
-
-This guide covers all the ways to distribute and adopt the FRAIM framework.
-
-P.S. I have only tested #1 so far
-
-## 📦 Distribution Methods
-
-### 1. **NPX (Recommended)**
-```bash
-npx @fraim/framework init
-```
-
-**Benefits:**
-- Instant execution without installation
-- Always uses latest version
-- No global dependencies
-- Cross-platform compatibility
-
-**Package Details:**
-- Name: `@fraim/framework`
-- Scope: `@fraim`
-- Registry: npmjs.com
-
-### 2. **Python Package (pip)**
-```bash
-pip install fraim-framework
-fraim init
-```
-
-**Benefits:**
-- Python ecosystem integration
-- Virtual environment support
-- Easy dependency management
-- Cross-platform compatibility
-
-**Package Details:**
-- Name: `fraim-framework`
-- Registry: PyPI
-- Python: >=3.8
-
-### 3. **One-Line Installer**
-```bash
-curl -sSL https://fraim.dev/install.sh | bash -s -- --repo owner/repository
-```
-
-**Benefits:**
-- No package manager required
-- Works on any Unix-like system
-- Direct GitHub integration
-- Customizable installation
-
-### 4. **GitHub Action**
-```yaml
-- uses: mathursrus/fraim-setup@v1
-  with:
-    repository: ${{ github.repository }}
-    config: fraim-config.json
-```
-
-**Benefits:**
-- Automated setup in CI/CD
-- Repository integration
-- Team collaboration
-- Version control
-
-## 🎯 Quick Start Snippets
-
-### For New Repositories
-```bash
-# Create new repo and setup FRAIM
-gh repo create my-ai-project --public
-cd my-ai-project
-npx @fraim/framework init
-```
-
-### For Existing Repositories
-```bash
-# Add FRAIM to existing project
-cd existing-project
-npx @fraim/framework init
-```
-
-## 🔧 Configuration Options
-
-### Basic Setup
-```json
-{
-  "repository": {
-    "owner": "your-org",
-    "name": "your-repo"
-  },
-  "features": {
-    "labels": true,
-    "workflows": true,
-    "agentRules": ["cursor", "claude", "windsurf"]
-  }
-}
-```
-
-### Advanced Setup
-```json
-{
-  "features": {
-    "deployments": {
-      "enabled": true,
-      "environments": ["staging", "production"]
-    },
-    "notifications": {
-      "slack": "webhook-url",
-      "teams": "webhook-url"
-    }
-  },
-  "phases": {
-    "design": { "required_approvals": 2 },
-    "implementation": { "required_approvals": 3 },
-    "testing": { "auto_deploy": true }
-  }
-}
-```
-
-## 🚀 Launch Strategy
-
-### Phase 1: Early Adopters
-- **Target**: Individual developers and small teams
-- **Distribution**: NPX and GitHub releases
-- **Focus**: Core functionality and documentation
-
-### Phase 2: Team Adoption
-- **Target**: Development teams and organizations
-- **Distribution**: Python package and GitHub Actions
-- **Focus**: Team coordination and advanced features
-
-### Phase 3: Enterprise
-- **Target**: Large organizations and enterprises
-- **Distribution**: Enterprise packages and support
-- **Focus**: Compliance, security, and scalability
-
-## 📊 Success Metrics
-
-### Adoption Metrics
-- **Downloads**: NPX executions, pip installs
-- **Repositories**: GitHub stars, forks, usage
-- **Community**: Issues, PRs, discussions
-
-### Usage Metrics
-- **Active Users**: Monthly active repositories
-- **Feature Usage**: Workflow executions, label usage
-- **Retention**: Repeat usage, long-term adoption
-
-### Quality Metrics
-- **Satisfaction**: User ratings, feedback scores
-- **Support**: Issue resolution time, documentation quality
-- **Performance**: Setup time, workflow success rates
-
-## 🔗 Distribution URLs
-
-### Primary
-- **NPX**: `npx @fraim/framework`
-- **Python**: `pip install fraim-framework`
-- **GitHub**: `https://github.com/mathursrus/FRAIM`
-
-### Documentation
-- **Main Docs**: `https://fraim.dev`
-- **GitHub Wiki**: `https://github.com/mathursrus/FRAIM/wiki`
-- **Examples**: `https://github.com/mathursrus/FRAIM/tree/master/examples`
-
-### Support
-- **Issues**: `https://github.com/mathursrus/FRAIM/issues`
-- **Discussions**: `https://github.com/mathursrus/FRAIM/discussions`
-- **Community**: `https://github.com/mathursrus/FRAIM/community`
-
-## 🎯 Next Steps
-
-1. **Choose Distribution Method**: Select the best option for your use case
-2. **Setup FRAIM**: Follow the [quick start guide](docs/guides/getting-started.md)
-3. **Configure Agents**: Customize AI agent rules and workflows
-4. **Start Managing**: Begin coordinating AI agents with RIGOR methodology
-5. **Share Feedback**: Contribute to the community and framework improvement
-
----
-
-**Ready to become an AI manager?** 🚀
-
-Start your FRAIM journey today with any of the distribution methods above!

package/PUBLISH_INSTRUCTIONS.md

@@ -1,93 +0,0 @@
-# Publishing FRAIM v2 to npm
-
-## Prerequisites
-1. **npm account**: You need an npm account to publish packages
-2. **npm CLI**: Make sure you have npm installed and updated
-
-## Step 1: Login to npm
-```bash
-npm login
-```
-Enter your npm username, password, and email when prompted.
-
-## Step 2: Verify Login
-```bash
-npm whoami
-```
-Should display your npm username.
-
-## Step 3: Test the Package (Optional but Recommended)
-```bash
-# Test the package locally
-npm pack
-# This creates a .tgz file you can inspect
-
-# Test installation locally
-npm install -g ./fraim-framework-2.0.0.tgz
-fraim --help
-```
-
-## Step 4: Publish to npm
-```bash
-npm publish
-```
-
-## Step 5: Verify Publication
-```bash
-# Check the package on npm
-npm view fraim-framework
-
-# Test installation from npm
-npm install -g fraim-framework@2.0.0
-fraim --help
-```
-
-## What's Included in v2.0.0
-
-### 🚀 Major Features
-- **Complete Generic Framework**: No Ashley-specific IP
-- **13 Comprehensive Rule Files**: Full AI agent management
-- **Simplified Label System**: 9 essential labels
-- **Spec Workflow**: Requirements and UX definition
-- **Timeout Management**: Advanced script execution with visibility
-- **Evidence-Based Validation**: Mandatory test evidence
-- **Systematic Debugging**: Structured debugging patterns
-
-### 📦 Package Contents
-- `bin/fraim.js` - Main CLI executable
-- `index.js` - Main entry point
-- `setup.js` - Setup script for new projects
-- `package.json` - Package configuration (v2.0.0)
-- `.ai-agents/` - Complete rule system
-- `examples/` - Example test cases with documentation
-- `CHANGELOG.md` - Detailed changelog
-- `README.md` - Marketing-style documentation
-
-### 🎯 Installation
-```bash
-npm install -g fraim-framework
-fraim init
-```
-
-## Post-Publication Tasks
-
-1. **Update README**: Ensure all installation instructions use the new v2 commands
-2. **GitHub Release**: Create a GitHub release for v2.0.0
-3. **Documentation**: Update any external documentation
-4. **Social Media**: Share the LinkedIn post about v2
-
-## Rollback Plan (if needed)
-```bash
-# If you need to unpublish (only works within 24 hours)
-npm unpublish fraim-framework@2.0.0
-
-# Or deprecate the version
-npm deprecate fraim-framework@2.0.0 "Use latest version instead"
-```
-
-## Success Metrics
-- Package successfully published to npm
-- Installation works: `npm install -g fraim-framework`
-- CLI works: `fraim --help`
-- Setup works: `fraim init`
-- All examples and documentation updated

package/getting-started.md

@@ -1,143 +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.
-
-## 🎯 What is FRAIM?
-
-FRAIM is a framework that empowers human developers to coordinate AI agents using the  **RIGOR methodology**: Reviews • Isolation • GitOps • Observability • Retrospectives.
-
-Instead of manually managing AI tools, FRAIM gives you the structure and automation to orchestrate AI agents like a professional team manager.
-
-## 🚀 Quick Start (30 seconds)
-
-### 1. Navigate to Your Repository
-```bash
-cd your-project
-```
-
-### 2. Setup FRAIM
-```bash
-npx @fraim/setup init
-```
-
-### 3. Create Your Issue List in your Git Repo
-```bash
-gh issue create --title "Add user authentication" 
-```
-
-### 4. Let your AI Agents do the Magic! 🎉
-Cursor: @design 1
-Windsurf: /start-design 1
-Claude: @design 1
-
-AI Agent automatically:
-- 🔄 Labels the Git issue with phase:design
-
-GitHub automatically:
-- 🔄 Creates branch: `feature/1-add-user-authentication`
-- 🔄 Creates draft PR
-- 🔄 Sets status: `status:wip`
-
-AI Agent automatically:
-- 🔄 Checks out the new branch
-- 🔄 Researches codebase, architecture, issue and writes a PRD/RFC
-- 🔄 Commits, Syncs the branch and Labels the Git issue with status:needs-review for you to PR
-
-You:
-- Watch the magic happen
-- Review the PR like you normally would, and add comments
-- Let the AI Agent know if you want it to iterate, or proceed to @implement (Claude, Cursor), or /start-impl (Windsurf)
-
-
-## 🧠 Understanding the RIGOR Methodology
-
-FRAIM is built on five core principles that ensure reliable, scalable, continuously improving AI coordination:
-
-- **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
-
-
-## 📋 Workflow Phases
-
-### Phase 1: Design (`phase:design`)
-1. **You**: Tell the agent to move into this phase and give it the issue number
-2. **AI Action**: Labels issue `phase:design`, moves to branch, creates RFC/UX/test-plan, commits and sends out PR, labels issue `status:needs-review`
-3. **Review**: Stakeholders review and approve design
-4. **Issue, PR State**: Git automatically changes status between wip, complete
-
-### Phase 2: Implementation (`phase:impl`)
-1. **You**: Tell the agent to move into this phase
-2. **AI Action**: Labels issue `phase:impl`, moves to branch, consults issue/code/rfcs, implements code and tests, runs tests, commits and sends out PR
-3. **Review**: Stakeholders review and approve implementation
-4. **Issue, PR State**: Git automatically changes status between wip, complete
-
-### Phase 3: Resolve 
-1. **You**: Tell the agent to move into this phase once totally satisfied with the implementation and tests
-2. **AI Action**: Pulls from master, deals with merge issues (with your help if needed), confirms everything still works, pushes to master, deletes remote and local branches, cleans up local copy of the branch
-3. **Git**: Runs CI and prevents merging if failed
-
-## 🏷️ Label System
-
-### Phase Labels
-- `phase:design` - Design and RFC creation
-- `phase:impl` - Implementation and development
-- `phase:tests` - Testing and validation (if needed, I ask AI Agents to write tests as part of implementation)
-
-### Status Labels
-- `status:wip` - Work in progress
-- `status:needs-review` - Ready for review
-- `status:complete` - Work completed
-
-### Agent Labels (for future, I don't use these yet)
-- `ai-agent:cursor` - Assigned to Cursor
-- `ai-agent:claude` - Assigned to Claude
-- `ai-agent:windsurf` - Assigned to Windsurf
-
-## 🔧 Advanced Setup
-
-### Interactive Wizard
-```bash
-npx @fraim/setup 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/setup setup owner/repository --config custom-config.json
-```
-
-### Partial Setup
-```bash
-# Only create labels
-npx @fraim/setup setup owner/repository --labels-only
-
-# Only setup workflows
-npx @fraim/setup setup owner/repository --workflows-only
-```
-
-## 🎯 Success Metrics - I hope these happen for you
-
-- **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
-
-## 🚀 Ready to Become an AI Manager?
-
-```bash
-npx @fraim/setup init
-```
-
-**FRAIM: Where humans become AI managers through rigorous methodology**
-
----
-

package/install.sh

@@ -1,58 +0,0 @@
-#!/bin/bash
-
-# FRAIM One-Line Installer
-# Framework for Rigor-based AI Management
-# Where humans become AI managers through rigorous methodology
-
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Banner
-echo -e "${BLUE}"
-cat << 'EOF'
-╔══════════════════════════════════════════════════════════════╗
-║  🚀 FRAIM                                                  ║
-║  Framework for Rigor-based AI Management                    ║
-║  Where humans become AI managers                            ║
-╚══════════════════════════════════════════════════════════════╝
-EOF
-echo -e "${NC}"
-
-echo -e "${GREEN}🤖 Welcome to FRAIM!${NC}"
-echo -e "${GREEN}Where humans become AI managers through rigorous methodology${NC}\n"
-
-# Check if we're in a git repository
-if [ ! -d ".git" ]; then
-    echo -e "${RED}❌ Error: Not in a git repository${NC}"
-    echo "Please run this script from within a git repository."
-    exit 1
-fi
-
-# Check if FRAIM is already installed
-if [ -d "FRAIM" ]; then
-    echo -e "${YELLOW}⚠️  FRAIM appears to already be installed in this repository${NC}"
-    echo "If you want to reinstall, please remove the existing FRAIM folder first."
-    exit 1
-fi
-
-echo -e "${BLUE}📥 Installing FRAIM framework...${NC}"
-
-# Download FRAIM from GitHub
-echo "Downloading FRAIM framework..."
-curl -sSL https://raw.githubusercontent.com/mathursrus/FRAIM/master/install.sh | bash -s -- --repo $(git remote get-url origin | sed 's/.*github.com[:/]\([^/]*\/[^/]*\).*/\1/' | sed 's/\.git$//')
-
-echo -e "\n${GREEN}✅ FRAIM installation complete!${NC}"
-echo -e "\n${BLUE}🚀 Next steps:${NC}"
-echo "1. Review the FRAIM folder that was created"
-echo "2. Run: npx @fraim/framework init"
-echo "3. Start managing your AI agents with RIGOR methodology!"
-echo -e "\n${BLUE}📚 Learn more:${NC}"
-echo "Documentation: https://github.com/mathursrus/FRAIM"
-echo -e "\n${GREEN}🎯 Ready to become an AI manager?${NC}"
-echo "The FRAIM framework is now installed and ready to use!"

package/linkedin-post.md

@@ -1,23 +0,0 @@
-# FRAIMv2 - The Future of how we work with AI?
-
-🚀 **AI coding agents are brilliant but chaotic.**
-
-They can build prototypes fast, but fail spectacularly at production-ready code.
-
-**Solution: Manage them like human developers.**
-
-FRAIMv2 applies enterprise-grade discipline to AI agent teams:
-• Clear guardrails to prevent costly mistakes
-• Structured workflows to avoid chaos
-• Evidence-based validation (not "looks good" claims)
-• Learning systems to improve over time
-• Debugging patterns and anti-patterns
-• Balance between determinism and creativity
-
-**Result:** Transform from solo developer to AI manager orchestrating production-ready code.
-
-Is this the future of how we work?
-
-Ready to transform how you work with AI? Check out FRAIM: https://github.com/mathursrus/FRAIM
-
-#AI #SoftwareDevelopment #Productivity #Innovation #TechLeadership #Coding #Agile #DevOps