fraim-framework 2.0.55 → 2.0.57

package/registry/stubs/workflows/customer-development/user-survey-dispatch.md

@@ -8,4 +8,4 @@
 > DO NOT EXECUTE.
 
 ## Intent
-To systematically formulate, build, and dispatch user surveys across multiple platforms (LinkedIn, Reddit, X, Facebook) to validate target audience assumptions and gather product insights.
+Engage target audiences across multiple social platforms through structured polls and surveys to gather quantitative and qualitative insights for product validation.

package/registry/stubs/workflows/customer-development/users-to-target.md

@@ -8,4 +8,4 @@
 > DO NOT EXECUTE.
 
 ## Intent
-Help founders systematically identify and build an inventory of specific potential customers across multiple platforms for customer discovery and outreach.
+Systematically discover, qualify, and compile a targeted prospect inventory of potential customers who have explicitly expressed pain points that your product solves.

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

@@ -8,4 +8,4 @@
 > DO NOT EXECUTE.
 
 ## 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.
+To create comprehensive technical design documents using a phase-based approach guided by the AI Mentor, ensuring proper architecture, clear requirements, and stakeholder alignment.

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

@@ -8,4 +8,4 @@
 > DO NOT EXECUTE.
 
 ## 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.
+To implement bug fixes and features using a phase-based approach guided by the AI Mentor, ensuring high-quality, tested code that meets requirements.

package/Claude.md

@@ -1 +0,0 @@
-Thoroughly review `.ai-agents/agent-guardrails.md`

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

