fraim-framework 2.0.56 → 2.0.58

package/dist/registry/workflows/product-building/spec.md

@@ -1,181 +0,0 @@
-# Workflow: spec
-
-**Path:** `workflows/spec.md`
-
----
-
-# Specification Phase
-
-## INTENT
-To create comprehensive, detailed product specifications that clarify the Why, What and User Experiences for new features.
-
-## PRINCIPLES
-- **Success Criteria**: Optimize for Integrity, Correctness, Completeness, Independence, and Speed - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- **Start with the User**: Understand the user's needs and experiences before implementing
-- **User Experience Matters**: Focus on creating a great user experience right from the beginning
-- **Validation Criteria**: Define clear validation criteria to ensure the feature meets user needs
-- **Simplicity**: Maintain simplicity in feature definition (read `rules/simplicity.md` via `get_fraim_file`)
-
-## SPECIFICATION WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {slug}). Get slug details using GitHub MCP.
-
-**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)
-
-### Step 2: Phase Initiation
-Label the issue 'phase:spec' (GitHub Action will automatically create a draft PR if none exists, or update the existing PR with phase-specific details, and label the issue `status:wip`)
-
-### Step 3: Environment Setup
-**IMPORTANT**: The user has already run `prep-issue.sh` which has:
-- ✅ Created the feature branch
-- ✅ Checked out the branch
-- ✅ Pushed the empty branch to origin
-- ✅ 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 specification document, agents MUST:
-
-1. **Verify Template Selection**:
-   - Use Feature Spec template: `get_fraim_file({ path: "templates/specs/FEATURESPEC-TEMPLATE.md" })`
-
-2. **Complete Competitive Analysis**:
-   - Proceed to competitor-analysis phase after spec creation
-   - Research configured competitors from .fraim/config.json
-   - Discover additional competitors through web research
-   - Update configuration with user-approved new competitors
-   - Develop competitive positioning strategy
-
-3. **Mandatory Retrospective**:
-   - After PR approval, complete retrospective phase before resolve
-   - Capture learnings while spec context is fresh
-   - Analyze PR feedback and incorporate lessons learned
-   
-2. **Validate Naming Convention**:
-   - Format: `docs/feature specs/{issue_number}-{kebab-title}.md`
-   - Example: `docs/feature specs/228-improve-token-refresh.md`
-   - NO other naming patterns allowed
-
-3. **Template Compliance Check**:
-   - Read and understand the template first
-   
-### Step 6: Specification Document Creation
-
-#### Core Principle: Focus on WHAT and WHY, Not HOW
-**Feature specifications describe the desired outcome and user experience, NOT technical implementation details.**
-
-#### Compliance Requirements Integration
-Before creating the specification, check for compliance requirements:
-
-1. **Read Project Configuration**:
-   - Read `.fraim/config.json` to check for compliance settings
-   - Look for `compliance.regulations` array and `compliance.compliance_specifications`
-   - Check `project.industry` for industry-specific requirements
-
-2. **Include Compliance Section** (if applicable):
-   - If `compliance.regulations` contains any entries, add a compliance section to your spec
-   - For each regulation, reference the corresponding `compliance_specifications` entry
-   - Tell agents to "ensure implementation abides by requirements specified in [pointer]"
-
-Example compliance section:
-```markdown
-## Compliance Requirements
-
-Based on project configuration, this feature must comply with:
-
-### FinRA Requirements
-Detailed list of FinRA requirements that apply
-
-### WCAG 2.1 AA Standards  
-Detailed list of WCAG requirements that apply
-```
-
-#### Include:
-- **High-Fidelity Mocks**: All UI changes must include clickable or high-fidelity HTML/CSS mocks. Markdown code blocks are NOT sufficient for UI specifications.
-- Clear user stories and acceptance criteria.
-- Edge cases and error states.
-- **Compliance Requirements**: If regulations are configured, include compliance section with references to specification documents.
-
-#### Exclude:
-- **Markdown Mocks**: Do NOT use markdown code blocks (e.g. ` ```html `) to mock UI. Use real HTML/CSS files or screenshots.
-- Technical implementation details.
-- Database schema changes (these belong in the Design Phase).
-
-### Step 7: Specification Creation Checklist
-Before committing your work, verify:
-- [ ] Correct template used (`FEATURESPEC-TEMPLATE.md`)
-- [ ] Proper file naming: `docs/feature specs/{issue_number}-{kebab-title}.md`
-- [ ] High-Fidelity mocks included (if UI changes)
-- [ ] No Markdown mocks used for UI
-- [ ] All template sections completed
-- [ ] No placeholder text remaining
-- [ ] Issue labeled `phase:spec`
-- [ ] Working in correct branch
-
-### Step 8: AI Coach Phase System
-This workflow uses the AI Coach phase system for guidance and validation. Start the phase system:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "spec",
-  issueNumber: "{issue_number}",
-  currentPhase: "spec-spec",
-  status: "starting"
-})
-```
-
-The AI Coach will guide you through:
-1. **Spec Phase**: Create comprehensive specification document
-2. **Spec Completeness Review**: Validate spec quality and HTML mocks
-3. **Submit PR**: Prepare work for review
-4. **Wait for PR Review**: Monitor review status and collect feedback
-
-Follow the AI Coach instructions for each phase and report back when complete.
-
-### Step 9: 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 Spec Evidence template: `get_fraim_file({ path: "templates/evidence/Spec-Evidence.md" })`
-- **Next Step**: Switch to "Iterate on PR Comments" workflow: `get_fraim_file({ path: "workflows/product-building/iterate-on-pr-comments.md" })`
-
-### Step 10: 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 Specification Process
-```
-Issue #84: "Add calendar sync"
-1. ✅ Identified: Issue #84, slug: "add-calendar-sync"
-2. ✅ Phase: Set phase:spec, PR created
-3. ✅ Environment: User ran prep-issue.sh, ready to work
-4. ✅ Location: Working in prepared workspace with Serena indexing
-5. ✅ Spec: Created docs/feature specs/84-add-calendar-sync.md
-6. ✅ Mocks: Included high-fidelity HTML mocks for the sync settings
-7. ✅ Review: Set status:needs-review
-8. ✅ Iteration: Incorporated feedback, updated spec
-Result: Clear, user-focused specification with high-fi mocks
-```
-
-### Bad: Incomplete Specification Process
-```
-Issue #84: "Add calendar sync"
-1. ✅ Identified: Issue #84
-2. ❌ Skip: Didn't set phase:spec
-3. ❌ Skip: Didn't create branch
-4. ❌ Skip: Started coding without spec
-5. ❌ Skip: No spec document created
-6. ❌ Skip: Used simple markdown mocks for complex UI
-Result: Unclear user experience, potential rework
-```

package/dist/registry/workflows/product-building/test.md

@@ -1,125 +0,0 @@
-# Workflow: test
- 
-**Path:** `workflows/test.md`
- 
----
- 
-# 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
-- **Success Criteria**: Optimize for Integrity (Honest reporting), Correctness (Coverage), Completeness, Independence, and Speed - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- **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 Guidelines**: Follow "Agent Testing Guidelines" (read `rules/agent-testing-guidelines.md` via `get_fraim_file`)
-- **Integrity**: Adhere to "Integrity and Test Ethics" (read `rules/integrity-and-test-ethics.md` via `get_fraim_file`)
-- **Architecture**: Follow existing architecture - see `.fraim/config.json` for the path (`customizations.architectureDoc`)
-
-## TESTING WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {slug}); confirm target branch feature/{issue_number}-{slug}.
-
-**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)
-
-### Step 2: Phase Initiation
-Label the issue 'phase:tests'. (GitHub Action will automatically create a draft PR if none exists, or update the existing PR with phase-specific details, and label the issue `status:wip`)
-
-### Step 3: Environment Setup
-**IMPORTANT**: The user has already run `prep-issue.sh` which has:
-- ✅ Created the feature branch
-- ✅ Checked out the branch
-- ✅ Pushed the empty branch to origin
-- ✅ 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 email threading issues, actually send emails and verify they appear as new messages vs replies
-- **Use Case Mapping**: If working with documented use cases, map each use case to test cases:
-  - For each use case, create corresponding test scenarios (happy path, edge cases, error cases)
-  - Organize tests by use case category
-  - Ensure all high-priority use cases have test coverage
-- Run the test cases to ensure they fail (demonstrating the issue exists)
-- Flip issue to 'status:needs-review' and remove 'status:wip'
-
-### Step 5.1: Robustness & Permutation Testing (MANDATORY)
-**You must author tests that specifically target fragility:**
-
-1.  **Regex Resilience**: if using regex, test for:
-    - Case sensitivity (upper/lower/mixed)
-    - Line endings (`\n` vs `\r\n`)
-    - Whitespace variations
-2.  **Negative & Default State Testing**:
-    - Assert that empty inputs fail (do not silently default)
-    - Assert that fallback values (e.g. "No intent defined") trigger failures
-3.  **Boundary Conditions**:
-    - Test inputs that are too short, too long, or malformed
-4.  **Silent Failure Prevention**:
-    - Ensure your tests *assert content coverage*, not just *existence*. (e.g., `assert(content.length > 20)` instead of `assert(content)`)
-
-**❌ 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
-- Verify test fails if product code is removed (No Tautologies)
-- 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 calendar sync timeout"
-1. ✅ Identified: Issue #84, branch feature/84-fix-sync
-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-sync-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 calendar sync 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/dist/registry/workflows/productivity-report/productivity-report.md

