fraim-framework 2.0.56 → 2.0.58

package/dist/registry/ai-manager-rules/shared-phases/submit-pr.md

@@ -1,202 +0,0 @@
-# Phase: submit-pr
-
-## INTENT
-To submit completed work for review by creating/updating PR, setting proper labels, and documenting evidence.
-
-## OUTCOME
-Work is submitted for review with:
-- PR created/updated with work
-- Proper issue labels applied
-- Evidence documented
-- Ready to enter PR review phase
-
-## PRINCIPLES
-- **Complete Documentation**: Evidence shows all work done
-- **Proper Labels**: Issue status reflects PR submission
-- **Clear Communication**: PR and evidence are clear
-- **Ready for Review**: No blockers for PR review process
-
-## RULES FOR THIS PHASE
-
-### Success Criteria
-Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus on:
-- **Integrity** (honest documentation of all work completed)
-- **Completeness** (all finalization steps completed)
-
-### Simplicity Principles
-Read `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Key for finalization:
-- **Focus on the assigned issue only** - document only relevant work
-- **Clear communication** - evidence should be easy to understand
-
-### Git Operations (if needed)
-When using git commands directly (if MCP tools unavailable), read `rules/git-safe-commands.md` via `get_fraim_file` to avoid interactive commands that hang agents.
-
-## WORKFLOW
-
-### Step 1: Create Evidence Document
-
-**File location:**
-```
-docs/evidence/{issue_number}-{workflow_type}-evidence.md
-```
-
-**Evidence document should include:**
-
-#### Summary
-- Issue number and title
-- Workflow type (spec, design, implement, test)
-- Brief description of work completed
-
-#### Work Completed
-**For Spec Workflow:**
-- Specification document created
-- High-fidelity HTML mocks (if UI changes)
-- Requirements coverage
-
-**For Design Workflow:**
-- Technical design document
-- Architecture decisions
-- API specifications
-- Database schema (if applicable)
-
-**For Implement Workflow:**
-- Implementation details
-- Key files changed
-- Approach taken
-- Testing completed
-
-**For Test Workflow:**
-- Test suite created/enhanced
-- Coverage metrics
-- Test results
-
-#### PR Feedback History (if applicable)
-**CRITICAL**: If PR feedback file exists (`docs/evidence/{issue_number}-{workflow_type}-feedback.md`), include its complete contents in the evidence document under this section.
-
-This shows reviewers:
-- All previous feedback received
-- How each item was addressed
-- Complete audit trail of review iterations
-
-#### Validation
-- How work was validated
-- Validation results
-- Screenshots/output (if applicable)
-
-#### Quality Checks
-- All deliverables complete
-- Documentation clear and professional
-- Work ready for next phase or review
-
-#### Phase Completion
-- All phases completed for this workflow
-- Evidence from each phase
-- Any iterations or challenges
-
-### Step 2: Commit and Sync Work
-
-**Commit all changes:**
-- Stage all modified files
-- Create commit with descriptive message
-- Push to feature branch
-
-**Commit message format:**
-```
-{workflow_type}({issue_number}): complete {phase_name} phase
-
-- Evidence document created
-- All deliverables complete
-- Ready for review
-```
-
-### Step 3: Verify PR Exists
-
-**Verify PR:**
-- PR exists for the feature branch
-- PR title reflects the issue and workflow
-- PR description includes context and links to deliverables
-
-**If PR doesn't exist:**
-- Create PR manually
-- Link to issue
-- Add evidence document link
-
-### Step 4: Add PR Comment
-
-Add comment to PR with link to evidence:
-```
-{Workflow_type} workflow complete. Evidence document: docs/evidence/{issue_number}-{workflow_type}-evidence.md
-
-All phases completed:
-{workflow_specific_phases_checklist}
-
-**PR Feedback History**: 
-{If feedback file exists, include: "This submission addresses all feedback from previous review rounds. See evidence document for complete feedback history and resolutions."}
-
-Ready for human review.
-```
-
-### Step 5: Update Issue Labels
-
-**Remove:**
-- `status:wip`
-
-**Add:**
-- `status:needs-review`
-
-**Keep:**
-- Current phase label (e.g., `phase:spec`, `phase:design`, `phase:impl`) to indicate which phase is in PR
-
-**GitHub Repository Context:**
-Read `.fraim/config.json` for:
-- `git.repoOwner` - GitHub repository owner
-- `git.repoName` - GitHub repository name
-
-Use GitHub MCP tools to update labels.
-
-### Step 6: Final Verification
-
-**Checklist:**
-- ✅ Issue labels updated (kept phase label, added needs-review)
-- ✅ Evidence document created and complete
-- ✅ All work committed and pushed to feature branch
-- ✅ PR exists and is ready
-- ✅ PR comment added with evidence link
-- ✅ All deliverables complete
-- ✅ Git status clean
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Issue has `status:needs-review` label
-- ✅ Issue keeps current phase label to indicate what needs review
-- ✅ Evidence document exists and is complete
-- ✅ All work committed and synced to remote
-- ✅ PR exists and is ready for review
-- ✅ PR has comment linking to evidence
-- ✅ All previous phases complete
-
-### Phase Incomplete If:
-- ❌ Labels not updated correctly
-- ❌ Evidence document missing or incomplete
-- ❌ Work not committed and synced
-- ❌ PR not ready
-- ❌ Previous phases not complete
-
-### Report Back:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "{workflow_type}",
-  issueNumber: "{issue_number}",
-  currentPhase: "submit-pr", 
-  status: "complete",
-  evidence: {
-    labelsUpdated: "Issue has status:needs-review and keeps phase label",
-    evidenceDocument: "docs/evidence/{issue_number}-{workflow_type}-evidence.md created",
-    workCommitted: "All changes committed and pushed to feature branch",
-    prStatus: "PR ready for review",
-    prComment: "PR comment added with evidence link",
-    allPhasesComplete: "All {workflow_type} phases completed successfully"
-  }
-})
-```

