fraim-framework 2.0.44 → 2.0.45

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
+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/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-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
+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

@@ -0,0 +1,139 @@
+# 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", "..."]
+  }
+})
+```

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

@@ -0,0 +1,102 @@
+# Phase: 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: 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 2: 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 3: 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 4: 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 5: 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
+- ✅ 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
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "spec",
+  issueNumber: "{issue_number}",
+  currentPhase: "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", "..."]
+  }
+})
+```

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

@@ -0,0 +1,118 @@
+# Phase: Validate (Spec)
+
+## INTENT
+To systematically validate that the specification is complete, follows template structure, and meets all quality criteria before proceeding to the next workflow phase.
+
+## OUTCOME
+Confirmation that:
+- Specification follows FEATURESPEC template structure
+- All required sections are complete and substantial
+- Customer focus is clear and specific
+- User experience includes detailed workflows
+- High-fidelity mocks are provided (if UI changes)
+- Validation plan is actionable
+- Quality standards are met consistently
+
+## PRINCIPLES
+- **Template Compliance**: Strict adherence to FEATURESPEC structure
+- **Completeness**: All sections must be substantial, not placeholder text
+- **Customer Focus**: Clear identification of who and what
+- **Actionable Validation**: Validation plan must be executable
+- **Quality Standards**: Professional-grade specification ready for design phase
+
+## WORKFLOW
+
+### Step 1: Load Validation Rules
+- Call `get_fraim_file({ path: "ai-manager-rules/spec.json" })`
+- Review all validation criteria and grading requirements
+
+### Step 2: Execute Validation Checklist
+
+**Blocking Validation Steps (ALL must pass):**
+
+1. **Issue Labeling**: Verify issue has `phase:spec` label
+2. **Document Location**: Confirm spec exists at `docs/feature specs/{issue_number}-*.md` with >1000 characters
+3. **Template Structure**: Check all required sections present:
+   - Customer identification
+   - Customer's desired outcome  
+   - Customer problem definition
+   - User experience
+   - Validation plan
+   - Alternatives analysis
+   - Competitive landscape
+4. **Customer Section**: Customer clearly identified with specific details
+5. **Desired Outcome**: Outcome is clear, measurable, describes end goal
+6. **Problem Definition**: Specific explanation of why current state insufficient
+7. **User Experience**: Step-by-step workflow (start in X, click Y, see Z)
+8. **High-Fidelity Mocks**: If UI changes, HTML/CSS files in mocks folder (not markdown)
+9. **Validation Plan**: Specific, executable steps (browser tests, API calls, scenarios)
+10. **Requirements Coverage**: All original issue requirements addressed
+
+**Warning Validation Steps (80% should pass):**
+
+11. **Alternatives Analysis**: Table with alternatives and reasons for rejection
+12. **Competitive Landscape**: Table with competitors, solutions, market research
+
+### Step 3: Quality Assessment
+- Check for placeholder text or incomplete sections
+- Verify professional writing quality
+- Ensure consistency throughout document
+- Confirm all links and references work
+
+### Step 4: Generate Validation Report
+Document findings for each validation step:
+- Pass/Fail for each blocking step
+- Pass/Fail for each warning step  
+- Specific reasons for any failures
+- Overall assessment and recommendations
+
+## VALIDATION
+
+### Phase Complete When:
+- ✅ ALL blocking validation steps pass
+- ✅ At least 80% of warning validation steps pass
+- ✅ No placeholder text or incomplete sections
+- ✅ Quality standards met consistently
+- ✅ Validation report generated with evidence
+
+### Phase Incomplete If:
+- ❌ ANY blocking validation step fails
+- ❌ Multiple warning validation steps fail
+- ❌ Placeholder text or incomplete sections found
+- ❌ Quality issues identified
+- ❌ Requirements not properly addressed
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "spec",
+  issueNumber: "{issue_number}",
+  currentPhase: "validate", 
+  status: "complete",
+  evidence: {
+    validationReport: "All 10 blocking steps passed, 2/2 warning steps passed",
+    blockingStepsPassed: 10,
+    warningStepsPassed: 2,
+    totalWarningSteps: 2,
+    qualityAssessment: "Professional grade, ready for design phase",
+    validationDecision: "PASS"
+  }
+})
+```
+
+If validation fails:
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "spec",
+  issueNumber: "{issue_number}",
+  currentPhase: "validate", 
+  status: "incomplete",
+  findings: {
+    failedSteps: ["Step 8: High-fidelity mocks missing", "Step 9: Validation plan not actionable"],
+    validationDecision: "FAIL",
+    nextAction: "Return to spec phase to address failed validation steps"
+  }
+})
+```