fraim-framework 1.0.12 → 2.0.2

package/.ai-agents/scripts/prep-issue.sh

@@ -0,0 +1,162 @@
+#!/bin/bash
+
+# Project Issue Preparation Script
+# This script automates the deterministic workflow from prep.md
+
+set -e  # Exit on any error
+
+# Function to detect editor from issue labels
+detect_editor_from_issue() {
+    local issue_num=$1
+    
+    # Try GitHub CLI first
+    if command -v gh &> /dev/null; then
+        local labels=$(gh issue view $issue_num --json labels --jq '.labels[].name' 2>/dev/null | grep "^ai-agent:" | head -1)
+        if [ -n "$labels" ]; then
+            echo "$labels" | sed 's/ai-agent://'
+            return 0
+        fi
+    else
+        # Fallback to curl (requires GitHub token in GITHUB_TOKEN env var)
+        if [ -n "$GITHUB_TOKEN" ]; then
+            local labels=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
+                "https://api.github.com/repos/{OWNER}/{REPO}/issues/$issue_num" \
+                | grep -o '"name":"ai-agent:[^"]*"' | sed 's/"name":"ai-agent://' | sed 's/"//' 2>/dev/null)
+        else
+            echo "Warning: No GitHub CLI or GITHUB_TOKEN found. Cannot auto-detect editor from issue labels." >&2
+        fi
+    fi
+    
+    return 1
+}
+
+# Function to open editor with project
+open_editor() {
+    local editor=$1
+    local project_path=$2
+    
+    case "$editor" in
+        "windsurf")
+            if command -v windsurf &> /dev/null; then
+                echo "Opening Windsurf..."
+                windsurf "$project_path" &
+            else
+                echo "Windsurf not found in PATH"
+                return 1
+            fi
+            ;;
+        "cursor")
+            if command -v cursor &> /dev/null; then
+                echo "Opening Cursor..."
+                cursor "$project_path" &
+            else
+                echo "Cursor not found in PATH"
+                return 1
+            fi
+            ;;
+        *)
+            echo "Unknown editor: $editor"
+            return 1
+            ;;
+    esac
+}
+
+# Check if issue number is provided
+if [ $# -eq 0 ]; then
+    echo "Usage: $0 <issue_number> [editor]"
+    echo "Example: $0 123 windsurf"
+    exit 1
+fi
+
+ISSUE_NUMBER=$1
+EDITOR=${2:-""}  # Will be set later if not provided
+
+echo "=== Project Issue Preparation ==="
+echo "Preparing for Issue #$ISSUE_NUMBER"
+echo
+
+# Auto-detect editor from issue labels if not provided
+if [ -z "$EDITOR" ]; then
+    echo "Auto-detecting editor from issue labels..."
+    DETECTED_EDITOR=$(detect_editor_from_issue $ISSUE_NUMBER)
+    if [ -n "$DETECTED_EDITOR" ]; then
+        EDITOR="$DETECTED_EDITOR"
+        echo "Detected editor: $EDITOR"
+    else
+        echo "Could not auto-detect editor. Defaulting to windsurf."
+        EDITOR="windsurf"
+    fi
+else
+    echo "Using specified editor: $EDITOR"
+fi
+
+# Get current directory and parent
+CURRENT_DIR=$(pwd)
+PARENT_DIR=$(dirname "$CURRENT_DIR")
+
+echo "Current directory: $CURRENT_DIR"
+echo "Parent directory: $PARENT_DIR"
+
+# Define clone directory name
+CLONE_DIR="FRAIM - Issue $ISSUE_NUMBER"
+CLONE_PATH="$PARENT_DIR/$CLONE_DIR"
+
+# Check if directory already exists
+if [ -d "$CLONE_PATH" ]; then
+    echo "Directory already exists: $CLONE_PATH"
+    echo "Entering existing directory..."
+    cd "$CLONE_PATH"
+else
+    echo "Creating new clone directory..."
+    
+    # Change to parent directory
+    cd "$PARENT_DIR"
+
+# Clone the repository
+echo "Cloning to: $CLONE_PATH"
+git clone https://github.com/mathursrus/FRAIM.git "$CLONE_DIR"
+
+# Change into the cloned repository
+cd "$CLONE_DIR"
+fi
+
+# Create and checkout feature branch
+BRANCH_NAME="feature/$ISSUE_NUMBER"
+echo "Creating/checking out branch: $BRANCH_NAME"
+
+if git show-ref --verify --quiet refs/heads/$BRANCH_NAME; then
+    echo "Branch exists locally, checking out..."
+    git checkout $BRANCH_NAME
+elif git show-ref --verify --quiet refs/remotes/origin/$BRANCH_NAME; then
+    echo "Branch exists on remote, checking out..."
+    git checkout -b $BRANCH_NAME origin/$BRANCH_NAME
+else
+    echo "Creating new branch..."
+    git checkout -b $BRANCH_NAME
+fi
+
+# Push branch to origin if it doesn't exist remotely
+if ! git show-ref --verify --quiet refs/remotes/origin/$BRANCH_NAME; then
+    echo "Pushing new branch to origin..."
+    git push -u origin $BRANCH_NAME
+fi
+
+echo
+echo "✅ Setup complete!"
+echo "📁 Working directory: $CLONE_PATH"
+echo "🌿 Branch: $BRANCH_NAME"
+echo "🔧 Editor: $EDITOR"
+echo
+
+# Open the editor
+echo "Opening $EDITOR..."
+if open_editor "$EDITOR" "$CLONE_PATH"; then
+    echo "✅ $EDITOR opened successfully"
+else
+    echo "❌ Failed to open $EDITOR"
+    echo "Please manually open your editor with: $CLONE_PATH"
+fi
+
+echo
+echo "🚀 Ready to work on Issue #$ISSUE_NUMBER!"
+echo "Remember to work only in this directory: $CLONE_PATH"

package/.ai-agents/templates/evidence/Design-Evidence.md

@@ -0,0 +1,30 @@
+# Feature: <Title>
+Issue: #<issue>  
+Feature Spec: <Link to Feature Spec, if any>
+PR: <Link to PR>
+
+## Completeness Evidence
+ - Issue tagged with label `phase:design`: Yes/No
+ - Issue tagged with label `status:needs-review`: Yes/No
+ - All files committed/synced to branch: Yes/No
+ - Table with following columns 
+   - PR Comment
+   - How Addressed
+
+
+## Due Diligence Evidence
+ - Reviewed feaure spec in detail (if feature spec present): Yes/No
+ - Reviwed code base in detail to understand and repro the issue: Yes/No
+ - Included detailed design, validation plan, test strategy in doc: Yes/No
+
+## Prototype & Validation Evidence
+ - [ ] Built simple proof-of-concept that works end-to-end
+ - [ ] Manually tested complete user flow (browser/curl)
+ - [ ] Verified solution actually works before designing architecture
+ - [ ] Identified minimal viable implementation
+ - [ ] Documented what works vs. what's overengineered
+   
+## Continous Learning
+ - Table with following columns
+    - Learning
+    - Agent Rule Updates (what agent rule file was updated to ensure the learning is durable)

package/.ai-agents/templates/evidence/Implementation-BugEvidence.md

@@ -0,0 +1,48 @@
+# Bug: <Title>
+Issue: #<issue>  
+Bug Spec: <Link to Bug Spec>
+PR: <Link to PR>
+
+## Completeness Evidence
+ - Issue tagged with label `phase:impl`: Yes/No
+ - Issue tagged with label `status:needs-review`: Yes/No
+ - All files committed/synced to branch: Yes/No
+ - Table with following columns 
+   - PR Comment
+   - How Addressed
+
+## Implementation Quality Checkpoints
+ - [ ] Code complexity reviewed (no overengineering)
+ - [ ] No resource waste (excessive retries, delays, workarounds)
+ - [ ] Solution based on proven approach from design phase
+ - [ ] All new files/functions are actually used
+
+## Validation Evidence
+ - Complete valiation performed as suggested in bug spec: Yes/No
+ - Table with following columns
+    - Validation Step (manual vs automated)
+    - Validation Result (pass vs fail)
+    - Failure Analysis (if fail)
+
+## New Files/Functions Created
+ - Table with the following columns
+    - File/Function Name
+    - Purpose
+    - Who is using/importing/calling it
+    - Is it actually used? (Yes/No - if No, explain why it exists)
+
+## New Tests Added
+ - Required if existing test cases did not repro the bug, Optional if bug fix made previously failing test cases pass
+ - For each new test case added, did it pass/fail
+
+## Existing Test Suites Run
+ - Table with following columns
+    - Test Suite
+    - Was it Run (if not, why not - it's ok to not run a suite if there is no impact of your work to it as covered in agent-testing-guidelines.md)
+    - Failing Tests
+    - Failure Analysis (if any tests fail)
+
+## Continous Learning
+ - Table with following columns
+    - Learning
+    - Agent Rule Updates (what agent rule file was updated to ensure the learning is durable)

package/.ai-agents/templates/evidence/Implementation-FeatureEvidence.md

@@ -0,0 +1,54 @@
+# Feature: <Title>
+Issue: #<issue>  
+Tech Spec: <Link to tech spec>
+PR: <Link to PR>
+
+## Completeness Evidence
+ - All phases of tech spec complete: Yes/No 
+ - Issue tagged with label `phase:impl`: Yes/No
+ - Issue tagged with label `status:needs-review`: Yes/No
+ - All files committed/synced to branch: Yes/No
+ - Table with following columns 
+   - PR Comment
+   - How Addressed
+
+## Implementation Quality Checkpoints
+ - [ ] Code complexity reviewed (no overengineering)
+ - [ ] No resource waste (excessive retries, delays, workarounds)
+ - [ ] Solution based on proven prototype from design phase
+ - [ ] All new files/functions are actually used
+
+## Validation Evidence
+ - Complete valiation performed as suggested in tech spec: Yes/No
+ - Table with following columns
+    - Validation Step (manual vs automated)
+    - Validation Result (pass vs fail)
+    - Failure Analysis (if fail)
+
+## New Files/Functions Created
+ - Table with the following columns
+    - File/Function Name
+    - Purpose
+    - Who is using/importing/calling it
+    - Is it actually used? (Yes/No - if No, explain why it exists)
+
+## New Tests Added
+ - Added all tests suggested in tech spec: Yes/No
+ - Table with the following columns
+    - Test Case Name
+    - What is test case validating
+    - Test Result (pass vs fail)
+    - Failure Analysis (if fail)
+
+## Existing Test Suites Run
+ - Table with following columns
+    - Test Suite
+    - Was it Run (if not, why not - it's ok to not run a suite if there is no impact of your work to it as covered in agent-testing-guidelines.md)
+    - Failing Tests
+    - Failure Analysis (if any tests fail)
+
+   
+## Continous Learning
+ - Table with following columns
+    - Learning
+    - Agent Rule Updates (what agent rule file was updated to ensure the learning is durable)

package/.ai-agents/templates/evidence/Spec-Evidence.md

@@ -0,0 +1,19 @@
+# Feature Specification: <Title>
+Issue: #<issue>  
+PR: <Link to PR>
+
+## Completeness Evidence
+ - Issue tagged with label `phase:spec`: Yes/No
+ - Issue tagged with label `status:needs-review`: Yes/No
+ - All specification documents committed/synced to branch: Yes/No
+ - Table with following columns 
+   - Customer Research Area
+   - Sources of Information
+ - Table with following columns 
+   - PR Comment
+   - How Addressed
+
+## Continuous Learning
+ - Table with following columns
+    - Learning
+    - Agent Rule Updates (what agent rule file was updated to ensure the learning is durable)

package/.ai-agents/templates/help/HelpNeeded.md

@@ -0,0 +1,14 @@
+# Feature: <Title>
+Issue: #<issue>  
+PR: <Link to PR>
+
+## Help Needed
+ - What help is needed? Be as specific as possible
+ - What is it blocking?
+ - What is the impact?
+
+## What has been tried
+ - What solutions have been tried to unblock? What was the result?
+
+## What Options exist
+ - Do you have options in mind? If so, what are the Pros/Cons and what is your suggestion?

package/.ai-agents/templates/retrospective/RETROSPECTIVE-TEMPLATE.md

@@ -0,0 +1,55 @@
+# Postmortem: {Issue Title} - Issue #{issue-number}
+
+**Date**: {current_date}  
+**Duration**: {time_spent}  
+**Objective**: {issue_description}  
+**Outcome**: {success/failure/partial}
+
+## Executive Summary
+
+{2-3 sentence summary of what happened and the outcome}
+
+## Timeline of Events
+
+### Phase 1: {Phase Name}
+- ✅/❌ **Action**: Description
+- ✅/❌ **Action**: Description
+
+### Phase 2: {Phase Name}
+- ✅/❌ **Action**: Description
+- ✅/❌ **Action**: Description
+
+## Root Cause Analysis
+
+### 1. **Primary Cause**
+**Problem**: {main issue}
+**Impact**: {what this caused}
+
+### 2. **Contributing Factors**
+**Problem**: {secondary issues}
+**Impact**: {what these caused}
+
+## What Went Wrong
+
+1. **Issue 1**: Description
+2. **Issue 2**: Description
+
+## What Went Right
+
+1. **Success 1**: Description
+2. **Success 2**: Description
+
+## Lessons Learned
+
+1. **Learning 1**: Description
+2. **Learning 2**: Description
+
+## Agent Rule Updates Made to avoid recurrence
+
+1. **Rule 1**: Description
+2. **Rule 2**: Description
+
+## Enforcement Updates Made to avoid recurrence
+
+1. **Improvement 1**: Description
+2. **Improvement 2**: Description

package/.ai-agents/templates/specs/BUGSPEC-TEMPLATE.md

@@ -0,0 +1,37 @@
+# Bug: <Title>
+
+Issue: #<issue>  
+Owner: <agent>
+
+## Customer 
+
+## Customer Problem being solved
+
+## Repro Steps
+- Specific steps in the user workflow that reproduce the bug (eg start in dashboard, click on tab x, see list y, approve item z ....)
+- Confirm that you have reproduced the bug
+
+## Root Cause
+- What root cause was identified after repro and code analysis
+
+## Fix Details
+- UI, API, Service, DB changes: Which files will be modified and for what?
+ 
+## Validation Plan
+- Table with following columns
+  - User Scenario
+  - Expected outcome
+  - Validation method (UI validation, API validation, Database validation ...)
+
+## Confidence Level
+- On a scale of 0 to 100, how confident are you that your fix will work?
+
+## Test Matrix
+- Unit(as many as needed, mocking ok): what core functionality will be tested. What test suite will be added? Which existing test suites will be modified?
+- Integration(only mock external services): what tests will ensure the full stack integration does not regress. What test suite will be added? Which existing test suites will be modified?
+- E2E(1 at most, no mocking): If any changes are made to external integrations, what end to end tests will ensure external integrations work as expected.
+
+## Future Prevention
+ - What will prevent future introduction of similar bugs
+ - What agent rules will you update to ensure similar bugs do not recur
+ - What enforcement will you create to ensure similar bugs are caught before they are checked in

package/.ai-agents/templates/specs/FEATURESPEC-TEMPLATE.md

@@ -0,0 +1,29 @@
+# Feature: <Title>
+
+Issue: #<issue>  
+Owner: <agent>
+
+## Customer 
+
+## Customer's Desired Outcome
+
+## Customer Problem being solved
+
+## User Experience that will solve the problem
+- Specific steps in the user workflow (eg start in dashboard, click on tab x, see list y, approve item z ....)
+- UI mocks showing the desired experience. Put these in the `docs/feature specs/mocks` folder and link to them here.
+
+## Validation Plan
+- How will you know the feature is working as intended (validate via browser, api, ...)
+- What steps will you follow to ensure the feature works
+
+## Alternatives
+- Table with following columns
+  - Alternative: What other way could the customer solve their problem?
+  - Why discard?: Why is this alternative not chosen?
+
+## Competitive Landscape
+- Table with the following
+  - Competitor 
+  - How they are solving the same problem
+  - What do customers say about this solution

package/.ai-agents/templates/specs/TECHSPEC-TEMPLATE.md

@@ -0,0 +1,39 @@
+# Feature: <Title>
+
+Issue: #<issue>  
+Owner: <agent>
+
+## Customer 
+
+## Customer Problem being solved
+
+## User Experience that will solve the problem
+- Specific steps in the user workflow 
+  - If UI feature: start on UI page a, click on tab x, see list y, approve item z, achieve outcome ....
+  - If API feature: call API a with params x, y, z, receive result
+  - If refactoring/rearchitecture: what is the simpler developer workflow 
+
+## Technical Details
+- UI changes: Which files will be modified and for what?
+- API surface (OpenAPI) changes
+- Data model / schema changes
+- Failure modes & timeouts
+- Telemetry & analytics
+
+## Confidence Level
+- On a scale of 0 to 100, how confident are you that your solution will work?
+
+## Validation Plan
+- Table with following columns
+  - User Scenario
+  - Expected outcome
+  - Validation method (UI validation, API validation, Database validation ...)
+
+## Test Matrix
+- Unit(as many as needed, mocking ok): what core functionality will be tested. What test suite will be added? Which existing test suites will be modified?
+- Integration(only mock external services): what tests will ensure the full stack integration does not regress. What test suite will be added? Which existing test suites will be modified?
+- E2E(1 at most, no mocking): If any changes are made to external integrations, what end to end tests will ensure external integrations work as expected.
+
+## Risks & Mitigations
+
+## Observability (logs, metrics, alerts)

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

@@ -0,0 +1,121 @@
+# Design Phase
+
+## INTENT
+To create comprehensive, detailed technical design documents that plan solutions before implementation, ensuring proper architecture, clear requirements, and stakeholder alignment through structured RFCs and bug fix templates.
+
+## PRINCIPLES
+- **Design First**: Plan before implementing to avoid rework
+- **Template Consistency**: Use established templates for different types of changes
+- **Stakeholder Alignment**: Get review and approval before implementation
+- **Clear Documentation**: Create detailed, actionable design documents
+- **Iterative Refinement**: Incorporate feedback and iterate on designs
+- **Spike-First Development**: Follow `.ai-agents/rules/spike-first-development.md` to validate technology compatibility before building complex solutions
+
+## DESIGN WORKFLOW
+
+### Step 1: Issue Identification
+Ask for {issue_number} (and optional {slug})
+### Step 2: Phase Initiation
+Label the issue 'phase:design' (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: Pre-Creation Validation
+Before creating any design document, agents MUST:
+
+1. **Spike-First Development Check**:
+   - Read and follow `.ai-agents/rules/spike-first-development.md`
+   - If design involves unfamiliar technology, plan spike/proof-of-concept first
+   - Validate technology compatibility before designing complex solutions
+   - Avoid "Build First, Integrate Later" anti-pattern
+
+2. **Verify Template Selection**:
+   - For bug fixes: Use `.ai-agents/templates/specs/BUGSPEC-TEMPLATE.md`
+   - For new features: Use `.ai-agents/templates/specs/TECHSPEC-TEMPLATE.md`
+   - Confirm template exists before proceeding
+   - If you cannot find the template, stop and ask for help as per `.ai-agents/rules/communication.md`
+
+3. **Validate Naming Convention**:
+   - Format: `docs/rfcs/{issue_number}-{kebab-title}.md`
+   - Example: `docs/rfcs/228-improve-token-refresh.md`
+   - NO other naming patterns allowed
+
+4. **Template Compliance Check**:
+   - Read the selected template first
+   - Ensure all required sections are included
+   - Verify placeholder format matches template
+
+5. **Workflow Rule Verification**:
+   - Confirm issue is labeled `phase:design`
+   - Verify branch exists before starting work
+   - Check working directory is correct
+
+### Step 6: Design Document Creation
+Your work entails the following:
+- Create docs/rfcs/{issue_number}-{slug}.md.  
+- Use the correct template as per #1
+- Check if there is an existing spec for  this issue. Specs are stored in `docs/feature specs/` and share the same naming convention as the RFCs. If there is an existing spec, read through it and understand if fully.
+- Understand the issue, the existing codebase, and be detailed in your technical design. The better your initial design, manual valiation, testing plan, the smoother the implementation will go.
+
+
+### Step 7: Design Creation Checklist
+Before commiting your work, verify:
+- [ ] Correct template used (BUGFIX-TEMPLATE.md or RFC-TEMPLATE.md)
+- [ ] Proper file naming: `{issue_number}-{kebab-title}.md`
+- [ ] All template sections completed
+- [ ] No placeholder text remaining
+- [ ] Issue labeled `phase:design`
+- [ ] Working in correct branch
+- [ ] File saved in `docs/rfcs/` directory
+- [ ] If issue is a bug, you have reproduced it
+- [ ] You understand the codebase and have high confidence in your design
+
+### Step 8: Submit for Review
+- Commit and sync your work
+- Label the issue 'status:needs-review' and remove 'status:wip'
+- Update the PR with a comment to include evidence - Use template `.ai-agents/templates/evidence/Design-Evidence.md`
+- Follow `.ai-agents/rules/pr-workflow-completeness.md`
+
+### Step 9: Iteration
+If workflow actions or reviewer feedback indicates more work is needed:
+- Label the issue 'status:wip' and remove 'status:needs-review'
+- Go back to Step 6 and iterate until PR is approved
+
+## EXAMPLES
+
+### Good: Comprehensive Design Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84, slug: "fix-sync-timeout"
+2. ✅ Phase: Set phase:design, PR created
+3. ✅ Environment: User ran prep-issue.sh, ready to work
+4. ✅ Location: Working in prepared workspace with Serena indexing
+5. ✅ Design: Created docs/rfcs/84-fix-sync-timeout.md
+6. ✅ Template: Used BUG-TEMPLATE.md for bug fix
+7. ✅ Review: Set status:needs-review
+8. ✅ Iteration: Incorporated feedback, updated design
+Result: Clear, actionable design document
+```
+
+### Bad: Incomplete Design Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84
+2. ❌ Skip: Didn't set phase:design
+3. ❌ Skip: Didn't create branch
+4. ❌ Skip: Started coding without design
+5. ❌ Skip: No RFC document created
+6. ❌ Skip: No stakeholder review
+Result: Unclear requirements, potential rework
+```