@@ -1,263 +0,0 @@
-# Productivity Report Workflow
-
-**Category:** Performance Analysis
-
-## OVERVIEW
-
-This workflow generates comprehensive productivity reports showing development velocity, team collaboration patterns, and project health metrics through analysis of commits, PRs, issues, and comment activity aggregated by day, week, and month. Works with any GitHub repository and automatically detects repository context.
-
-## WHEN TO USE
-
-- **Sprint Reviews**: Analyze team productivity during development cycles
-- **Project Retrospectives**: Understand development patterns and bottlenecks
-- **Performance Tracking**: Monitor long-term development velocity trends
-- **Team Management**: Assess collaboration and code review engagement
-- **Stakeholder Reporting**: Provide data-driven insights on project progress
-
-## Intent
-Generate comprehensive productivity reports showing development velocity, team collaboration patterns, and project health metrics through analysis of commits, PRs, issues, and comment activity.
-
-## Overview
-This workflow guides teams through analyzing repository activity to create detailed productivity reports aggregated by day, week, and month. Works with any GitHub repository and automatically detects repository context.
-
-## Prerequisites
-- GitHub CLI authenticated (`gh auth status`)
-- Repository access and permissions
-- Node.js (v14+) and jq installed
-- Git repository context
-
-## Phases
-
-### Phase 1: Environment Setup
-**Objective**: Prepare environment and validate dependencies
-
-**Actions**:
-1. Verify GitHub CLI authentication
-2. Confirm repository access and permissions
-3. Check required dependencies (Node.js, jq)
-4. Detect repository context automatically
-
-**Evidence Required**:
-- GitHub CLI authentication confirmed
-- Repository owner/name detected
-- All dependencies available
-
-### Phase 2: Data Collection
-**Objective**: Gather comprehensive repository activity data
-
-**Actions**:
-1. Collect commit timestamps since repository creation
-2. Fetch pull request creation dates and metadata
-3. Gather closed issue timestamps (excluding PRs)
-4. Extract comment data from PRs and reviews
-
-**Evidence Required**:
-- Raw data files in `docs/productivity-report/` directory
-- Commit, PR, issue, and comment data collected
-- Data validation completed
-
-### Phase 3: Data Processing & Analysis
-**Objective**: Process and aggregate collected data
-
-**Actions**:
-1. Aggregate activity by day, week, and month
-2. Calculate comment totals per PR
-3. Filter issues to exclude pull requests
-4. Generate summary statistics
-
-**Evidence Required**:
-- Processed data aggregations
-- Comment totals calculated
-- Issue/PR separation validated
-
-### Phase 4: Report Generation
-**Objective**: Create final productivity report
-
-**Actions**:
-1. Generate CSV with standardized columns
-2. Include multiple time period views
-3. Provide summary statistics
-4. Validate report completeness
-
-**Evidence Required**:
-- Final CSV report: `docs/productivity-report/productivity-report-{timestamp}.csv`
-- All time periods included (day/week/month)
-- Report validation completed
-
-## Success Metrics
-- CSV report generated successfully in `docs/productivity-report/` directory
-- All time periods (day/week/month) included
-- Comment totals are non-zero (validates PR detail fetch)
-- Issues count excludes pull requests
-- Data files cached for reuse
-
-## Output Location
-`docs/productivity-report/productivity-report-{timestamp}.csv`
-
-## Output Format
-
-### CSV Structure
-| Column | Description |
-|--------|-------------|
-| `period_type` | Time aggregation: `day`, `week`, or `month` |
-| `period` | Date (YYYY-MM-DD) or month (YYYY-MM) |
-| `commits` | Number of commits in period |
-| `prs_created` | Pull requests opened in period |
-| `issues_resolved` | Non-PR issues closed in period |
-| `comments_total` | PR + review comments for PRs created in period |
-
-### Sample Output
-```csv
-period_type,period,commits,prs_created,issues_resolved,comments_total
-day,2024-01-15,5,2,1,8
-week,2024-01-14,23,7,4,34
-month,2024-01,156,28,18,187
-```
-
-## Directory Structure
-```
-docs/productivity-report/
-├── productivity-report-2024-02-04-1430.csv
-├── productivity-report-2024-01-15-0900.csv
-└── .gitkeep
-```
-
-The workflow automatically creates the output directory if it doesn't exist.
-
-## Execution Instructions
-
-### Quick Start
-```bash
-# Navigate to your repository root
-cd /path/to/your/repository
-
-# Get the main script via FRAIM
-# This copies the script to ~/.fraim/scripts/productivity/
-@fraim get_fraim_file("scripts/productivity/productivity-report.sh")
-
-# Create output directory
-mkdir -p docs/productivity-report
-
-# Run the complete productivity report
-bash ~/.fraim/scripts/productivity/productivity-report.sh
-
-# Output will be saved to docs/productivity-report/productivity-report-{timestamp}.csv
-```
-
-The workflow automatically detects repository context and works with any GitHub repository.
-
-### Manual Configuration
-Set environment variables if auto-detection fails:
-```bash
-export REPO_OWNER="your-username"
-export REPO_NAME="your-repository"
-export REPO_FULL="your-username/your-repository"
-```
-
-## Advanced Usage
-
-### Accessing Scripts
-Scripts are available through FRAIM's file system:
-```bash
-# Get all productivity scripts
-@fraim get_fraim_file("scripts/productivity/productivity-report.sh")
-@fraim get_fraim_file("scripts/productivity/fetch-pr-details.mjs")
-@fraim get_fraim_file("scripts/productivity/build-productivity-csv.mjs")
-
-# Ensure output directory exists
-mkdir -p docs/productivity-report
-
-# Run main script
-bash ~/.fraim/scripts/productivity/productivity-report.sh
-```
-
-### Partial Execution
-For large repositories or debugging:
-
-```bash
-# 1. Collect commits only
-gh api "repos/$REPO/commits?per_page=100" --paginate --jq '.[].commit.author.date' > .productivity-data/commits.txt
-
-# 2. Collect PR list
-gh api "repos/$REPO/pulls?state=all&per_page=100" --paginate --jq '.[] | {number, created_at}' > .productivity-data/prs_list_raw.json
-
-# 3. Collect closed issues
-gh api "repos/$REPO/issues?state=closed&per_page=100" --paginate --jq '.[] | select(.pull_request == null) | .closed_at' > .productivity-data/issues_closed.txt
-
-# 4. Fetch PR details (time-intensive)
-node ~/.fraim/scripts/productivity/fetch-pr-details.mjs
-
-# 5. Generate final CSV
-node ~/.fraim/scripts/productivity/build-productivity-csv.mjs
-```
-
-### Data Caching
-- Intermediate data stored in `.productivity-data/`
-- Enables resumable execution for large repositories
-- Automatically added to `.gitignore`
-- Can be cleared and regenerated as needed
-
-## Performance Considerations
-
-### Execution Time
-- **Small repos** (< 100 PRs): 30 seconds - 2 minutes
-- **Medium repos** (100-500 PRs): 2-10 minutes
-- **Large repos** (500+ PRs): 10+ minutes
-
-### Optimization Tips
-- PR comment fetching is the main bottleneck (~1.5 sec per PR)
-- Use cached data for repeated runs
-- Consider date range filtering for very large repositories
-- Run during off-peak hours for better API performance
-
-## Troubleshooting
-
-### Authentication Issues
-```bash
-# Check GitHub CLI status
-gh auth status
-
-# Re-authenticate if needed
-gh auth login
-```
-
-### Permission Errors
-```bash
-# Make scripts executable (after obtaining via get_fraim_file)
-chmod +x ~/.fraim/scripts/productivity/productivity-report.sh
-```
-
-### Missing Dependencies
-```bash
-# Install jq (macOS)
-brew install jq
-
-# Install jq (Ubuntu/Debian)
-sudo apt-get install jq
-
-# Verify Node.js
-node --version
-```
-
-### Large Repository Timeouts
-- Use manual execution steps for better control
-- Monitor `.productivity-data/` for partial progress
-- Consider API rate limiting for very active repositories
-
-## Integration with FRAIM Workflows
-- **After `implement`**: Measure development velocity
-- **During `retrospect`**: Analyze team collaboration patterns
-- **Before `spec`**: Understand historical development patterns
-
-## Dependencies
-
-### Required Tools
-- **GitHub CLI (`gh`)**: API access and authentication
-- **Node.js**: JavaScript script execution (v14+)
-- **jq**: JSON processing in shell scripts
-- **Git**: Repository context detection
-
-### Optional Tools
-- **Excel/LibreOffice**: CSV visualization
-- **Python/R**: Advanced data analysis
-- **Tableau/PowerBI**: Dashboard creation