fraim-framework 2.0.30 → 2.0.33

package/registry/workflows/performance/analyze-performance.md

@@ -1,63 +1,65 @@
-# Performance Analysis Phase
-
-## INTENT
-To diagnose production performance issues (CPU, Memory, Swap) and provide actionable recommendations for stabilization without performing direct application or infrastructure modifications.
-
-## PRINCIPLES
-- **Observational Only**: Do not modify code or infrastructure during this phase.
-- **Data-Driven**: Base all recommendations on metrics collected from the environment.
-- **Non-Invasive**: Use non-destructive commands that do not impact server stability.
-- **Actionable**: Provide clear, prioritized recommendations for remediation.
-
-## ANALYSIS WORKFLOW
-
-### Step 1: Run the Performance Profiler
-Execute the profiling script against the production environment to collect plan-level and process-level metrics.
-// turbo
-```bash
-# 1. Fetch profile-server.ts using get_fraim_file and save to machine temp
-# (Agent implementation detail: use os.tmpdir())
-
-# 2. Run from temp
-npx tsx /path/to/temp/profile-server.ts --prod
-```
-
-### Step 2: Inspect Automated Diagnosis
-Review the "Step 4: Automated Diagnosis" section of the output. 
-It will specifically check for:
-- **Swap Death**: If >95% swap is used, the server is thrashing.
-- **Absent Application**: If `server.js` is missing, the infrastructure is healthy but the app is crashed/not starting.
-- **Infrastructure Hogs**: If Azure agents (Kudu/dotnet) are consuming excessive RAM.
-
-### Step 3: Deep Dive Log Analysis
-If a crash loop or high operation frequency is suspected, collect and analyze application logs.
-```bash
-npx tsx tmp/profile-server.ts --prod --logs
-```
-Look for:
-- Frequency of initialization logs (e.g., "Ensured unique index").
-- Patterns indicative of OOM events or unhandled exceptions.
-- High volume of specific operations (e.g., decryptions) suggesting an infinite loop.
-
-### Step 4: Formulate Recommendations
-Based on the diagnosis, provide specific recommendations in your response or an implementation plan (if a fix is needed in a subsequent phase).
-Examples:
-- **Restart**: If swap usage is high or rogue processes are detected.
-- **Upgrade Plan**: If physical memory is chronically saturated (B1 to P1v3).
-- **Code Optimization**: If log analysis reveals initialization loops or leaks.
-
-## EXAMPLES
-
-### Good Analysis
-> "The profiler shows 98% CPU usage and 'Swap Death'. The logs show 'Ensured unique index' occurring 100 times per minute. I recommend implementing an initialization guard in `PrismaDatabaseService` to break this loop."
-
-### Bad Analysis (Do not do)
-> "I found a loop, so I've updated `server.ts` to fix it." 
-> *Correction: Propose the fix first, do not implement it within the analysis workflow.*
-
-## COMPLETION CHECKLIST
-- [ ] Profiler run successfully on production.
-- [ ] Resource bottlenecks (CPU/Mem/Swap) identified.
-- [ ] Application process stability verified.
-- [ ] Root cause hypothesis formulated based on metrics and logs.
-- [ ] Prioritized recommendations delivered to the user.
+# Performance Analysis Phase
+
+## INTENT
+To diagnose production performance issues (CPU, Memory, Swap) and provide actionable recommendations for stabilization without performing direct application or infrastructure modifications.
+
+## PRINCIPLES
+- **Observational Only**: Do not modify code or infrastructure during this phase.
+- **Data-Driven**: Base all recommendations on metrics collected from the environment.
+- **Non-Invasive**: Use non-destructive commands that do not impact server stability.
+- **Actionable**: Provide clear, prioritized recommendations for remediation.
+
+## ANALYSIS WORKFLOW
+
+### Step 1: Run the Performance Profiler
+Execute the profiling script against the production environment to collect plan-level and process-level metrics.
+
+**Note**: `profile-server.ts` has FRAIM dependencies and requires ephemeral execution.
+
+```bash
+# Get the profile-server script ephemerally (has FRAIM dependencies)
+# Use get_fraim_file({ path: "scripts/performance/profile-server.ts" }) and save to tmp/profile-server.ts
+npx tsx tmp/profile-server.ts --prod
+```
+
+### Step 2: Inspect Automated Diagnosis
+Review the "Step 4: Automated Diagnosis" section of the output. 
+It will specifically check for:
+- **Swap Death**: If >95% swap is used, the server is thrashing.
+- **Absent Application**: If `server.js` is missing, the infrastructure is healthy but the app is crashed/not starting.
+- **Infrastructure Hogs**: If Azure agents (Kudu/dotnet) are consuming excessive RAM.
+
+### Step 3: Deep Dive Log Analysis
+If a crash loop or high operation frequency is suspected, collect and analyze application logs using the same script with the `--logs` flag.
+
+```bash
+# Use the same ephemeral script with logs flag
+npx tsx tmp/profile-server.ts --prod --logs
+```
+Look for:
+- Frequency of initialization logs (e.g., "Ensured unique index").
+- Patterns indicative of OOM events or unhandled exceptions.
+- High volume of specific operations (e.g., decryptions) suggesting an infinite loop.
+
+### Step 4: Formulate Recommendations
+Based on the diagnosis, provide specific recommendations in your response or an implementation plan (if a fix is needed in a subsequent phase).
+Examples:
+- **Restart**: If swap usage is high or rogue processes are detected.
+- **Upgrade Plan**: If physical memory is chronically saturated (B1 to P1v3).
+- **Code Optimization**: If log analysis reveals initialization loops or leaks.
+
+## EXAMPLES
+
+### Good Analysis
+> "The profiler shows 98% CPU usage and 'Swap Death'. The logs show 'Ensured unique index' occurring 100 times per minute. I recommend implementing an initialization guard in `PrismaDatabaseService` to break this loop."
+
+### Bad Analysis (Do not do)
+> "I found a loop, so I've updated `server.ts` to fix it." 
+> *Correction: Propose the fix first, do not implement it within the analysis workflow.*
+
+## COMPLETION CHECKLIST
+- [ ] Profiler run successfully on production.
+- [ ] Resource bottlenecks (CPU/Mem/Swap) identified.
+- [ ] Application process stability verified.
+- [ ] Root cause hypothesis formulated based on metrics and logs.
+- [ ] Prioritized recommendations delivered to the user.

