fraim-framework 2.0.56 → 2.0.58

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

@@ -1,103 +0,0 @@
-# Workflow: design
- 
-**Path:** `workflows/design.md`
- 
----
- 
-# Design Workflow - AI Coach Guided
-
-## INTENT
-To create comprehensive technical design documents using a phase-based approach guided by the AI Coach, ensuring proper architecture, clear requirements, and stakeholder alignment.
-
-## HOW IT WORKS
-This workflow uses a **coaching approach** where you get guidance on what to do next based on your current progress:
-
-- **Starting work**: Get initial phase instructions (usually design-design)
-- **Completed a phase**: Get next phase instructions immediately  
-- **Stuck or incomplete**: Get guidance to continue current phase
-- **Adaptive guidance**: Different instructions based on design complexity
-
-The AI Coach provides phase-specific instructions and handles all the workflow progression for you.
-
-## PHASE PROGRESSION
-
-**Typical Design Flow**: `design-design` → `design-completeness-review` → `submit-pr` → `wait-for-pr-review`
-
-**IMPORTANT**: Always use the exact phase names shown above!
-
-## GETTING COACHING
-
-Use a single tool for all guidance:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "design",
-  issueNumber: "{issue_number}",
-  currentPhase: "design-design", // IMPORTANT: Use "design-design" for starting phase
-  status: "starting", // Use "starting" when beginning work
-  findings: {
-    // Your results/findings from current phase
-    designType: "rfc", // or "bugspec"
-    requirements: "...", // summary of what you learned
-    uncertainties: ["..."] // any unclear aspects
-  }
-})
-```
-
-## PHASE NAMES (IMPORTANT!)
-
-**You MUST use these exact phase names:**
-- **Starting phase**: `design-design` (NOT "design" or "scoping")
-- **Review phase**: `design-completeness-review`
-- **Submit phase**: `submit-pr`
-- **Final phase**: `wait-for-pr-review`
-
-## STATUS VALUES
-
-- **starting**: You're beginning work (get initial design instructions)
-- **complete**: You finished a phase successfully (get next phase instructions)  
-- **incomplete**: You need help with current phase (get guidance to continue)
-
-## EVIDENCE TRACKING
-
-The AI Coach expects evidence of your work:
-- **Design documents**: RFC or BUGSPEC files created
-- **Stakeholder feedback**: Reviews and approvals received
-- **Technical validation**: Architecture compliance verified
-
-## QUICK START
-
-1. **Start the workflow**: Call `seekCoachingOnNextStep` with `status: "starting"`
-2. **Follow phase instructions**: Complete the specific phase you're guided to
-3. **Report completion**: Call `seekCoachingOnNextStep` with `status: "complete"` and evidence
-4. **Get next phase**: Receive instructions for the next phase automatically
-5. **Repeat**: Continue until workflow completion
-
-The AI Coach handles all the complexity - you just focus on executing the current phase!
-
-## EXAMPLE USAGE
-
-**Starting the workflow:**
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "design",
-  issueNumber: "1019",
-  currentPhase: "design-design",
-  status: "starting"
-})
-```
-
-**Completing a phase:**
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "design",
-  issueNumber: "1019", 
-  currentPhase: "design-design",
-  status: "complete",
-  findings: {
-    designType: "rfc",
-    requirements: "Created comprehensive RFC for feature X",
-    rfcPath: "docs/rfcs/1019-feature-x.md"
-  }
-})
-```

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

@@ -1,74 +0,0 @@
-# Workflow: implement
- 
-**Path:** `workflows/implement.md`
- 
----
- 
-# Implementation Workflow - AI Coach Guided
-
-## INTENT
-To implement bug fixes and features using a phase-based approach guided by the AI Coach, ensuring high-quality, tested code that meets requirements.
-
-## HOW IT WORKS
-This workflow uses a **coaching approach** where you get guidance on what to do next based on your current progress:
-
-- **Starting work**: Get initial phase instructions (usually scoping)
-- **Completed a phase**: Get next phase instructions immediately  
-- **Stuck or incomplete**: Get guidance to continue current phase
-- **Adaptive guidance**: Different instructions for bugs vs features
-
-The AI Coach provides phase-specific instructions and handles all the workflow progression for you.
-
-## PHASE PROGRESSION
-
-**Typical Bug Flow**: implement-scoping → implement-repro → implement-code → implement-validate → implement-smoke → implement-regression → implement-completeness-review → submit-pr → wait-for-pr-review → retrospective
-
-**Typical Feature Flow**: implement-scoping → implement-spike → implement-code → implement-validate → implement-smoke → implement-regression → implement-completeness-review → submit-pr → wait-for-pr-review → retrospective
-
-## GETTING COACHING
-
-Use a single tool for all guidance:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "{phase_name}",
-  status: "{starting|complete|incomplete}",
-  findings: {
-    // Your results/findings from current phase
-    issueType: "bug", // or "feature" (for scoping)
-    requirements: "...", // summary of what you learned
-    uncertainties: ["..."] // any unclear aspects
-  }
-})
-```
-
-## STATUS VALUES
-
-- **starting**: You're beginning work (get initial scoping instructions)
-- **complete**: You finished a phase successfully (get next phase instructions)  
-- **incomplete**: You're stuck or need to iterate (get guidance for current phase)
-
-## GETTING STARTED
-
-### Prerequisites
-**IMPORTANT**: Ensure you are aware of the issue you are working on and are on an appropriate feature branch:
-- ✅ Know your issue number and description
-- ✅ Make sure you are working on a feature branch, not main or master
-
-### Start with Scoping
-
-Unless you are already on a future phase, start with scoping:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-scoping",
-  status: "starting"
-})
-```
-
-The AI Coach will provide detailed implement-scoping instructions and guide you through the entire workflow, one phase at a time.
-

package/dist/registry/workflows/product-building/iterate-on-pr-comments.md

@@ -1,70 +0,0 @@
-# Workflow: iterate-on-pr-comments
-
-**Path:** `workflows/iterate-on-pr-comments.md`
-
----
-
-# PR Iteration & Monitoring
-
-## INTENT
-To ensure AI agents autonomously handle the complete PR lifecycle with proper monitoring, feedback handling, and testing, eliminating gaps that require human intervention.
-
-## PRINCIPLES
-- **Complete Autonomy**: Agents should handle the PR workflow without requiring human prompting
-- **Proactive Monitoring**: Continuously check status of actions and PRs
-- **Comprehensive Feedback**: Address all comments before resubmission
-- **Evidence-Based Progress**: Document test results and implementation status
-
-## WORKFLOW
-
-### Step 1: Git Action Monitoring
-After pushing changes:
-1.  **Monitor Actions**: Check GitHub Actions status every 30 seconds.
-2.  **Retry on Failure**: If specific actions fail, analyze logs, debug, fix, and push again.
-3.  **Timeout**: If actions run > 10 mins or fail 3x consecutively, notify user with analysis.
-4.  **Success**: Only when all actions pass, proceed to Step 2.
-
-### Step 2: PR Feedback Polling
-After submission (or update):
-1.  **Poll**: Check for PR comments/reviews every 1 minute.
-2.  **Timeout**: After 24 hours of silence, notify user.
-3.  **Active Feedback**: If feedback arrives, proceed to Step 3 immediately.
-
-### Step 3: Feedback Processing
-1.  **Set Status**: Label issue `status:wip`.
-2.  **Analyze**: Read all comments. Use `get_github_pr_comments` or similar tool.
-3.  **Address**: For each comment:
-    *   Implement code changes or fixes.
-    *   **Reply** to the comment (using `add_comment_to_pending_review` or `add_issue_comment`) explaining the fix.
-4.  **Verify**: Ensure no comments are left unaddressed.
-
-### Step 4: Verification & Evidence
-Before re-submitting:
-1.  **Run Tests**: Execute relevant test suites (Unit + Integration).
-2.  **Document**: Add a comment to the PR/Issue with:
-    *   Test commands run.
-    *   Pass/Fail status.
-    *   Coverage summary.
-3.  **Clean Up**: Remove temp files/logs.
-
-### Step 5: Submission
-1.  **Sync**: Push all changes.
-2.  **Set Status**: specific label `status:needs-review`.
-3.  **Loop**: Return to Step 1 (Monitor Actions).
-
-## FAILURE MODES
-- **Git Action Timeout**: 10 mins / 20 attempts.
-- **Feedback Timeout**: 24 hours.
-- **Network Errors**: Exponential backoff needed.
-
-## EXAMPLES
-
-### Good: Handling Feedback
-```
-1. Detected 3 comments on PR #123.
-2. Comment 1 ("Fix typo"): Fixed in file.ts. Replied "Fixed".
-3. Comment 2 ("Memory leak"): Reproduced, fixed logic. Replied "Fixed with new pattern".
-4. Ran tests: All Pass.
-5. Posted evidence.
-6. Pushed. Labeled status:needs-review.
-```

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

@@ -1,41 +0,0 @@
-# Workflow: Issue Preparation (prep-issue)
-
-This workflow prepares the local development environment for working on a specific GitHub issue.
-
-## Prerequisites
-
-- GitHub Issue Number (e.g., 56)
-- GitHub CLI (gh) installed and authenticated
-
-## Action Items
-
-1.  **Execute Preparation Script**:
-    Fetch and run cleanup/setup scripts ephemerally.
-
-    ```bash
-    # Execute the prep-issue script directly from synced location
-    ~/.fraim/scripts/prep-issue.sh {issue_number}
-    
-    # Note: Windows users should use Git Bash terminal
-    ```
-
-
-3.  **Verify Setup**:
-    - **Clean Context**: Start fresh to avoid pollution
-    - **Environment**: Follow "Local Development" guidelines (read `rules/local-development.md` using `get_fraim_file`).
-    - [ ] Feature branch created and pushed to origin.
-    - [ ] `npm install` completed.
-    - [ ] Serena indexing completed (if applicable).
-
-## Implementation Detail (Agent Guidance)
-
-Execute:
-```bash
-# Execute the prep-issue script directly from synced location
-~/.fraim/scripts/prep-issue.sh {issue_number}
-
-# Note: Windows users should use Git Bash terminal
-```
-
-> [!NOTE]
-> The script will automatically handle branch naming based on the issue title using `gh issue view`.

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

@@ -1,65 +0,0 @@
-# Workflow: prototype
-
-**Path:** `workflows/prototype.md`
-
----
-
-# Prototype / PoC Phase
-
-## INTENT
-To quickly explore ideas, validate technologies, or prove concepts using "spike" code. Speed and learning are prioritized over code quality and tests.
-
-## PRINCIPLES
-- **Speed Over Perfection**: It gets the job done; it doesn't need to be pretty.
-- **Disposable Code**: Assume this code will be thrown away or heavily refactored.
-- **Time-Boxed**: Spikes should have a clear time limit.
-- **Learning Focused**: The goal is to answer a question or prove a capability.
-
-## PROTOTYPE WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {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:prototype'.
-
-### Step 3: Environment Setup
-User runs `prep-issue.sh` (or you do if needed).
-Switch to a `prototype/...` branch if not already on one.
-
-### Step 4: Work Location
-Work in the prepared workspace.
-
-### Step 5: Prototyping
-- **Goal**: Build a working demonstration of the concept.
-- **Constraints**:
-    - **No Tests Required** (unless helpful for you).
-    - **Hardcoding Allowed**: Use hardcoded values to speed up development.
-    - **No Cleanup Required**: Formatting/Linting is optional.
-    - **Focus on the Core**: Ignore edge cases, error handling, and polish.
-
-### Step 6: Demonstration
-- Verify the prototype works for the "Happy Path".
-- Create a screen recording or screenshot of the working prototype.
-- Document what was learned:
-    - Does it work?
-    - What are the risks?
-    - How should we implement the real version?
-    - How should we implement the real version?
-
-### Step 7: Transition
-**Decide the next step:**
-1.  **Discard**: The idea didn't work. Close issue.
-2.  **Spec**: The idea works, but needs a full design. Call `get_fraim_workflow({ workflow: "spec" })`.
-3.  **Implement**: The prototype is good enough to be the base. **YOU MUST CLEAN IT UP.** 
-    - Call `get_fraim_workflow({ workflow: "implement" })`.
-    - **CRITICAL**: You must specifically address the "Cleanup" phase where you refactor the prototype code into production-quality code, add tests, and handle edge cases.
-
-### Step 8: Completion
-- Commit the prototype code (optional, but good for history).
-- Label `status:prototype-done`.

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

@@ -1,168 +0,0 @@
-# Workflow: resolve
- 
-**Path:** `workflows/resolve.md`
- 
----
- 
-# Issue Resolution Workflow
- 
-## INTENT
-To provide a systematic approach to resolving issues from development through merge verification and cleanup, ensuring no work is lost and all changes are properly integrated into the main codebase.
- 
-## PRINCIPLES
-- **Success Criteria**: Optimize for Integrity (Verify truthfully) and Completeness (Clean up fully) - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- **Verification First**: Always verify merges before closing issues
-- **Complete Cleanup**: Remove all traces of feature branches
-- **No Work Loss**: Prevent incidents like Issue #112 through proper verification
-- **Systematic Process**: Follow established steps in order
-- **Evidence-Based**: Provide concrete verification of completion
-- **Git Safety**: Follow "Git Safe Commands" (read `rules/git-safe-commands.md` using `get_fraim_file`)
-
-## CRITICAL DEPENDENCY
-**This workflow MUST be used in conjunction with "Merge Requirements" rule** (read `rules/merge-requirements.md` via `get_fraim_file`) which contains:
-- **Pre-Push Workflow** (for feature branches during development)
-- **PR Description Template** (for PR creation)
-- **Final Merge Process** (for merging to master - used in this workflow)
-- **Conflict Resolution Guide** (for resolving conflicts during rebase)
-
-**Note**: The Pre-Push workflow applies to feature branch development. This resolve.md workflow focuses on the **final merge into master** and uses the Final Merge Process from merge-requirements.md.
-
-## RESOLUTION WORKFLOW
-
-**PREREQUISITE**: This workflow assumes:
-- ✅ All development work is complete
-- ✅ All tests have been run on the feature branch
-- ✅ PR has been created and approved
-- ✅ Feature branch is ready for merge
-
-**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)
-
-### 1. Execute the Merge
-Use GitHub MCP to merge the PR:
-
-```bash
-# Merge the PR using GitHub MCP
-gh pr merge <PR_NUMBER> --rebase
-```
-
-**If conflicts occur during merge:**
-- GitHub will reject the merge with conflict details
-- Use `gh pr view <PR_NUMBER>` to see conflict details
-- Resolve conflicts intelligently using the **Conflict Resolution Guide** from `merge-requirements.md`
-- Keep master's base implementation and add your enhancements on top
-- Test the resolution: Check `.fraim/config.json` for `customizations.validation.smokeTestCommand` and use that, or default to `npm run build && npm run test-smoke test*.ts`
-- Push the resolved changes and retry the merge
-
-### 2. Wait for Master CI Smoke Tests
-After successful merge, monitor the master branch CI:
-- Check GitHub Actions for the master branch
-- Wait for smoke tests to complete successfully
-- **CRITICAL**: Do not proceed until CI passes
-
-### 3. Verify Code Made it to Master
-**MANDATORY**: Confirm the merge was successful:
-```bash
-# Check PR is merged, not just closed
-gh pr view <PR_NUMBER> --json merged
-
-# Verify merge commit in master
-git fetch origin master
-git log origin/master --oneline | grep "PR #<PR_NUMBER>"
-
-# Verify files in master
-git show origin/master:path/to/expected/file
-```
-
-### 4. Handle CI Failures
-**If master CI fails:**
-- Debug the issue immediately
-- Fix the problem in the feature branch
-- Push the fix and re-merge
-- Repeat until CI passes
-- **Do not close the issue until CI passes**
-
-### 5. Confirm all good
-**Only after CI passes successfully:**
-
-**Add Resolution Comment if conflicts with master had to be resolved:**
-- Add a comment to the issue using GitHub MCP:
-```bash
-gh issue comment <ISSUE_NUMBER> --body "✅ Encountered conflicts during merge with master.
-
-**Conflict Resolution Notes:**
-- Resolved conflicts in: [list files with conflicts]
-- Resolution strategy: [explain what was done]
-- Kept master's base implementation and added enhancements on top"
-```
-
-**Verify the following:**
-1. ✅ **PR Status**: PR shows "merged" status, not just "closed"
-2. ✅ **Merge Commit**: Verify merge commit exists in master
-3. ✅ **Files in Master**: Confirm expected files are present in master
-
-### **Verification Commands**
-```bash
-# Check PR is merged, not just closed
-gh pr view <PR_NUMBER> --json merged
-
-# Verify merge commit in master
-git fetch origin master
-git log origin/master --oneline | grep "PR #<PR_NUMBER>"
-
-# Verify files in master
-git show origin/master:path/to/expected/file
-```
-
-**CRITICAL**: Do not close the issue until merge verification passes. This prevents work loss incidents 
-
-### 6. Issue Resolution & Cleanup
-**Close the Issue:**
-- Close the issue with resolution comment using GitHub MCP:
-```bash
-gh issue close <ISSUE_NUMBER> --comment "✅ Issue resolved and merged to master. CI smoke tests passed."
-```
-
-**Cleanup Branch:**
-    ```bash
-    # Execute cleanup script directly from synced location
-    npx tsx ~/.fraim/scripts/cleanup-branch.ts {branch_name}
-    
-    # Note: Windows users should use Git Bash terminal
-    ```
-
-### 7. Celebrate
-- Say Hoorah !
-
-
-## EXAMPLES
-
-### Good: Proper Resolution Process
-```
-Issue #84: "Fix calendar sync timeout"
-PREREQUISITE: ✅ Development complete, tests passed, PR approved
-1. ✅ Merge: Used `gh pr merge <PR_NUMBER> --rebase`
-2. ✅ Conflicts: Resolved conflicts intelligently (kept master's base)
-3. ✅ CI Wait: Waited for master CI smoke tests to pass
-4. ✅ Verification: Confirmed merge commit exists in master
-5. ✅ Schema: Cleaned up database schema BEFORE branch deletion
-6. ✅ Comment: Added resolution comment with conflict resolution notes
-7. ✅ Close: Closed issue with resolution comment using `gh issue close`
-8. ✅ Cleanup: Deleted branch after schema cleanup
-Result: Complete resolution with no work loss
-```
-
-### Bad: Incomplete Resolution
-```
-Issue #84: "Fix calendar sync timeout"
-PREREQUISITE: ✅ Development complete, tests passed, PR approved
-1. ✅ Merge: Used `gh pr merge <PR_NUMBER> --rebase`
-2. ❌ Skip: Didn't wait for master CI smoke tests
-3. ❌ Skip: Didn't verify merge commit exists
-4. ❌ Skip: Didn't clean up schema BEFORE branch deletion
-5. ❌ Skip: Didn't add resolution comment with conflict notes
-6. ❌ Close: Closed issue without CI verification
-Result: Work lost, schema not cleaned up, CI may have failed
-```

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

@@ -1,86 +0,0 @@
-# Retrospective Creation
-
-## INTENT
-To capture learnings and insights from completed issues, enabling continuous improvement and preventing future similar problems through systematic analysis and documentation.
-
-## PRINCIPLES
-- **Success Criteria**: Focus on Integrity (Self-reflection) and Independence (Learning from mistakes) - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- Every completed issue requires a retrospective
-- Focus on root causes, not just symptoms
-- Document both successes and failures
-- Create actionable prevention measures
-- Share learnings with other agents
-- Continuous Learning: Follow "Continuous Learning" principles (read `rules/continuous-learning.md` via `get_fraim_file`)
-
-## WORKFLOW
-
-1. **Label the issue** `status:wip` and remove `status:complete`
-2. **Create retrospective document** using the template
-3. **Complete retrospective** following the quality checklist
-4. **When ready for review**, flip issue to `status:needs-review` and remove `status:wip`
-5. **Iterate** until the PR is approved
-
-## RETROSPECTIVE TRIGGERS
-
-- **All Issues**: Every completed issue requires a retrospective
-- **Complex Issues (>3 iterations)**: Must create detailed retrospective
-- **Process Violations**: Any workflow rule violations require detailed retrospectives
-- **Work Loss Incidents**: Any incidents where work is lost require detailed retrospectives
-
-## RETROSPECTIVE CREATION PROCESS
-
-### 1. Create Retrospective File
-- **File path**: `retrospectives/issue-{issue-number}-{kebab-title}-postmortem.md`
-- **Template**: Use Retrospective template: `get_fraim_file({ path: "templates/retrospective/RETROSPECTIVE-TEMPLATE.md" })`
-- **Copy template**: Copy the template file and fill in the placeholders
-
-### 2. Root Cause Analysis
-- Identify underlying causes, not just symptoms
-- Document what went wrong and why
-- Analyze process failures and human errors
-- Look for patterns that could affect other issues
-
-### 3. Prevention Measures
-- Document specific actions to prevent recurrence
-- Update rules and workflows based on learnings
-- Share solutions with other agents through issue comments
-- Identify process improvements
-
-### 4. Document Success Factors
-- What worked well and why
-- Best practices discovered
-- Tools and techniques that helped
-- Lessons that can be applied to future issues
-
-## RETROSPECTIVE QUALITY CHECKLIST
-
-Before marking retrospective complete, verify:
-- [ ] Root cause analysis completed (not just symptoms)
-- [ ] Prevention measures documented
-- [ ] Process improvements identified
-- [ ] Success factors captured
-- [ ] Action items are specific and actionable
-- [ ] Template followed completely
-- [ ] File saved in correct location
-- [ ] All placeholders replaced with actual content
-- [ ] Timeline of events is accurate and complete
-- [ ] Lessons learned are actionable
-
-## EXAMPLES
-
-### Good: Comprehensive Retrospective
-```
-- Root cause: "Agent didn't verify workspace directory before file operations"
-- Prevention: "Added mandatory pwd check before any file operation"
-- Learning: "Workspace violations are common without explicit safeguards"
-- Git Issues Suggested: "Update local-development.mdc with verification checklist"
-```
-
-### Bad: Surface-Level Retrospective
-```
-- Problem: "File created in wrong location"
-- Solution: "Moved file to correct location"
-- Learning: "Need to be more careful"
-```
-
-**CRITICAL**: Do not close the issue until retrospective is created, reviewed, and approved.