fraim-framework 2.0.65 → 2.0.67

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

@@ -0,0 +1,202 @@
+# 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
+seekMentoring({
+  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

@@ -0,0 +1,170 @@
+# 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
+seekMentoring({
+  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
+seekMentoring({
+  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
+seekMentoring({
+  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/finalize.md

@@ -0,0 +1,60 @@
+# Phase: Finalize
+
+## INTENT
+To prepare completed work for human review by setting proper labels, creating/updating PR, and documenting evidence.
+
+## OUTCOME
+Work is ready for human review with:
+- Proper issue labels applied
+- PR created/updated with work
+- Evidence documented
+- Clean handoff to next phase or review
+
+## WORKFLOW
+
+### Step 1: Apply Issue Labels
+- Remove current phase label (e.g., `phase:spec`, `phase:design`, `phase:impl`)
+- Add `status:needs-review` label
+- Keep any other relevant labels
+
+### Step 2: Create/Update Pull Request
+- Ensure PR exists for the feature branch
+- Update PR title to reflect completed work
+- Update PR description with summary of work completed
+- Link to relevant documents (specs, designs, evidence)
+
+### Step 3: Document Evidence
+- Create evidence file at `docs/evidence/{issue_number}-{workflow}-evidence.md`
+- Document key decisions made
+- List deliverables created
+- Note any recommendations for next phase
+
+### Step 4: Prepare Handoff
+- Ensure all work is committed to git
+- Verify documentation is complete
+- Confirm work is ready for human review
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ Issue labels updated (`status:needs-review`)
+- ✅ PR created/updated with work summary
+- ✅ Evidence documented
+- ✅ All work committed to git
+- ✅ Ready for human review
+
+### Report Back:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "{workflow_type}",
+  issueNumber: "{issue_number}",
+  currentPhase: "finalize", 
+  status: "complete",
+  evidence: {
+    labelsApplied: ["status:needs-review"],
+    prUpdated: true,
+    evidenceDocumented: "docs/evidence/{issue_number}-{workflow}-evidence.md",
+    workCommitted: true
+  }
+})
+```

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

@@ -0,0 +1,105 @@
+# 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
+seekMentoring({
+  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

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