package/registry/workflows/product-building/implement.md

@@ -122,7 +122,11 @@ Before creating PR evidence, verify:
 Before marking work ready for review, run the pre-PR quality gate:
 
 ```bash
-Retrieve and run quality check (retrieve via `get_fraim_file({ path: "scripts/code-quality-check.sh" })`)
+# Execute code quality check script directly from synced location
+~/.fraim/scripts/code-quality-check.sh pre-pr
+
+# On Windows:
+# %USERPROFILE%\.fraim\scripts\code-quality-check.sh pre-pr
 ```
 
 ### Step 6: PR Monitoring
@@ -154,7 +158,7 @@ After submitting/updating PR:
 
 ### Pre-PR Check Results
 ```bash
-Retrieve and run quality check (retrieve via `get_fraim_file({ path: "scripts/code-quality-check.sh" })`)
+~/.fraim/scripts/code-quality-check.sh pre-pr
 ✅ GATE 1: No 'as any' Type Bypassing
 ✅ GATE 2: TypeScript Compilation
 ⚠️ GATE 3: Linter (2 warnings - documented below)

package/registry/workflows/product-building/prep-issue.md

@@ -12,21 +12,12 @@ This workflow prepares the local development environment for working on a specif
 1.  **Execute Preparation Script**:
     Fetch and run cleanup/setup scripts ephemerally.
 
-    ```javascript
-    // 1. Fetch script
-    const script = await get_fraim_file({ path: "scripts/prep-issue.sh" });
+    ```bash
+    # Execute the prep-issue script directly from synced location
+    ~/.fraim/scripts/prep-issue.sh {issue_number}
     
-    // 2. Save to machine temp
-    const os = require('os');
-    const path = require('path');
-    const fs = require('fs');
-    const fraimTmp = path.join(os.homedir(), '.fraim', 'tmp');
-    if (!fs.existsSync(fraimTmp)) fs.mkdirSync(fraimTmp, { recursive: true });
-    const tempPath = path.join(fraimTmp, 'prep-issue.sh');
-    fs.writeFileSync(tempPath, script);
-    
-    // 3. Make executable (if needed) and run
-    await run_command({ command: `bash ${tempPath} ${issueNumber}` });
+    # On Windows:
+    # %USERPROFILE%\.fraim\scripts\prep-issue.sh {issue_number}
     ```
 
 
@@ -40,16 +31,12 @@ This workflow prepares the local development environment for working on a specif
 ## Implementation Detail (Agent Guidance)
 
 Execute:
