fraim-framework 2.0.4 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.4",
+  "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": {

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/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/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