fraim-framework 2.0.65 → 2.0.67

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

@@ -0,0 +1,303 @@
+---
+{
+    "name": "spec",
+    "initialPhase": "spec-spec",
+    "phases": {
+        "spec-spec": { "onSuccess": "spec-competitor-analysis", "onFailure": "spec-spec" },
+        "spec-competitor-analysis": { "onSuccess": "spec-completeness-review", "onFailure": "spec-competitor-analysis" },
+        "spec-completeness-review": { "onSuccess": "submit", "onFailure": "spec-spec" },
+        "submit": { "onSuccess": "address-feedback", "onFailure": "submit" },
+        "address-feedback": { "onSuccess": "retrospective", "onFailure": "spec-spec" },
+        "retrospective": { "onSuccess": null, "onFailure": null }
+    }
+}
+---
+
+# Workflow: spec
+
+# 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 {{get_issue}}.
+
+### Step 2: Phase Initiation
+Label the issue 'phase:spec' using {{update_issue_status}} (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: Start AI Mentor Phase System
+This workflow uses the AI Mentor phase system for guidance and validation. Start the phase system:
+
+```javascript
+seekMentoring({
+  workflowType: "spec",
+  issueNumber: "{issue_number}",
+  currentPhase: "spec-spec",
+  status: "starting"
+})
+```
+
+The AI Mentor 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 Mentor instructions for each phase and report back when complete.
+   
+### Step 6: Specification Document Creation
+
+## Phase: spec-spec
+
+#### 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**:
+   - Compliance settings: {{config.compliance.regulations | "Check if project has specific compliance requirements (SOC2, HIPAA, etc.)"}}
+   - Industry: {{config.project.industry | "Determine if project operates in regulated industry"}}
+
+2. **Include Compliance Section** (if applicable):
+   - If compliance regulations exist, add a compliance section to your spec
+   - For each regulation, reference the corresponding compliance specifications
+   - 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).
+
+## Phase: spec-competitor-analysis
+
+### INTENT
+To conduct systematic competitive research and analysis for the feature being specified, ensuring comprehensive understanding of competitive landscape and clear differentiation strategy.
+
+### OUTCOME
+A comprehensive competitive analysis that:
+- Documents all configured competitors and their approaches
+- Identifies new competitors through systematic research
+- Proposes configuration updates with user approval
+- Defines clear differentiation strategy and competitive positioning
+- Updates the specification with complete competitive landscape analysis
+
+### WORKFLOW
+
+#### Step 1: Load Competitor Configuration
+Competitors: {{config.competitors | "Research and identify competitors in the project's domain and feature space"}}
+
+#### Step 2: Research Configured Competitors
+Competitors: {{config.competitors | "Research and identify competitors in the project's domain and feature space"}}
+
+For each competitor:
+- Research their current solution for this feature area
+- Analyze their strengths and weaknesses in this space
+- Gather customer feedback and reviews
+- Assess market position and pricing approach
+- Document findings in structured format
+
+#### Step 3: Discover Additional Competitors
+- Use web search to find other competitors in the feature space
+- Research market for competitors not in configuration
+- Identify direct, adjacent, and emerging competitors
+- Focus on competitors specifically relevant to this feature
+
+#### Step 4: Competitor Configuration Updates
+- **Identify New Competitors**: Present newly discovered competitors to user
+- **Configuration Proposal**: Suggest adding relevant competitors to `.fraim/config.json`
+- **User Approval**: Ask user to approve additions: "Found new competitor 'X' in space 'Y'. Add to config?"
+- **Auto-Update**: If user approves, automatically update configuration file
+- **Documentation**: Note configuration changes in competitive analysis
+
+#### Step 5: Competitive Analysis
+- Compare competitor approaches to our proposed solution
+- Identify competitive advantages and disadvantages
+- Develop differentiation strategy
+- Plan competitive response strategies
+- Define market positioning approach
+
+#### Step 6: Update Specification
+- Update Competitive Landscape section with findings
+- Ensure all configured competitors are covered
+- Include newly discovered competitors
+- Add competitive positioning strategy
+- Document research sources and methodology
+- Validate analysis completeness
+
+### VALIDATION
+- ✅ All configured competitors analyzed
+- ✅ Additional competitors discovered through research
+- ✅ User consulted on adding new competitors to config
+- ✅ Configuration updated with user-approved competitors
+- ✅ Competitive positioning strategy defined
+- ✅ Differentiation advantages clearly articulated
+- ✅ Research sources documented
+- ✅ Analysis covers both configured and discovered competitors
+- ✅ Specification competitive landscape section updated
+
+### Report Back:
+When this phase is complete, call:
+```javascript
+seekMentoring({
+  workflowType: "spec",
+  issueNumber: "{issue_number}",
+  currentPhase: "spec-competitor-analysis",
+  status: "complete",
+  evidence: {
+    competitorsAnalyzed: ["competitor1", "competitor2"],
+    newCompetitorsFound: ["new-competitor1"],
+    configurationUpdated: true,
+    differentiationStrategy: "summary of strategy",
+    specificationUpdated: true
+  }
+})
+```
+
+## Phase: spec-completeness-review
+
+### INTENT
+To verify that the specification is complete and includes high-fidelity HTML mocks when UI changes are involved.
+
+### OUTCOME
+Confirmation that:
+- Specification document is complete and follows template
+- High-fidelity HTML mocks exist for UI changes (not markdown code blocks)
+- Mocks are accessible and render properly in browser
+- All requirements from original issue are addressed
+
+### WORKFLOW
+
+#### Step 1: Check Specification Completeness
+- Verify spec document exists at `docs/feature specs/{issue_number}-*.md`
+- Confirm all template sections are complete (not placeholder text)
+- Check that customer, desired outcome, and user experience are well-defined
+
+#### Step 2: Validate Mocks (if UI changes)
+**If the feature involves UI changes:**
+- Check that HTML mock files exist in `docs/feature specs/mocks/`
+- Verify mocks are named `{issue_number}-*.html`
+- Confirm mocks are actual HTML files (not markdown code blocks)
+- **Ask agent to open mocks in browser** to verify they render properly
+- Check that mocks show different states/views of the feature
+
+**If no UI changes:**
+- Confirm this is documented in the spec
+- Verify the feature is purely backend/API
+
+#### Step 3: Requirements Coverage
+- Review original GitHub issue requirements
+- Confirm all requirements are addressed in the specification
+- Check that acceptance criteria are covered
+
+### VALIDATION
+
+#### Phase Complete When:
+- ✅ Specification document complete and professional quality
+- ✅ High-fidelity HTML mocks created (if UI changes required)
+- ✅ Agent has opened mocks in browser and confirmed they render
+- ✅ All original issue requirements addressed
+- ✅ Ready for design phase
+
+#### Phase Incomplete If:
+- ❌ Specification incomplete or poor quality
+- ❌ UI changes specified but no HTML mocks provided
+- ❌ Mocks don't render properly in browser
+- ❌ Original requirements not fully addressed
+
+### Report Back:
+```javascript
+seekMentoring({
+  workflowType: "spec",
+  issueNumber: "{issue_number}",
+  currentPhase: "spec-completeness-review", 
+  status: "complete",
+  evidence: {
+    specComplete: true,
+    mockFilesCreated: ["docs/feature specs/mocks/21-view1.html", "21-view2.html"],
+    browserValidated: true,
+    requirementsCovered: true
+  }
+})
+```
+
+## 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
+```
+
+## Phase: submit
+
+{{include:delivery/submit.md}}
+
+## Phase: address-feedback
+
+{{include:delivery/address-feedback.md}}
+
+## Phase: retrospective
+
+{{include:delivery/retrospective.md}}

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

@@ -0,0 +1,125 @@
+# 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}.
+
+### 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
+
+{{include:orchestration/parallelization-guidance.md}}
+
+{{include:testing/test-execution-with-timeout.md}}
+
+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

@@ -0,0 +1,263 @@
+# 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