package/dist/registry/ai-manager-rules/shared-phases/wait-for-pr-review.md

@@ -1,170 +0,0 @@
-# Phase: wait-for-pr-review
-
-## INTENT
-Wait for human instruction to check PR status, then evaluate if PR is ready for merge or needs more work.
-
-## OUTCOME
-Either:
-- **PR Approved**: Workflow complete, ready for merge
-- **PR Has Comments**: Write feedback file and return to workflow to address feedback
-
-## RULES FOR THIS PHASE
-
-### Success Criteria
-Read `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework.
-
-## WORKFLOW
-
-### Step 1: Wait for Human Instruction
-
-**Your task is to wait for human instruction.** Do not automatically poll or check PR status.
-
-When human says "check the PR" or "proceed", move to Step 2.
-
-### Step 2: Check PR Status and Comments
-
-Use GitHub MCP tools to check the PR comprehensively:
-
-1. **Get PR Status**: Use `mcp_github_pull_request_read` with method `get` to check if PR is approved
-2. **Get All Comment Types**:
-   - **PR-level comments**: Use method `get_comments` 
-   - **Review comments**: Use method `get_review_comments` (inline/detailed comments)
-   - **Review status**: Use method `get_reviews` (approval/changes requested)
-
-### Step 3: Evaluate Results and Write Feedback File
-
-**If PR status shows "approved" AND no unresolved comments:**
-- PR is ready for merge
-- Report success
-
-**If PR has ANY comments OR is not approved:**
-- PR needs more work
-- **CRITICAL**: Write feedback file to `docs/evidence/{issueNumber}-{workflowType}-feedback.md`
-- Use Round X format (check existing file to determine next round number)
-- Report failure with feedback file path
-
-## FEEDBACK FILE FORMAT
-
-Create or append to `docs/evidence/{issueNumber}-{workflowType}-feedback.md`:
-
-```markdown
-# PR Feedback for Issue #{issueNumber} - {WorkflowType} Workflow
-
-## Round {X} Feedback
-*Received: {timestamp}*
-
-### Comment {N} - UNADDRESSED
-- **Author**: {author}
-- **Type**: {pr_comment|review_comment|review}
-- **File**: {file_path} (if applicable)
-- **Line**: {line_number} (if applicable)
-- **Comment**: {comment_body}
-- **Status**: UNADDRESSED
-```
-
-**Round Detection Logic**:
-1. If feedback file doesn't exist → Start with "Round 1"
-2. If feedback file exists → Parse to find highest "Round X", use "Round X+1"
-3. Always append new round, never overwrite existing rounds
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ PR status is "approved" in GitHub
-- ✅ No unresolved comment threads exist
-- ✅ No pending review comments
-
-**Report back with:**
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "{workflow_type}",
-  issueNumber: "{issue_number}",
-  currentPhase: "wait-for-pr-review",
-  status: "complete",
-  evidence: {
-    prStatus: "approved",
-    commentsResolved: true,
-    readyForMerge: true
-  }
-})
-```
-
-### Phase Failed When:
-- ✅ PR has unresolved comments
-- ✅ PR status is not "approved"
-- ✅ Review requests changes
-
-### Report Back:
-
-**When PR is approved and ready:**
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "{workflow_type}",
-  issueNumber: "{issue_number}",
-  currentPhase: "wait-for-pr-review",
-  status: "complete",
-  evidence: {
-    prStatus: "approved",
-    commentsResolved: true,
-    readyForMerge: true
-  }
-})
-```
-
-**When PR has comments (CRITICAL: Write feedback file first):**
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "{workflow_type}",
-  issueNumber: "{issue_number}",
-  currentPhase: "wait-for-pr-review",
-  status: "failure",
-  findings: {
-    feedbackFile: "{issueNumber}-{workflowType}-feedback.md",
-    roundNumber: {X},
-    commentCount: {total_comments},
-    prStatus: "{current_status}"
-  }
-})
-```
-
-## GITHUB MCP TOOLS TO USE
-
-1. **Check PR Status**:
-   ```javascript
-   mcp_github_pull_request_read({
-     method: "get",
-     owner: "{repo_owner}",
-     repo: "{repo_name}", 
-     pullNumber: {pr_number}
-   })
-   ```
-
-2. **Get PR Comments**:
-   ```javascript
-   mcp_github_pull_request_read({
-     method: "get_comments",
-     owner: "{repo_owner}",
-     repo: "{repo_name}",
-     pullNumber: {pr_number}
-   })
-   ```
-
-3. **Get Review Comments**:
-   ```javascript
-   mcp_github_pull_request_read({
-     method: "get_review_comments", 
-     owner: "{repo_owner}",
-     repo: "{repo_name}",
-     pullNumber: {pr_number}
-   })
-   ```
-
-4. **Get Reviews**:
-   ```javascript
-   mcp_github_pull_request_read({
-     method: "get_reviews",
-     owner: "{repo_owner}",
-     repo: "{repo_name}",
-     pullNumber: {pr_number}
-   })
-   ```

