fraim-framework 2.0.67 → 2.0.69

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

@@ -1,771 +0,0 @@
----
-{
-  "name": "implement",
-  "initialPhase": "implement-scoping",
-  "phases": {
-    "implement-scoping": {
-      "onSuccess": {
-        "bug": "implement-repro",
-        "feature": "implement-spike",
-        "default": "implement-spike"
-      },
-      "onFailure": "implement-scoping"
-    },
-    "implement-repro": {
-      "onSuccess": "implement-code",
-      "onFailure": "implement-scoping"
-    },
-    "implement-spike": {
-      "onSuccess": "implement-code",
-      "onFailure": "implement-scoping"
-    },
-    "implement-code": {
-      "onSuccess": "implement-validate",
-      "onFailure": "implement-scoping"
-    },
-    "implement-validate": {
-      "onSuccess": "implement-smoke",
-      "onFailure": "implement-code"
-    },
-    "implement-smoke": {
-      "onSuccess": "implement-regression",
-      "onFailure": "implement-code"
-    },
-    "implement-regression": {
-      "onSuccess": "implement-completeness-review",
-      "onFailure": "implement-code"
-    },
-    "implement-completeness-review": {
-      "onSuccess": "submit",
-      "onFailure": "implement-validate"
-    },
-    "submit": {
-      "onSuccess": "address-feedback",
-      "onFailure": "submit"
-    },
-    "address-feedback": {
-      "onSuccess": "retrospective",
-      "onFailure": "implement-validate"
-    },
-    "retrospective": {
-      "onSuccess": null,
-      "onFailure": null
-    }
-  }
-}
----
-# FRAIM Workflow: implement
-
-## Workflow Activation
-When you are assigned an issue to implement, START here:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-scoping", 
-  status: "starting"
-})
-```
-
-## Intent
-To implement bug fixes and features using a phase-based approach guided by the AI Mentor, ensuring high-quality, tested code that meets requirements.
-
-## Overview
-This workflow guides you through the complete software development lifecycle within FRAIM, from initial scoping to final completeness review.
-
-### Prerequisites
-- Active feature branch
-- Clear understanding of the issue/task
-
----
-
-## Phase: implement-scoping
-
-### INTENT
-To understand the issue requirements, identify all relevant documents, and determine if it's a bug fix or a new feature.
-
-### OUTCOME
-- Clear understanding of the problem or feature
-- Identified all relevant files and documents (RFCs, design specs, etc.)
-- Confirmed issue type (bug vs feature)
-- Initial plan for implementation
-- Ready to proceed to repro (bugs) or spike (features)
-
-### PRINCIPLES
-- **Thorough Understanding**: Read everything first. Don't guess.
-- **Identify Dependencies**: Know what files you need to touch.
-- **Ask Early**: If requirements are vague, escalate to the user immediately.
-
-### RULES FOR THIS PHASE
-
-#### Success Criteria
-Read `rules/agent-success-criteria.md` via `get_fraim_file` for criteria. Focus on **Integrity** and **Correctness**.
-
-#### Simplicity Principles
-Read `rules/simplicity.md` via `get_fraim_file`. Apply "Understand First" and "Ask for Clarification" rules.
-
-#### Architecture Compliance
-Read the architecture document at {{config.customizations.architectureDoc | "Search for architecture documents in docs/architecture/ or broader if not found there"}} to understand standards.
-
-### WORKFLOW
-
-#### Step 1: Review Issue
-Read the full issue description using {{get_issue}}. Note all requirements and constraints.
-
-#### Step 2: Identify Documents
-Identify any linked RFCs, design documents, or technical specifications. Read them thoroughly using `mcp.fraim.get_fraim_file` or `view_file`.
-
-#### Step 3: Determine Issue Type
-- **Bug**: Broken existing functionality. Requires a reproduction test.
-- **Feature**: New functionality. May require a spike/POC.
-
-#### Step 4: Create Implementation Checklist from Design
-
-**CRITICAL**: If there's a design document (RFC, TECHSPEC, FEATURESPEC), create a comprehensive checklist of ALL components to implement.
-
-**Process**:
-1. **Read the FULL design document** - Don't skip sections
-2. **Extract all "Changes" sections** - List every file to create/modify
-3. **Extract all new features** - List every endpoint, API, function
-4. **Extract all configuration changes** - List every config field
-5. **Extract all test requirements** - List every test suite needed
-
-**Checklist Format**:
-```markdown
-## Implementation Checklist (from Design)
-
-**Design Document**: [path to RFC/spec]
-
-### Part 1: [Component Name]
-- [ ] File: path/to/file.ts - [what needs to be done]
-- [ ] File: path/to/test.ts - [test description]
-- [ ] Config: .fraim/config.json - [new fields]
-
-### Part 2: [Component Name]
-- [ ] File: path/to/file.ts - [what needs to be done]
-- [ ] Endpoint: POST /api/endpoint - [description]
-
-### Part 3: [Component Name]
-...
-
-**Total Items**: X
-**Estimated Complexity**: [Small <5 items | Medium 5-15 items | Large >15 items]
-```
-
-**If checklist has >15 items**: 
-- Discuss with user about phasing the work
-- Consider breaking into multiple issues
-- Document which parts are in scope for this issue
-
-**Save this checklist** - You'll reference it throughout implementation and review phases.
-
-#### Step 5: List Uncertainties
-If any requirement is unclear, list them as findings and ask the user for clarification.
-
-### VALIDATION
-- ✅ Issue type determined (bug vs feature)
-- ✅ All requirements understood
-- ✅ All relevant documents identified
-- ✅ **Implementation checklist created** (if design doc exists)
-- ✅ No blocking uncertainties remain
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-scoping", 
-  status: "complete",
-  findings: {
-    issueType: "bug", // or "feature"
-    requirements: "Summary of what needs to be done",
-    implementationChecklist: "Markdown checklist of all components to implement (if design doc exists)",
-    uncertainties: ["List any remaining questions for the user"]
-  }
-})
-```
-
----
-
-## Phase: implement-repro
-
-### INTENT
-To create a failing test that reproduces the reported bug, confirming the root cause before fixing it.
-
-### OUTCOME
-A test case that consistently fails due to the bug described in the issue.
-
-### WORKFLOW
-
-#### Step 1: Understand Failure
-Review the bug description and any reproduction steps provided.
-
-#### Step 2: Write Failing Test
-Write a minimal test case that triggers the bug. Name it: `test: reproduces bug #{issue_number} - {description}`.
-
-#### Step 3: Verify Failure
-Run the test and verify it fails as expected. Document the error message.
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-repro", 
-  status: "complete",
-  evidence: {
-    testPath: "path/to/repro/test.test.ts",
-    errorMessage: "Exact error message from the failure",
-    reproSteps: "Steps to reproduce"
-  }
-})
-```
-
----
-
-## Phase: implement-spike
-
-### INTENT
-To build a proof-of-concept that validates the technical approach, tests uncertain or risky aspects, and confirms the design is viable before full implementation.
-
-### OUTCOME
-A working POC that:
-- Validates key technical assumptions
-- Tests risky or uncertain aspects
-- Gets user approval
-- Informs any necessary design updates
-
-### PRINCIPLES
-- **Spike-First Development**: Follow the spike-first rule for unfamiliar technology
-- **Risk Reduction**: Focus on highest-risk or most uncertain aspects
-- **Quick Validation**: Build minimal POC, not production code
-- **User Approval**: Get explicit approval before proceeding
-- **Design Updates**: Update design doc with findings
-
-### WORKFLOW
-
-#### Step 1: Review Design Document
-- Read the technical design/RFC thoroughly
-- Identify technical assumptions
-- Note any unfamiliar technologies or patterns
-- List risky or uncertain aspects
-
-#### Step 2: Identify Spike Scope
-**Focus on:**
-- Unfamiliar technology or libraries
-- Integration points with external systems
-- Performance-critical components
-- Complex algorithms or logic
-- Uncertain technical feasibility
-
-#### Step 3: Build Proof-of-Concept
-- Create minimal code to test assumptions
-- Focus on proving/disproving technical approach
-- Don't worry about production quality
-- Document what you're testing
-
-#### Step 4: Test Key Assumptions
-- Run the POC
-- Verify it works as expected
-- Test edge cases if relevant
-- Document findings
-
-#### Step 5: Get User Approval
-- Present POC to user
-- Explain what was validated
-- Share any findings or concerns
-- **Wait for explicit approval** before proceeding
-
-#### Step 6: Update Design Document
-If POC revealed:
-- Better approaches
-- Technical constraints
-- Performance considerations
-- Integration challenges
-
-**Update the design document** with findings
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-spike", 
-  status: "complete",
-  evidence: {
-    spikePath: "path/to/spike",
-    validatedAssumptions: ["Assumption 1", "Assumption 2"],
-    userApprovalReceived: true
-  }
-})
-```
-
----
-
-## Phase: implement-code
-
-### INTENT
-To write the minimal, testable code needed to fix the bug or implement the feature, following approved designs and established patterns.
-
-### OUTCOME
-Working implementation that:
-- Fixes the bug or implements the feature
-- Follows approved design/RFC
-- Includes comprehensive tests
-- Maintains code quality
-- Is ready for validation
-
-### 🎯 SUCCESS MINDSET
-
-**Your Goal**: Working application that users can actually use, not just passing tests.
-
-**Critical Success Factors**:
-- 🔍 **Manual validation is MANDATORY** - You WILL test in browser/API/CLI manually
-- ⚠️ **Every error must be investigated** - No assumptions, no "that's probably fine"
-- 🚫 **No placeholder code** - Implement complete solutions, no task placeholders or "for now" comments
-- 📊 **100% test success required** - 91% is failure, 99% is failure, only 100% is success
-- 🏗️ **Prototype-first** - Build simplest end-to-end solution, then engineer it properly
-
-### RULES FOR THIS PHASE
-
-#### Success Criteria
-Read `rules/agent-success-criteria.md` via `get_fraim_file`. Focus on:
-- **Integrity** (never claim tests pass if you didn't run them)
-- **Correctness** (follow architecture, tests must pass, no `any` types)
-- **Completeness** (implement everything in the issue description)
-
-#### Simplicity Principles
-Read `rules/simplicity.md`. Critical:
-- **Prototype-First Development**: Build simplest solution that works end-to-end, validate manually, then engineer correctly
-- **Manual Validation Required**: Test with browser/curl before creating automated tests
-- **NEVER use placeholder comments** like "For now", "task placeholders", "fix-me notes"
-
-#### Architecture Compliance
-Read the architecture document at {{config.customizations.architectureDoc | "Search for architecture documents in docs/architecture/ or broader if not found there"}} to understand standards.
-
-### 📋 WORKFLOW
-
-{{include:orchestration/parallelization-guidance.md}}
-
-#### Step 0: Create Standing Work List
-
-**CRITICAL**: Before starting implementation, create a standing work list that you'll maintain throughout the phase.
-
-**If you have an implementation checklist from scoping**:
-- Copy it here as your work list
-- This is your source of truth for what needs to be done
-
-**If no checklist exists**:
-- Create one now from the design/spec/issue
-- List every file to create/modify
-- List every test to write
-- List every config change
-
-**Work List Format**:
-```markdown
-## Standing Work List - Issue #{issue_number}
-
-**Last Updated**: [timestamp]
-
-### To Do
-- [ ] File: path/to/file.ts - [description]
-- [ ] Test: path/to/test.ts - [description]
-- [ ] Config: .fraim/config.json - [fields]
-
-### In Progress
-- [ ] File: path/to/current.ts - [what you're working on now]
-
-### Done
-- [x] File: path/to/completed.ts - [completed work]
-
-**Progress**: X/Y items complete (Z%)
-```
-
-**Maintain this list**:
-- Update it as you work
-- Move items from To Do → In Progress → Done
-- Don't rathole on one item - work breadth-first when possible
-- Reference it before calling seekMentoring
-
-#### Step 1: Prototype-First Development
-
-**Build Simplest End-to-End Solution**:
-- Focus on getting something working, not perfect
-- Don't worry about code quality initially
-- Prove the approach works before optimizing
-- Get basic functionality working first
-
-**Manual Validation (CRITICAL)**:
-- Test every step manually using browser/curl/CLI
-- Verify each acceptance criteria works
-- Take screenshots/capture output as evidence
-- Fix any issues found immediately
-
-#### Step 2: Review Design/Spec
-
-**For Bugs:**
-- Review bug description and repro test
-- Understand root cause
-- Plan minimal fix
-
-**For Features:**
-- Review approved RFC/design document
-- Review spike/POC findings (if applicable)
-- Understand all acceptance criteria
-- Plan implementation approach
-
-#### Step 3: Check for Design and PR Feedback
-
-**CRITICAL**: Before implementing, check for feedback:
-- **Design Review Feedback**: `docs/evidence/{issue_number}-design-reviewer-feedback.md`
-- **Feature Review Feedback**: `docs/evidence/{issue_number}-feature-reviewer-feedback.md`
-- **PR Review Feedback**: `docs/evidence/{issue_number}-implement-feedback.md`
-
-**If any feedback exists:**
-- **MUST address all UNADDRESSED items** before proceeding
-- Update feedback files after addressing each item
-- Change status from UNADDRESSED to ADDRESSED with resolution details
-
-#### Step 4: Implement Changes
-
-**For Bugs:**
-- Make minimal changes to fix the issue
-- Focus on root cause, not symptoms
-- Avoid unrelated changes
-- Keep diff small and focused
-
-**For Features:**
-- Implement all aspects from design/spec
-- Follow existing patterns and architecture
-- Create necessary files/modules
-- Implement all API contracts
-- No placeholder code for core functionality
-
-**🔀 Orchestration Guidance (Optional)**
-
-If you have sub-agent or parallel execution capabilities, consider delegating independent components:
-
-**When to parallelize:**
-- Multiple independent components (API, UI, DB layers)
-- Separate modules with no shared state
-- Different technology stacks (frontend/backend)
-
-**Orchestration principles:**
-- Independence enables parallelization - if components don't depend on each other, they can be built in parallel
-- Dependencies require sequencing - if Component B needs Component A's interface, build A first
-- Maintain accountability - you (the host agent) remain responsible for integration and completeness
-- Document your approach - include orchestration decisions in your evidence
-
-**Example orchestration:**
-```
-Issue has 3 independent parts:
-- Part 1: REST API endpoints (no UI dependencies)
-- Part 2: React UI components (uses API contracts from design)
-- Part 3: Database migrations (independent schema changes)
-
-Orchestration decision: Parallelize Parts 1, 2, 3 since they're independent
-Host agent: Integrate results, verify contracts match, run integration tests
-```
-
-**If you don't have these capabilities:** Simply implement sequentially as you normally would. This guidance is optional and capability-agnostic.
-
-#### Step 5: Fix All Errors (MANDATORY)
-
-**Error Investigation Requirements**:
-- **Every error in logs must be investigated**
-- **No error is "expected" until proven**
-- **Fix root causes, not symptoms**
-
-#### Step 6: Write Comprehensive Tests
-
-**MANDATORY**: Every issue requires tests - no exceptions.
-
-**For Bugs:**
-- Verify repro test from implement-repro phase now passes
-- Add additional edge case tests if needed
-
-**For Features:**
-- Write tests for all acceptance criteria
-- Test main user scenarios
-- Test edge cases
-- Test error conditions
-
-**Test Requirements:**
-- Use shared-server-utils.ts for server tests
-- Unique API keys per test
-- Proper cleanup in finally blocks
-- No individual server instances
-- Tests must validate real functionality, not mocks
-- No tests that default to passing
-
-**🔀 Orchestration Guidance (Optional)**
-
-If you have sub-agent or parallel execution capabilities, consider delegating different test types:
-
-**When to parallelize:**
-- Unit tests (fast, isolated)
-- Integration tests (moderate speed, some dependencies)
-- E2E tests (slow, full system)
-- Performance tests (resource-intensive)
-
-**Orchestration principles:**
-- Different test types can run in parallel - they validate different aspects
-- Test creation can be parallelized - writing tests doesn't require running them first
-- Test execution may have dependencies - E2E tests need working implementation
-- Maintain accountability - you verify all tests pass and meet coverage requirements
-
-**Example orchestration:**
-```
-Issue requires:
-- 5 unit tests (fast, isolated)
-- 3 integration tests (API + DB)
-- 1 E2E test (full workflow)
-
-Orchestration decision: Parallelize test creation
-- Sub-agent A: Write unit tests
-- Sub-agent B: Write integration tests  
-- Sub-agent C: Write E2E test
-Host agent: Review all tests, run test suite, verify 100% pass rate
-```
-
-**If you don't have these capabilities:** Write tests sequentially as you normally would. This guidance is optional and capability-agnostic.
-
-#### Step 7: Basic Compilation Check
-
-**Verify code compiles:**
-- Run build command: {{config.customizations.validation.buildCommand | "npm run build"}}
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-code", 
-  status: "complete",
-  evidence: {
-    filesChanged: ["src/file1.ts", "src/file2.ts"],
-    testResults: "Pass/Fail summary",
-    manualValidationDone: true,
-    workListProgress: "X/Y items complete (Z%)",
-    remainingWork: ["List any deferred items with reasons"]
-  }
-})
-```
-
----
-
-## Phase: implement-validate
-
-### INTENT
-To verify that the implementation works correctly by testing it in appropriate ways: browser testing for UI changes, API testing for backend changes, and command-line testing for CLI changes.
-
-### OUTCOME
-Confirmation that:
-- Implementation works as expected
-- All acceptance criteria are met
-- Edge cases are handled
-- No obvious bugs or issues
-
-### 🎯 VALIDATION MINDSET
-This is THE critical phase where you prove your implementation actually works. No shortcuts, no assumptions.
-
-### 📋 MANDATORY VALIDATION STEPS
-
-{{include:orchestration/parallelization-guidance.md}}
-
-#### Step 1: Build and Compilation Check ✅
-- Check TypeScript compilation: `npx tsc --noEmit --skipLibCheck`
-- Run full build: `npm run build`
-- Check for any 'as any' type bypassing: `grep -r "as any" src/`
-
-#### Step 2: Test Suite Validation 📊
-
-{{include:testing/test-execution-with-timeout.md}}
-
-**CRITICAL**: You must run the COMPLETE test suite, including all existing tests, smoke tests, and any tests you created. Do not run only the tests you wrote.
-- Run test suite: `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 120 -- {{config.customizations.validation.testSuiteCommand | "npm test"}}`
-
-#### Step 3: Manual Functionality Testing 🧪
-- **UI**: Start server (`npm run dev`) and test in browser.
-- **API**: Test endpoints with `curl`.
-- **CLI**: Execute commands directly.
-- **Document**: Steps performed, clicked/typed, results, and errors.
-
-#### Step 4: Git and Code Quality Check 🔍
-- `git status` check.
-- Remove debug code (`console.log`).
-- Check for task placeholder comments.
-
-#### Step 5: Bug/Feature Specific Validation
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-validate", 
-  status: "complete",
-  evidence: {
-    manualTestScenarios: ["Scenario 1", "Scenario 2"],
-    testOutput: "Summary of manual validation",
-    buildSuccess: true
-  }
-})
-```
-
----
-
-## Phase: implement-smoke
-
-### INTENT
-To run technical health checks ensuring the system is stable: build passes, all tests pass, git status is clean, and core functionality hasn't been broken.
-
-{{include:orchestration/parallelization-guidance.md}}
-
-### 📋 MANDATORY TECHNICAL CHECKS
-- **Build Check**: {{config.customizations.validation.buildCommand | "npm run build"}}
-- **Smoke Test**: {{config.customizations.validation.smokeTestCommand | "Run core functionality tests to ensure system stability"}}
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-smoke", 
-  status: "complete",
-  evidence: {
-    fullTestSuitePass: true,
-    gitStatusClean: true,
-    buildSuccess: true
-  }
-})
-```
-
----
-
-## Phase: implement-regression
-
-### INTENT
-For bugs: Verify the repro test now passes. For features: Write comprehensive regression tests to prevent future breakage.
-
-### WORKFLOW
-
-#### For Bug Fixes:
-- Run Repro Test: `npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 120 -- npm test -- path/to/repro/test.test.ts`
-- Verify Test Passes.
-
-#### For Features:
-- Identify Coverage: UI, edge cases, errors, integration.
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-regression", 
-  status: "complete",
-  evidence: {
-    reproTestPass: true,
-    regressionCoverage: "Summary of coverage"
-  }
-})
-```
-
----
-
-## Phase: implement-completeness-review
-
-### INTENT
-To verify that all design aspects have been implemented and that the work fully addresses the requirements.
-
-### WORKFLOW
-
-#### Step 1: RFC/Design Completeness Check
-
-**CRITICAL**: Before checking technical correctness, verify scope completeness against the design document.
-
-**If there's a design document (RFC, TECHSPEC, FEATURESPEC)**:
-
-1. **Load your implementation checklist** from scoping phase (or create one now if missing)
-
-2. **For each checklist item, verify**:
-   - ✅ **Implemented**: Point to code/tests that implement it
-   - ⏸️ **Deferred**: Document reason and create follow-up issue
-   - ❌ **Missing**: This is a BLOCKER - must implement or defer with follow-up
-
-3. **Calculate completeness**:
-   ```
-   Implemented: X/Y items (Z%)
-   Deferred: A items (with follow-up issues #123, #456)
-   Missing: B items (BLOCKER if >0 without follow-up issues)
-   ```
-
-4. **Document in evidence**:
-   - List all checklist items with status
-   - Link to follow-up issues for deferred items
-   - Explain any scope changes from original design
-
-**If completeness <100% and no deferrals documented**:
-- STOP and complete missing items, OR
-- Create follow-up issues for deferred work, OR
-- Get explicit user approval to defer
-
-**If no design document exists**:
-- Skip this step and proceed to Step 2
-
-#### Step 2: Check PR Feedback
-Check `docs/evidence/{issue_number}-implement-feedback.md`. Resolve all UNADDRESSED items.
-
-#### Step 3: Design Review Workflow
-Follow `workflows/reviewer/review-implementation-vs-design-spec.md`.
-
-#### Step 4: Execute Review Workflow
-Use all checklists; execute validation steps; create feedback docs using templates.
-
-### Report Back:
-```javascript
-seekMentoring({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-completeness-review", 
-  status: "complete",
-  findings: {
-    issueType: "bug",
-    rfcCompleteness: "X/Y items (Z%)",
-    deferredItems: ["List with follow-up issue numbers"],
-    scopeChanges: ["List any changes from original design"]
-  },
-  evidence: {
-    reviewDecision: "APPROVE",
-    workflowChecklistsComplete: "YES",
-    designAspectsVerified: "YES",
-    architectureCompliant: "YES",
-    rfcCompletenessVerified: "YES",
-    summary: "Completed systemic design review. All aspects verified."
-  }
-})
-```
-
-## Phase: submit
-
-{{include:delivery/submit.md}}
-
-## Phase: address-feedback
-
-{{include:delivery/address-feedback.md}}
-
-## Phase: retrospective
-
-{{include:delivery/retrospective.md}}