-```javascript
-const scriptContent = await get_fraim_file({ path: "scripts/prep-issue.sh" });
-const os = require('os');
-const path = require('path');
-const fs = require('fs');
-const fraimTmp = path.join(os.homedir(), '.fraim', 'tmp');
-if (!fs.existsSync(fraimTmp)) fs.mkdirSync(fraimTmp, { recursive: true });
-const tempPath = path.join(fraimTmp, 'prep-issue.sh');
-fs.writeFileSync(tempPath, scriptContent);
-await run_command({ command: `bash ${tempPath} ${issueNumber}` });
+```bash
+# Execute the prep-issue script directly from synced location
+~/.fraim/scripts/prep-issue.sh {issue_number}
+
+# On Windows:
+# %USERPROFILE%\.fraim\scripts\prep-issue.sh {issue_number}
 ```
 
 > [!NOTE]

package/registry/workflows/product-building/resolve.md

@@ -122,7 +122,11 @@ gh issue close <ISSUE_NUMBER> --comment "✅ Issue resolved and merged to master
 
 **Cleanup Branch:**
     ```bash
-    # Retrieve and run cleanup script: `get_fraim_file({ path: "scripts/cleanup-branch.ts" })`
+    # Execute cleanup script directly from synced location
+    npx tsx ~/.fraim/scripts/cleanup-branch.ts {branch_name}
+    
+    # On Windows:
+    # npx tsx %USERPROFILE%\.fraim\scripts\cleanup-branch.ts {branch_name}
     ```
 
 ### 7. Celebrate

package/registry/workflows/replicate/replicate-discovery.md

@@ -0,0 +1,336 @@
+# Replicate Discovery Workflow
+
+## INTENT
+To systematically discover, analyze, and document an existing web application for replication, producing a complete analysis package that can be converted into implementation issues.
+
+## PRINCIPLES
+- **Comprehensive Discovery**: Capture all features, UI patterns, and user workflows
+- **Systematic Analysis**: Follow structured phases from technical scraping to use case extraction
+- **Organized Documentation**: Create well-structured artifacts for downstream workflows
+- **Technology Awareness**: Document the tech stack and architectural patterns
+
+## Overview
+This workflow guides agents through discovering and analyzing an existing web application, producing comprehensive documentation including screenshots, use cases, UI patterns, and technology analysis. The output feeds into the `replicate-to-issues.md` workflow to create GitHub issues for implementation.
+
+## When to Use This Workflow
+
+Use this workflow when:
+- Re-implementing an existing application
+- Migrating an application to a new technology stack
+- Creating a feature-complete replica of an application
+- Documenting an existing application for modernization
+
+## Prerequisites
+- Access to the target website URL
+- Python 3.8 or higher
+- Basic understanding of web technologies (HTML, CSS, JavaScript, React)
+
+### Required Python Packages
+The Python scraping scripts are synced to `~/.fraim/scripts/` during `fraim init` or `fraim sync`.
+
+Install required packages:
+```bash
+pip install playwright beautifulsoup4 requests
+```
+
+For Playwright browser automation, install browser binaries:
+```bash
+playwright install chromium
+```
+
+## Workflow Steps
+
+### Phase 1: Initial Site Scraping
+
+**Objective**: Get a comprehensive understanding of the site structure, pages, and resources.
+
+1. **Create Output Directory Structure**
+   ```
+   docs/replicate/
+   ├── analysis/           # JSON analysis files
+   ├── screenshots/        # Organized screenshots
+   ├── reports/           # Generated documentation
+   └── artifacts/         # Additional artifacts
+   ```
+
+2. **Run Basic Site Scraper**
+   ```bash
+   python ~/.fraim/scripts/scrape-site.py <target_url> --output-dir docs/replicate/analysis [--max-pages N]
+   ```
+   - **Options**:
+     - `target_url`: Base URL of the website to scrape (required)
+     - `--max-pages N`: Maximum number of pages to scrape (default: 50)
+     - `--output-dir`: Output directory for results
+     - `--output-file`: Output filename (default: site_analysis.json)
+   
+   This generates:
+   - `docs/replicate/analysis/site_analysis.json` - Page structure, forms, CSS/JS files, images, links
+
+3. **Review Initial Findings**
+   - Check `site_analysis.json` for:
+     - Total pages discovered
+     - Common navigation patterns
+     - Form structures
+     - Resource dependencies
+     - Technology indicators (React, Vue, Angular, etc.)
+
+### Phase 2: Interactive Browser Analysis
+
+**Objective**: Understand dynamic behavior, user interactions, and SPA patterns.
+
+1. **Run Interactive Explorer**
+   ```bash
+   python ~/.fraim/scripts/interactive-explorer.py <target_url> --output-dir docs/replicate [--headless] [--max-clicks N]
+   ```
+   - **Options**:
+     - `target_url`: Base URL of the website to explore (required)
+     - `--output-dir`: Output directory for results
+     - `--headless`: Run browser in headless mode
+     - `--max-clicks N`: Maximum number of clicks to perform (default: 20)
+   
+   This generates:
+   - `docs/replicate/analysis/interaction_analysis.json` - Pages visited, interactions, use case hints
+   - `docs/replicate/screenshots/` - Screenshots of each state
+
+2. **Run Comprehensive Explorer**
+   ```bash
+   python ~/.fraim/scripts/comprehensive-explorer.py <target_url> --output-dir docs/replicate [--headless]
+   ```
+   
+   This generates:
+   - `docs/replicate/analysis/comprehensive_analysis.json` - Detailed page content, routes, use cases
+   - Additional screenshots in `docs/replicate/screenshots/`
+
+### Phase 3: Screenshot Organization & Visual Analysis
+
+**Objective**: Organize visual assets and identify UI/UX patterns.
+
+1. **Organize Screenshots by Category**
+   Create folder structure within `docs/replicate/screenshots/`:
+   ```
+   screenshots/
+   ├── authentication/
+   ├── navigation/
+   ├── forms/
+   ├── lists/
+   ├── details/
+   └── [feature-specific]/
+   ```
+
+2. **Identify UI Component Patterns**
+   Document in `docs/replicate/reports/component-catalog.md`:
+   - Navigation components (header, sidebar, footer)
+   - Form components (inputs, buttons, validation)
+   - Card/List components
+   - Modal/Dialog patterns
+   - Button styles and states
+   - Input styles and variations
+
+3. **Analyze Layout Patterns**
+   Document in `docs/replicate/reports/layout-patterns.md`:
+   - Page layout structures
+   - Responsive design patterns
+   - Grid systems
+   - Spacing and typography
+   - Color palette
+   - Visual hierarchy
+
+4. **Create Screenshot Index**
+   Generate `docs/replicate/reports/screenshot-index.md`:
+   - Filename and path
+   - Page/Route
+   - Description
+   - Related use case
+   - Key UI elements visible
+
+### Phase 4: Technology Stack Analysis
+
+**Objective**: Identify and document the technology stack and architectural patterns.
+
+1. **Analyze Technology Indicators**
+   From analysis JSON files, identify:
+   - **Frontend Framework**: React, Vue, Angular, vanilla JS
+   - **Build Tools**: Webpack, Vite, Parcel
+   - **CSS Framework**: Bootstrap, Tailwind, Material-UI, custom
+   - **State Management**: Redux, MobX, Context API
+   - **Routing**: React Router, Vue Router, etc.
+   - **API Patterns**: REST, GraphQL, WebSocket
+
+2. **Document Architecture Patterns**
+   Create `docs/replicate/reports/technology-stack.md`:
+   - Identified technologies
+   - Architectural patterns (SPA, MPA, SSR)
+   - Component structure
+   - Data flow patterns
+   - Authentication approach
+   - API integration patterns
+
+3. **Infer Data Models**
+   From forms and content, document in `docs/replicate/reports/data-models.md`:
+   - Entity types (User, Event, Organization, etc.)
+   - Field structures
+   - Relationships
+   - Validation rules
+
+### Phase 5: Use Case Extraction
+
+**Objective**: Systematically identify and document all user workflows.
+
+1. **Identify User Roles**
+   From analysis data, identify:
+   - Guest/Anonymous users
+   - Authenticated users
+   - Admin/Moderator roles
+   - Organization/Group roles
+   - Special roles (Volunteer, Member, etc.)
+
+2. **Extract Use Cases from Data**
+   Review all analysis files and:
+   - Map user journeys through the application
+   - Identify user actions (buttons, forms, links)
+   - Group related actions into use cases
+   - Document workflows and flows
+
+3. **Organize Use Cases by Category**
+   Common categories:
+   - **Authentication & Account Management**
+   - **Content Discovery & Browsing**
+   - **Content Creation & Management**
+   - **Search & Filtering**
+   - **Data Collection & Reporting**
+   - **Administration & Configuration**
+   - **Communication & Collaboration**
+
+4. **Document Each Use Case**
+   Create `docs/replicate/reports/use-cases.md` with structure:
+   ```markdown
+   ## Use Case: [Name]
+   
+   **ID**: UC-[number]
+   **Actor**: [Who performs this]
+   **Category**: [Category name]
+   **Priority**: High/Medium/Low
+   
+   **Preconditions**: 
+   - [What must be true before]
+   
+   **Steps**:
+   1. [Step description]
+   2. [Step description]
+   3. [Step description]
+   
+   **Postconditions**: 
+   - [Expected outcomes]
+   
+   **Screenshots**: 
+   - `screenshots/[category]/[filename].png`
+   
+   **Technical Notes**:
+   - [API endpoints, data models, etc.]
+   
+   **Acceptance Criteria**:
+   - [ ] [Testable criterion]
+   - [ ] [Testable criterion]
+   ```
+
+5. **Validate Completeness**
+   - Every page has associated use cases
+   - Every form has documented workflow
+   - All navigation paths are covered
+   - All user roles are represented
+   - Edge cases and error scenarios documented
+
+### Phase 6: Create Master Report
+
+**Objective**: Consolidate all findings into a comprehensive report.
+
+1. **Generate Master Report**
+   Create `docs/replicate/REPLICATION_ANALYSIS.md`:
+   - **Executive Summary**: High-level overview
+   - **Technology Stack**: Identified technologies
+   - **User Roles**: All identified roles
+   - **Use Case Summary**: Count by category and priority
+   - **Component Inventory**: UI components identified
+   - **Data Models**: Inferred data structures
+   - **Implementation Recommendations**: Suggested approach
+   - **Next Steps**: Link to replicate-to-issues workflow
+
+2. **Create Quick Reference Index**
+   Generate `docs/replicate/INDEX.md`:
+   - Links to all reports
+   - Use case index with IDs
+   - Screenshot index
+   - Technology summary
+   - Statistics (page count, use case count, etc.)
+
+## Output Artifacts
+
+After completing this workflow, you should have in `docs/replicate/`:
+
+### Analysis Data (`analysis/`)
+- `site_analysis.json` - Basic site structure
+- `interaction_analysis.json` - Interactive behavior
+- `comprehensive_analysis.json` - Deep content analysis
+
+### Screenshots (`screenshots/`)
+- Organized by category/feature
+- Named descriptively
+- Cover all pages and key interactions
+
+### Reports (`reports/`)
+- `use-cases.md` - Complete use case documentation
+- `component-catalog.md` - UI component inventory
+- `layout-patterns.md` - Layout and design patterns
+- `technology-stack.md` - Technology analysis
+- `data-models.md` - Inferred data structures
+- `screenshot-index.md` - Screenshot reference
+
+### Master Documents
+- `REPLICATION_ANALYSIS.md` - Comprehensive master report
+- `INDEX.md` - Quick reference index
+
+## Best Practices
+
+1. **Be Thorough**: Don't skip pages or features
+2. **Document Everything**: Better to have too much information
+3. **Validate Manually**: Review automated findings manually
+4. **Organize Early**: Keep structure clean from the start
+5. **Iterate**: Run scripts multiple times as you discover new routes
+6. **Be Respectful**: Include delays between requests, respect robots.txt
+7. **Start Small**: Use limits on initial runs, expand as needed
+
+## Common Challenges
+
+1. **SPA Routing**: React/SPA apps may not expose all routes in HTML
+   - **Solution**: Use browser navigation to discover routes
+
+2. **Authentication**: Some pages require login
+   - **Solution**: Document login flows, consider authenticated scraping
+
+3. **Dynamic Content**: Content loaded via JavaScript
+   - **Solution**: Use browser automation (Playwright)
+
+4. **Rate Limiting**: Too many requests too fast
+   - **Solution**: Scripts include delays, adjust as needed
+
+## Troubleshooting
+
+### Browser Installation Issues
+```bash
+playwright install chromium --force
+```
+
+### Import Errors
+```bash
+pip install --upgrade playwright beautifulsoup4 requests
+```
+
+### Network Timeouts
+- Check internet connection
+- Verify target URL is accessible
+- Increase timeout values in scripts
+
+## Next Steps
+
+After completing this workflow, get user feedback and once in agreement, suggest that the user proceed to:
+- **Replicate to Issues** workflow (`workflows/replicate/replicate-to-issues.md`)