@@ -1,73 +0,0 @@
-# Phase: Design-Completeness-Review
-
-## INTENT
-To verify that the technical design addresses all aspects of the functional specification, including the validation plan and testing strategy.
-
-## OUTCOME
-Confirmation that:
-- Design addresses all functional spec requirements
-- Validation plan from spec is reflected in design
-- Testing strategy covers all specified scenarios
-- Technical approach enables spec validation
-- Design is ready for implementation
-
-## WORKFLOW
-
-### Step 1: Load Functional Specification
-- Read the functional specification document from `docs/feature specs/{issue_number}-*.md`
-- Extract all requirements, user workflows, and validation criteria
-- Note any UI mockups and interaction patterns
-
-### Step 2: Verify Spec Requirements Coverage
-- Check that design addresses each functional requirement
-- Confirm technical approach supports all user workflows from spec
-- Verify API design enables the specified user experience
-- Ensure data models support all spec requirements
-
-### Step 3: Validation Plan Alignment
-**Critical**: The spec's validation plan must be implementable with this design
-- Review validation scenarios from functional spec
-- Confirm design provides necessary APIs/interfaces for validation
-- Check that testing strategy covers all validation scenarios
-- Verify design enables browser testing (if UI changes)
-- Ensure backend validation points are accessible
-
-### Step 4: Technical Feasibility Check
-- Confirm design is technically sound and implementable
-- Check that all spec requirements can be built with this approach
-- Verify integration points are well-defined
-- Assess if design enables the spec's success criteria
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ All functional spec requirements addressed in design
-- ✅ Validation plan from spec is implementable with this design
-- ✅ Testing strategy covers all spec scenarios
-- ✅ Technical approach is sound and feasible
-- ✅ Design enables spec success criteria
-- ✅ Ready for implementation phase
-
-### Phase Incomplete If:
-- ❌ Functional spec requirements not addressed
-- ❌ Validation plan not implementable with current design
-- ❌ Testing strategy insufficient for spec scenarios
-- ❌ Technical approach infeasible or unclear
-- ❌ Design doesn't enable spec success criteria
-
-### Report Back:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "design",
-  issueNumber: "{issue_number}",
-  currentPhase: "design-completeness-review", 
-  status: "complete",
-  evidence: {
-    specRequirementsCovered: true,
-    validationPlanImplementable: true,
-    testingStrategySufficient: true,
-    technicallyFeasible: true,
-    functionalSpecPath: "docs/feature specs/{issue_number}-*.md"
-  }
-})
-```

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

@@ -1,145 +0,0 @@
-# Phase: Design-Design
-
-## INTENT
-To create a comprehensive technical design that translates the feature specification into implementable architecture, APIs, and technical solutions.
-
-## OUTCOME
-A complete technical design document that:
-- Translates spec requirements into technical architecture
-- Defines APIs, data models, and system interactions
-- Identifies technical risks and mitigation strategies
-- Provides clear implementation guidance
-- Includes technical validation criteria
-
-## PRINCIPLES
-- **Spec-Driven**: Design directly addresses specification requirements
-- **Implementation-Ready**: Provides clear technical guidance
-- **Risk-Aware**: Identifies and mitigates technical risks
-- **Validation-Focused**: Includes technical validation criteria
-- **Template-Compliant**: Follows RFC 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 (specs, RFCs, design docs)
-- Review any comments or discussion threads
-- Note acceptance criteria and requirements
-- Identify if there's an existing specification document
-
-### Step 2: Load Template and Specification
-- Call `get_fraim_file({ path: "templates/specs/TECHSPEC-TEMPLATE.md" })` (for features)
-- Call `get_fraim_file({ path: "templates/specs/BUGSPEC-TEMPLATE.md" })` (for bugs)
-- Read the completed specification document from previous phase
-- Call `get_fraim_file({ path: "rules/spike-first-development.md" })`
-
-### Step 3: Check for PR Feedback
-
-**CRITICAL**: Before creating design, check for feedback:
-- **PR Review Feedback**: `docs/evidence/{issue_number}-design-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: Analyze Specification Requirements
-- Extract all technical requirements from specification
-- Identify system components that need modification
-- Determine API changes or additions needed
-- Note any performance or scalability considerations
-- List integration points with existing systems
-
-### Step 5: Create Technical Design Document
-- Create RFC file at `docs/rfcs/{issue_number}-{kebab-case-title}.md`
-- Follow appropriate template structure (TECHSPEC or BUGSPEC)
-- Include all required sections:
-  - Problem statement (from spec)
-  - Technical requirements
-  - Proposed solution architecture
-  - API design and data models
-  - Implementation plan
-  - Testing strategy
-  - Risk assessment and mitigation
-  - Alternative approaches considered
-
-### Step 6: Design System Architecture
-- Define component interactions and data flow
-- Specify API endpoints and request/response formats
-- Design database schema changes (if needed)
-- Plan integration with existing systems
-- Consider scalability and performance implications
-
-### Step 7: Identify Technical Risks
-- List unfamiliar technologies or patterns
-- Note complex integrations or dependencies
-- Identify performance bottlenecks
-- Consider security implications
-- Plan risk mitigation strategies
-
-### Step 8: Apply Labels
-- Label the GitHub issue with `phase:design`
-- This will trigger automatic PR creation/update
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Technical design document created using appropriate template
-- ✅ All specification requirements addressed technically
-- ✅ System architecture clearly defined
-- ✅ API design and data models specified
-- ✅ Technical risks identified and mitigation planned
-- ✅ Implementation plan provides clear guidance
-- ✅ Testing strategy defined
-- ✅ **PR feedback addressed** (if `docs/evidence/{issue_number}-design-feedback.md` exists)
-- ✅ Issue labeled with `phase:design`
-
-### Phase Incomplete If:
-- ❌ Design document missing or incomplete
-- ❌ Template structure not followed
-- ❌ Specification requirements not addressed
-- ❌ Architecture unclear or missing
-- ❌ Technical risks not identified
-- ❌ Implementation guidance insufficient
-- ❌ **PR feedback not addressed** (UNADDRESSED items remain in feedback file)
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "design",
-  issueNumber: "{issue_number}",
-  currentPhase: "design-design", 
-  status: "complete",
-  evidence: {
-    designDocument: "docs/rfcs/{issue_number}-{title}.md",
-    templateUsed: "TECHSPEC-TEMPLATE.md",
-    architectureComponents: ["API layer", "Database schema", "UI components"],
-    technicalRisks: ["Integration with legacy system", "Performance at scale"],
-    issueLabeled: "phase:design"
-  },
-  findings: {
-    keyDecisions: ["Use REST API", "PostgreSQL for data storage", "React components"],
-    riskMitigation: ["Spike legacy integration", "Load testing plan"]
-  }
-})
-```

package/dist/registry/ai-manager-rules/implement-phases/implement-code.md

@@ -1,283 +0,0 @@
-# Phase: 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 `registry/rules/agent-success-criteria.md` via `get_fraim_file` for the complete framework. Focus especially 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 `registry/rules/simplicity.md` via `get_fraim_file` for complete guidelines. Critical for coding phase:
-- **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
-- **Resource Waste Prevention**: Maximum 2 retries for expensive operations
-- **NEVER use placeholder comments** like "For now", "task placeholders", "fix-me notes"
-
-### Architecture Compliance
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full architecture guidelines. Follow all architectural standards - no shortcuts.
-
-### 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.
-
-### Failure Handling
-- **If implementation fails**: Return to implement-scoping phase to re-understand requirements
-- **If tests fail**: Fix implementation until all tests pass
-- **If architecture violations**: Return to implement-scoping to understand constraints better
-
-## PRINCIPLES
-- **Design-Driven**: Follow approved RFCs and design documents
-- **Minimal Implementation**: Write only code needed for this issue
-- **Test-First**: Write tests before or alongside implementation
-- **Quality Focus**: Maintain code quality and follow patterns
-- **Complete**: All aspects of design/spec implemented
-
-## 📋 ENHANCED WORKFLOW
-
-### 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
-- 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: 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
-- Implement all data models
-- Implement all user interfaces
-- No placeholder code for core functionality
-
-### 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**
-- **Document why any remaining errors are acceptable**
-
-**Common Error Sources**:
-- Server startup errors
-- API connection errors
-- Database connection errors
-- TypeScript compilation errors
-- Test execution errors
-
-### 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
-- Ensure tests cover the fix
-
-**For Features:**
-- Write tests for all acceptance criteria
-- Test main user scenarios
-- Test edge cases
-- Test error conditions
-- Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full test architecture standards
-
-**Test Requirements:**
-- Use shared-server-utils.ts for server tests
-- Unique API keys per test
-- Proper cleanup in finally blocks
-- No individual server instances
-- Proper timeouts (5-10s for network calls)
-- Tests must validate real functionality, not mocks
-- No tests that default to passing
-
-**Test Tagging Guidelines:**
-Tag tests appropriately to ensure proper test suite execution:
-
-- **`smoke`**: Tag tests as "smoke" if they verify:
-  - Core system functionality (CLI commands, server startup, basic workflows)
-  - Critical user journeys (init, sync, basic operations)
-  - Integration points between major components
-  - Functionality that, if broken, would make the system unusable
-
-- **`integration`**: Tests that verify multiple components working together
-- **`unit`**: Tests that verify individual functions or classes in isolation
-- **`e2e`**: End-to-end tests that verify complete user workflows
-
-### Step 7: Basic Compilation Check
-
-**Verify code compiles:**
-
-**Build Commands**: Always check `.fraim/config.json` first for `customizations.validation.buildCommand`, use that if available, otherwise default to `npm run build`.
-
-**What to Look For**:
-- Exit code 0 (success)
-- No TypeScript compilation errors
-- Clean build output
-
-**Must exit with code 0** (no errors)
-
-If compilation fails:
-- Fix TypeScript errors
-- Re-compile
-- Iterate until clean
-
-**Note**: Full validation, testing, and manual verification will be handled in subsequent phases (implement-validate, implement-smoke, implement-regression).
-
-## 📸 EVIDENCE REQUIREMENTS
-
-You MUST provide concrete evidence for all claims:
-
-1. **Implementation Complete**: Code written per design/spec
-2. **Tests Written**: Comprehensive test coverage for new functionality
-3. **Compilation Success**: TypeScript compiles without errors
-4. **Basic Functionality**: Code implements the required features/fixes
-
-**Note**: Screenshots, manual validation, server logs, and API responses will be captured in the implement-validate phase.
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ Implementation complete per design/spec
-- ✅ (Bugs) Minimal, focused changes
-- ✅ (Features) All design aspects implemented
-- ✅ Tests written for new functionality
-- ✅ TypeScript compiles cleanly
-- ✅ Design feedback addressed (if applicable)
-- ✅ **PR feedback addressed** (if `docs/evidence/{issue_number}-implement-feedback.md` exists)
-- ✅ Code implements required features/fixes
-
-### Phase Incomplete If:
-- ❌ Design/spec not fully implemented
-- ❌ No tests written for new functionality
-- ❌ TypeScript compilation errors
-- ❌ Design feedback not addressed
-- ❌ **PR feedback not addressed** (UNADDRESSED items remain in feedback file)
-- ❌ Code doesn't implement required functionality
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-code", 
-  status: "complete",
-  findings: {
-    issueType: "bug", // or "feature" - Required for phase validation
-    evidence: "Brief summary of what you implemented and validated"
-  },
-  evidence: {
-    implementation: "Brief summary of what you implemented",
-    testsWritten: "Description of tests created for new functionality",
-    compilationStatus: "TypeScript compiles without errors",
-    feedbackAddressed: "All design/PR feedback addressed (if applicable)"
-  }
-})
-```
-
-If implementation incomplete, iterate:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-code",
-  status: "incomplete", 
-  findings: {
-    issueType: "bug", // or "feature" - Required for phase validation
-    uncertainties: ["Issues encountered", "What needs to be fixed"]
-  }
-})
-```
-```
-
-## SCRIPTS
-
-**Run tests:**
-```bash
-npm test -- path/to/test.test.ts
-```
-
-**Compile TypeScript:**
-```bash
-npx tsc --noEmit --skipLibCheck
-```
-
-**Start dev server (for manual testing in validate phase):**
-```bash
-npm run dev
-```

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