package/dist/registry/ai-manager-rules/spec-phases/spec-competitor-analysis.md

@@ -1,105 +0,0 @@
-# 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
-
-## TRIGGER
-This phase is triggered after `spec-spec` completion and before `spec-completeness-review`.
-
-## CONTEXT ADVANTAGES
-- **Full Feature Context**: Complete understanding of proposed feature and requirements
-- **Fresh Research**: Current competitive landscape information
-- **Strategic Positioning**: Ability to influence feature design based on competitive insights
-- **Configuration-Driven**: Systematic analysis of known competitors plus discovery of new ones
-
-## WORKFLOW
-
-### Step 1: Load Competitor Configuration
-- Read `.fraim/config.json` competitors section
-- Extract configured competitors and their competitive spaces
-- Note any existing competitive intelligence
-
-### Step 2: Research Configured Competitors
-For each competitor in config:
-- 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
-
-### Phase Complete When:
-- ✅ 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
-seekCoachingOnNextStep({
-  workflowType: "spec",
-  issueNumber: "your-issue-number",
-  currentPhase: "spec-competitor-analysis",
-  status: "complete",
-  evidence: {
-    competitorsAnalyzed: ["competitor1", "competitor2"],
-    newCompetitorsFound: ["new-competitor1"],
-    configurationUpdated: true,
-    differentiationStrategy: "summary of strategy",
-    specificationUpdated: true
-  }
-})
-```
-
-### Phase Incomplete If:
-- Configuration competitors not fully researched
-- No additional competitor discovery attempted
-- User not consulted on configuration updates
-- Competitive positioning strategy missing
-- Specification not updated with findings
-
-## NEXT PHASE
-After completing competitor-analysis, proceed to `spec-completeness-review` phase.

package/dist/registry/ai-manager-rules/spec-phases/spec-completeness-review.md

@@ -1,66 +0,0 @@
-# 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
-seekCoachingOnNextStep({
-  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
-  }
-})
-```

package/dist/registry/ai-manager-rules/spec-phases/spec-spec.md

