fraim-framework 2.0.56 → 2.0.58

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

@@ -1,336 +0,0 @@
-# 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`)

package/dist/registry/workflows/replicate/replicate-to-issues.md

@@ -1,324 +0,0 @@
-# Replicate to Issues Workflow
-
-## INTENT
-To convert comprehensive replication analysis into actionable GitHub issues that can be implemented through standard FRAIM workflows (spec → design → implement → test).
-
-## PRINCIPLES
-- **One Issue Per Feature**: Each use case becomes a focused, implementable issue
-- **Complete Context**: Include all relevant screenshots, requirements, and technical notes
-- **Proper Prioritization**: Use priority from discovery analysis
-- **Clear Acceptance Criteria**: Make issues testable and verifiable
-- **Linked Dependencies**: Connect related issues appropriately
-
-## Overview
-This workflow guides agents through converting the outputs from `replicate-discovery.md` into well-structured GitHub issues. Each issue represents a feature or use case that can be implemented through the standard FRAIM spec/design/implement/test workflow.
-
-## Prerequisites
-- Completed Replicate Discovery workflow (`workflows/replicate/replicate-discovery.md`)
-- Access to `docs/replicate/` directory with all analysis artifacts
-- GitHub repository access with issue creation permissions
-- Understanding of the target implementation repository
-
-**GitHub Repository Context**: Before using GitHub MCP tools, read the local `.fraim/config.json` file to get the repository context:
-- Use `git.repoOwner` for the GitHub repository owner
-- Use `git.repoName` for the GitHub repository name
-- These values are required for GitHub MCP API calls (owner/repo parameters)
-
-## Workflow Steps
-
-### Phase 1: Prepare Issue Generation
-
-1. **Review Discovery Artifacts**
-   - Read `docs/replicate/REPLICATION_ANALYSIS.md`
-   - Review `docs/replicate/reports/use-cases.md`
-   - Check `docs/replicate/reports/technology-stack.md`
-   - Verify all screenshots are accessible
-
-2. **Define Issue Structure**
-   Each issue should include:
-   - **Title**: Clear, concise feature name
-   - **Description**: What needs to be built
-   - **User Story**: As a [role], I want [feature] so that [benefit]
-   - **Use Case Reference**: Link to use case in discovery docs
-   - **Screenshots**: Embedded or linked screenshots
-   - **Technical Requirements**: Technology, components, APIs needed
-   - **Acceptance Criteria**: Testable conditions for completion
-   - **Priority**: High/Medium/Low from discovery
-   - **Labels**: Feature type, priority, component area
-   - **Dependencies**: Links to related issues
-
-3. **Create Issue Template**
-   ```markdown
-   ## User Story
-   As a [role], I want [feature] so that [benefit].
-   
-   ## Description
-   [Detailed description of the feature]
-   
-   ## Use Case Reference
-   See: `docs/replicate/reports/use-cases.md` - UC-[number]
-   
-   ## Screenshots
-   ![Screenshot](<path-to-screenshot>)
-   
-   ## Technical Requirements
-   - **Components**: [List of UI components needed]
-   - **Data Models**: [Entities and fields]
-   - **API Endpoints**: [Required endpoints]
-   - **Dependencies**: [External libraries or services]
-   
-   ## Acceptance Criteria
-   - [ ] [Testable criterion 1]
-   - [ ] [Testable criterion 2]
-   - [ ] [Testable criterion 3]
-   
-   ## Implementation Notes
-   [Any additional technical notes or considerations]
-   
-   ## Related Issues
-   - Depends on: #[issue-number]
-   - Related to: #[issue-number]
-   ```
-
-### Phase 2: Categorize and Prioritize
-
-1. **Group Use Cases by Implementation Order**
-   Typical order:
-   1. **Foundation** (Priority: High)
-      - Project setup and configuration
-      - Database schema and models
-      - Authentication system
-      - Basic routing and navigation
-   
-   2. **Core Features** (Priority: High)
-      - Primary user workflows
-      - Essential CRUD operations
-      - Main user interfaces
-   
-   3. **Secondary Features** (Priority: Medium)
-      - Supporting functionality
-      - Additional user workflows
-      - Enhanced features
-   
-   4. **Polish & Enhancement** (Priority: Low)
-      - UI/UX improvements
-      - Edge cases
-      - Nice-to-have features
-
-2. **Identify Dependencies**
-   - Authentication must come before protected features
-   - Data models before features that use them
-   - Shared components before pages that use them
-   - API endpoints before frontend features
-
-3. **Create Implementation Roadmap**
-   Document in `docs/replicate/IMPLEMENTATION_ROADMAP.md`:
-   - Phase 1: Foundation (issues #1-10)
-   - Phase 2: Core Features (issues #11-30)
-   - Phase 3: Secondary Features (issues #31-50)
-   - Phase 4: Polish (issues #51+)
-
-### Phase 3: Generate GitHub Issues
-
-1. **Create Foundation Issues**
-   Generate issues for:
-   - Project setup and tooling
-   - Database schema design
-   - Authentication system
-   - Base layout and navigation
-   - Shared component library
-
-2. **Create Feature Issues**
-   For each use case in `docs/replicate/reports/use-cases.md`:
-   - Extract use case details
-   - Format as GitHub issue
-   - Include relevant screenshots
-   - Add technical requirements
-   - Set priority and labels
-   - Note dependencies
-
-3. **Use GitHub API or CLI**
-   ```bash
-   # Using GitHub CLI
-   gh issue create \
-     --title "Implement User Registration" \
-     --body-file issue-template.md \
-     --label "feature,high-priority,authentication" \
-     --assignee @me
-   ```
-
-4. **Batch Issue Creation**
-   Create a script or use MCP GitHub tools:
-   - Read use cases from `docs/replicate/reports/use-cases.md`
-   - Generate issue body for each
-   - Create issues via API
-   - Track created issue numbers
-   - Update dependency links
-
-### Phase 4: Link and Organize
-
-1. **Update Issue Dependencies**
-   - After all issues created, update with dependency links
-   - Use "Depends on #X" or "Blocked by #X"
-   - Link related issues with "Related to #X"
-
-2. **Create GitHub Milestones**
-   - Foundation Milestone
-   - Core Features Milestone
-   - Secondary Features Milestone
-   - Polish & Launch Milestone
-
-3. **Assign Issues to Milestones**
-   - Group issues by implementation phase
-   - Set milestone due dates if applicable
-
-4. **Create Project Board** (Optional)
-   - Columns: Backlog, Spec, Design, Implementation, Testing, Done
-   - Add all issues to board
-   - Organize by priority and dependencies
-
-### Phase 5: Documentation
-
-1. **Create Issue Index**
-   Generate `docs/replicate/GITHUB_ISSUES.md`:
-   ```markdown
-   # GitHub Issues Index
-   
-   ## Foundation Issues
-   - #1: Project Setup and Configuration
-   - #2: Database Schema Design
-   - #3: Authentication System
-   
-   ## Core Features
-   - #10: User Registration
-   - #11: User Login
-   - #12: Event Listing
-   
-   [etc.]
-   ```
-
-2. **Update Master Report**
-   Add to `docs/replicate/REPLICATION_ANALYSIS.md`:
-   - Link to GitHub issues
-   - Implementation roadmap
-   - Next steps for development
-
-3. **Create Developer Guide**
-   Generate `docs/replicate/DEVELOPER_GUIDE.md`:
-   - How to pick up an issue
-   - Workflow: spec → design → implement → test
-   - Where to find reference materials
-   - How to use discovery artifacts
-
-## Output Artifacts
-
-After completing this workflow, you should have:
-
-1. **GitHub Issues**
-   - One issue per feature/use case
-   - Properly labeled and prioritized
-   - With dependencies linked
-   - Assigned to milestones
-
-2. **Documentation**
-   - `docs/replicate/IMPLEMENTATION_ROADMAP.md` - Phased implementation plan
-   - `docs/replicate/GITHUB_ISSUES.md` - Index of all created issues
-   - `docs/replicate/DEVELOPER_GUIDE.md` - How to work with issues
-
-3. **Project Organization**
-   - GitHub milestones created
-   - Project board set up (optional)
-   - Issues organized and ready for work
-
-## Issue Labeling Strategy
-
-Use consistent labels:
-- **Type**: `feature`, `bug`, `enhancement`, `documentation`
-- **Priority**: `high-priority`, `medium-priority`, `low-priority`
-- **Component**: `authentication`, `ui`, `api`, `database`, `navigation`
-- **Status**: `needs-spec`, `needs-design`, `ready-for-implementation`, `blocked`
-- **Phase**: `foundation`, `core`, `secondary`, `polish`
-
-## Best Practices
-
-1. **Keep Issues Focused**: One feature per issue, not too broad
-2. **Include Context**: Link to discovery docs and screenshots
-3. **Clear Acceptance Criteria**: Make it obvious when done
-4. **Realistic Scope**: Issues should be completable in reasonable time
-5. **Update Dependencies**: Keep dependency links current
-6. **Use Templates**: Consistent issue format helps clarity
-
-## Common Patterns
-
-### Foundation Issue Example
-```markdown
-Title: Set Up Database Schema for User Management
-
-## User Story
-As a developer, I want a well-designed database schema so that I can implement user-related features.
-
-## Description
-Design and implement the database schema for user management based on the discovery analysis.
-
-## Technical Requirements
-- User table with fields: id, email, password_hash, name, created_at, updated_at
-- Profile table with additional user information
-- Proper indexes and constraints
-- Migration scripts
-
-## Acceptance Criteria
-- [ ] Database schema designed and documented
-- [ ] Migration scripts created
-- [ ] Schema matches requirements from discovery
-- [ ] Indexes added for performance
-- [ ] Foreign keys and constraints properly set
-
-## Related Issues
-- Blocks: #10 (User Registration)
-- Blocks: #11 (User Login)
-```
-
-### Feature Issue Example
-```markdown
-Title: Implement Event Listing Page
-
-## User Story
-As a user, I want to see a list of upcoming events so that I can find events to attend.
-
-## Description
-Implement the event listing page showing all upcoming events with filtering and search capabilities.
-
-## Use Case Reference
-See: `docs/replicate/reports/use-cases.md` - UC-15
-
-## Screenshots
-![Event List](docs/replicate/screenshots/events/event-list.png)
-
-## Technical Requirements
-- **Components**: EventCard, EventList, FilterBar, SearchBox
-- **Data Models**: Event (id, title, date, location, description)
-- **API Endpoints**: GET /api/events?filter=upcoming&search=query
-- **Dependencies**: React, date-fns for date formatting
-
-## Acceptance Criteria
-- [ ] Event list displays all upcoming events
-- [ ] Events can be filtered by date, location, category
-- [ ] Search functionality works
-- [ ] Pagination implemented (20 events per page)
-- [ ] Responsive design matches screenshots
-- [ ] Loading and error states handled
-
-## Implementation Notes
-- Use infinite scroll or pagination
-- Cache event data for performance
-- Consider using React Query for data fetching
-
-## Related Issues
-- Depends on: #5 (Event Data Model)
-- Depends on: #8 (Event API Endpoints)
-- Related to: #16 (Event Detail Page)
-```
-
-## Next Steps
-
-After completing this workflow, let the user verify and once in agreement, recommend that the product-building workflows be started with prep-issue, spec, design, implement phases