@@ -1,120 +0,0 @@
-# Phase: Implement-Completeness-Review
-
-## INTENT
-To verify that all design aspects have been implemented and that the work fully addresses the requirements from the design document or issue specification.
-
-## OUTCOME
-Confirmation that:
-- All design aspects implemented
-- All acceptance criteria met
-- Implementation matches design specifications
-- Work is complete and ready for finalization
-
-## PRINCIPLES
-- **Design Fidelity**: Implementation must match design specifications
-- **Complete Coverage**: All design aspects must be addressed
-- **Evidence-Based**: Use existing comprehensive review workflows
-
-## WORKFLOW
-
-### Step 1: Check for PR Feedback to Address
-
-- Check for PR feedback file: `docs/evidence/{issue_number}-implement-feedback.md`
-- If feedback file exists, verify all comments have been addressed before proceeding
-
-**PR Feedback Validation:**
-- Read the feedback file to see all previous review rounds
-- Ensure all items marked as UNADDRESSED have been resolved
-- Update feedback file with ADDRESSED status and resolution details
-- Cannot proceed until all feedback items are properly addressed
-
-**Expected behavior:**
-- All UNADDRESSED items in feedback file must be resolved
-- Each resolved item should have detailed resolution explanation
-- Phase cannot complete with any remaining UNADDRESSED items
-
-### Step 2: Execute Design Review Workflow
-
-Use the comprehensive design validation workflow:
-- Read `registry/workflows/reviewer/review-implementation-vs-design-spec.md` via `get_fraim_file`
-- Follow the complete systematic review process
-- This workflow provides detailed checklists, validation steps, and templates
-- Works for both bugs and features - all should be reviewed against their design spec
-
-### Step 3: Execute Review Workflow
-
-**Follow the design review workflow completely:**
-- Use all the checklists provided
-- Execute all validation steps
-- Create feedback documents using the templates
-- Follow the iteration limits (max 3)
-
-### Step 4: Architecture Compliance
-
-Read `.fraim/config.json` for the architecture document path (`customizations.architectureDoc`), then read the local architecture document to understand the full architecture guidelines. Verify implementation follows all design standards.
-
-## VALIDATION
-
-### Phase Complete When:
-- ✅ PR comments addressed (if applicable)
-- ✅ PR comment verification script passes (if applicable)
-- ✅ Appropriate review workflow executed completely
-- ✅ All workflow checklists completed
-- ✅ All design aspects verified per workflow
-- ✅ Evidence quality meets workflow standards
-- ✅ Feedback documents created using workflow templates
-- ✅ Architecture compliance verified
-
-### Phase Incomplete If:
-- ❌ PR comments not properly addressed
-- ❌ PR comment verification script fails
-- ❌ Review workflow not followed completely
-- ❌ Workflow checklists incomplete
-- ❌ Design aspects not verified per workflow standards
-- ❌ Evidence quality insufficient per workflow criteria
-- ❌ Feedback documents missing or not using templates
-
-### Report Back:
-When you complete this phase, call:
-
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-completeness-review", 
-  status: "complete",
-  findings: {
-    issueType: "bug" // or "feature" - Required for phase validation
-  },
-  evidence: {
-    reviewWorkflowUsed: "review-implementation-vs-design-spec", // Which workflow was used
-    workflowChecklistsComplete: "YES", // All checklists from workflow completed?
-    designAspectsVerified: "YES", // All design aspects verified per workflow?
-    evidenceQualityMet: "YES", // Evidence meets workflow standards?
-    feedbackDocumentsCreated: "YES", // Feedback documents created using templates?
-    architectureCompliant: "YES", // Architecture compliance verified?
-    reviewDecision: "APPROVE", // APPROVE/REQUEST_CHANGES/REJECT per workflow
-    summary: "Completed systematic design review using comprehensive workflow. All design aspects verified and documented."
-  }
-})
-```
-
-If review reveals issues:
-```javascript
-seekCoachingOnNextStep({
-  workflowType: "implement",
-  issueNumber: "{issue_number}",
-  currentPhase: "implement-completeness-review", 
-  status: "incomplete",
-  findings: {
-    issueType: "bug" // or "feature" - Required for phase validation
-  },
-  evidence: {
-    reviewWorkflowUsed: "review-implementation-vs-design-spec",
-    reviewDecision: "REQUEST_CHANGES", // or "REJECT"
-    issuesFound: ["Missing test case X per workflow checklist", "Design requirement Y not implemented"],
-    feedbackDocumentLocation: "docs/evidence/{issue}-design-reviewer-feedback.md",
-    nextAction: "Implementation agent must address feedback per workflow iteration process"
-  }
-})
-```