@@ -1,139 +0,0 @@
-# Phase: Spec-Spec
-
-## INTENT
-To create a comprehensive feature specification that clearly defines customer needs, desired outcomes, user experience, and validation criteria.
-
-## OUTCOME
-A complete specification document that:
-- Identifies the target customer and their needs
-- Defines the desired outcome and success criteria
-- Describes the user experience in detail
-- Includes high-fidelity mocks for UI changes
-- Provides a comprehensive validation plan
-- Analyzes alternatives and competitive landscape
-
-## PRINCIPLES
-- **Customer-First**: Start with customer identification and needs
-- **Outcome-Driven**: Focus on what the customer wants to achieve
-- **Experience-Detailed**: Provide step-by-step user workflows
-- **Validation-Ready**: Include specific, executable validation steps
-- **Template-Compliant**: Follow FEATURESPEC template structure
-
-## WORKFLOW
-
-### Step 1: Get Repository Context and Issue Details
-
-**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)
-
-**Read Issue Details**: Use GitHub MCP tools to get the complete issue information:
-- Read the full issue description, title, and labels
-- Check for linked documents or references
-- Review any comments or discussion threads
-- Note any existing requirements or context
-- Understand the customer problem being addressed
-
-### Step 2: Load Template and Rules
-- Call `get_fraim_file({ path: "templates/specs/FEATURESPEC-TEMPLATE.md" })`
-- Call `get_fraim_file({ path: "rules/communication.md" })`
-- Call `get_fraim_file({ path: "rules/pr-workflow-completeness.md" })`
-
-### Step 3: Check for PR Feedback
-
-**CRITICAL**: Before creating specification, check for feedback:
-- **PR Review Feedback**: `docs/evidence/{issue_number}-spec-feedback.md`
-
-**If PR feedback exists:**
-- **MUST address all UNADDRESSED items** before proceeding
-- Update feedback file after addressing each item
-- Change status from UNADDRESSED to ADDRESSED with resolution details
-- Cannot skip or defer feedback items
-- Phase cannot complete until all feedback is addressed
-
-**PR Feedback File Format** (if exists):
-```markdown
-### Comment X - ADDRESSED
-- **Author**: reviewer_name
-- **Comment**: Original feedback
-- **Status**: ADDRESSED
-- **Resolution**: How you addressed this feedback
-```
-
-### Step 4: Create Specification Document
-- Create spec file at `docs/feature specs/{issue_number}-{kebab-case-title}.md`
-- Follow FEATURESPEC template structure exactly
-- Include all required sections:
-  - Customer identification
-  - Customer's desired outcome
-  - Customer problem definition
-  - User experience with detailed workflows
-  - Validation plan
-  - Alternatives analysis
-  - Competitive landscape
-
-### Step 4: Create High-Fidelity Mocks (if UI changes)
-If the feature involves UI changes:
-- Create HTML/CSS mocks in `docs/feature specs/mocks/`
-- Name files: `{issue_number}-{descriptive-name}.html`
-- Include at least 3 different views/states
-- Link mocks in the specification document
-- **Note**: Markdown code blocks are NOT sufficient - must be actual HTML files
-
-### Step 5: Validate Completeness
-- Ensure all template sections are complete
-- Verify customer focus is clear and specific
-- Check that user experience includes step-by-step workflows
-- Confirm validation plan is actionable and executable
-- Review alternatives and competitive analysis
-
-### Step 6: Apply Labels
-- Label the GitHub issue with `phase:spec`
-- This will trigger automatic PR creation/update
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Specification document created using FEATURESPEC template
-- ✅ All required sections completed with substantial content
-- ✅ Customer and desired outcome clearly identified
-- ✅ User experience includes detailed step-by-step workflows
-- ✅ High-fidelity mocks created (if UI changes required)
-- ✅ Validation plan includes specific, executable steps
-- ✅ Alternatives and competitive landscape analyzed
-- ✅ **PR feedback addressed** (if `docs/evidence/{issue_number}-spec-feedback.md` exists)
-- ✅ Issue labeled with `phase:spec`
-
-### Phase Incomplete If:
-- ❌ Specification document missing or incomplete
-- ❌ Template structure not followed
-- ❌ Customer identification vague or missing
-- ❌ User experience lacks detailed workflows
-- ❌ UI changes specified but no HTML mocks provided
-- ❌ Validation plan not actionable
-- ❌ Alternatives or competitive analysis missing
-- ❌ **PR feedback not addressed** (UNADDRESSED items remain in feedback file)
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "spec",
-  issueNumber: "{issue_number}",
-  currentPhase: "spec-spec", 
-  status: "complete",
-  evidence: {
-    specDocument: "docs/feature specs/{issue_number}-{title}.md",
-    templateUsed: "FEATURESPEC-TEMPLATE.md",
-    mockFiles: ["docs/feature specs/mocks/{issue_number}-view1.html", "..."],
-    namingConvention: "{issue_number}-{kebab-case-title}.md",
-    issueLabeled: "phase:spec"
-  },
-  findings: {
-    completedSections: ["Customer identification", "Customer desired outcome", "..."],
-    keyInsights: ["Key insight 1", "Key insight 2", "..."]
-  }
-})
-```