fraim-framework 2.0.55 → 2.0.56

package/dist/registry/workflows/improve-fraim/file-issue.md

@@ -0,0 +1,32 @@
+# Workflow: File Issue for FRAIM
+
+**Path:** `workflows/improve-fraim/file-issue.md`
+
+---
+
+# File Issue Workflow
+
+## INTENT
+Allows users to easily file bugs or feature requests for the FRAIM framework directly from their working environment.
+
+## STEPS
+
+### Step 1: Gather Information
+1. Ask the user to describe the **Issue** (Bug or Feature Request).
+   - Example: "Please describe the bug you encountered or the feature you would like to request."
+
+### Step 2: Categorization (Optional)
+Ask if this is a **Bug** or a **Feature**.
+- If Bug: Use label `bug`.
+- If Feature: Use label `enhancement`.
+- Default: `triage`.
+
+### Step 3: Execute Issue Filing
+Call the `file_issue` tool with the details gathered.
+
+- `title`: `"[ISSUE]: <Short Summary>"`
+- `body`: `"<Full Description>"`
+- `labels`: `["<bug/enhancement>"]`
+
+### Step 4: Completion
+Notify the user that the issue has been filed successfully. Summarize the information (title and body) that was filed. Do not provide the issue number or URL.

package/dist/registry/workflows/learning/build-skillset.md

@@ -0,0 +1,212 @@
+# Workflow: build-skillset
+
+**Path:** `workflows/learning/build-skillset.md`
+
+---
+
+# Build Skillset
+
+## INTENT
+Create new project-specific skills through conversation with the user. This workflow allows agents to learn and document custom workflows, processes, and knowledge that are specific to the current project or team.
+
+## PRINCIPLES
+- **Conversational Learning**: Learn through natural dialogue with the user
+- **Project-Specific**: Focus on skills unique to this project/team
+- **Structured Documentation**: Create well-formatted, reusable skill documents
+- **Iterative Refinement**: Allow for feedback and improvement of skills
+- **Knowledge Persistence**: Store skills locally for future use
+
+## WORKFLOW
+
+### Phase 1: Skill Discovery
+**Objective**: Understand what skill the user wants to create
+
+**Actions**:
+1. **Initiate Conversation**: Ask the user what skill they want to build
+   - "What process or workflow would you like me to learn?"
+   - "What makes this unique to your project/team?"
+   - "What are the key steps or considerations?"
+
+2. **Gather Context**: Ask clarifying questions
+   - Tools and technologies involved
+   - Common pain points or challenges
+   - Success criteria and outcomes
+   - Frequency of use
+   - Team members involved
+
+3. **Research Existing Skills**: Check if similar workflows exist
+   - Search registry workflows for related patterns using get_fraim_file()
+   - Check local learned-skills directory for existing custom skills
+   - Identify gaps or unique aspects
+
+**Output**: Clear understanding of the skill to be created
+
+### Phase 2: Skill Design
+**Objective**: Design the structure and content of the new skill
+
+**Actions**:
+1. **Present Draft Structure**: Show the user a proposed workflow outline
+   - Intent and principles
+   - Key phases or steps
+   - Tools and resources needed
+   - Success criteria
+
+2. **Gather Feedback**: Iterate on the structure
+   - "Does this capture your process correctly?"
+   - "What am I missing?"
+   - "Are these the right steps?"
+
+3. **Refine Content**: Incorporate user feedback
+   - Add missing steps
+   - Clarify ambiguous points
+   - Include specific examples
+   - Add project-specific context
+
+**Output**: Approved skill structure and content
+
+### Phase 3: Skill Implementation
+**Objective**: Create the skill document in the learned-skills directory
+
+**Actions**:
+1. **Create Directory Structure**: Ensure proper organization in local project
+   ```
+   Local learned-skills directory structure:
+   ├── [category]/
+   │   └── [skill-name].md
+   ```
+
+2. **Write Skill Document**: Follow standard workflow format
+   - Title and metadata
+   - Intent and principles
+   - Detailed workflow steps
+   - Examples and templates
+   - Success criteria
+
+3. **Validate Format**: Ensure consistency with existing workflows
+   - Use similar structure to registry workflows
+   - Include proper markdown formatting
+   - Add relevant metadata
+
+**Output**: Complete skill document in local learned-skills directory
+
+### Phase 4: Skill Integration
+**Objective**: Make the skill discoverable and usable
+
+**Actions**:
+1. **Test Accessibility**: Verify the skill can be found
+   - Confirm file is in correct location
+   - Test that content is readable
+   - Validate markdown formatting
+
+2. **Present to User**: Show the completed skill
+   - Walk through the final document
+   - Confirm it meets expectations
+   - Note how to access it in future
+
+**Output**: Integrated, accessible skill ready for use
+
+## SKILL DOCUMENT TEMPLATE
+
+```markdown
+# Learned Skill: {skill-name}
+
+**Category:** {category}
+**Created:** {date}
+**Last Updated:** {date}
+**Project Context:** {project-specific context}
+
+---
+
+## INTENT
+{What this skill accomplishes and why it's needed}
+
+## PRINCIPLES
+- {Key principle 1}
+- {Key principle 2}
+- {Key principle 3}
+
+## WORKFLOW
+
+### Step 1: {Step Name}
+**Objective**: {What this step accomplishes}
+
+**Actions**:
+1. {Specific action}
+2. {Specific action}
+3. {Specific action}
+
+**Tools/Resources**:
+- {Tool or resource needed}
+- {Tool or resource needed}
+
+**Output**: {What this step produces}
+
+### Step 2: {Step Name}
+{Similar format}
+
+## EXAMPLES
+
+### Good Example
+{Concrete example of successful execution}
+
+### Common Pitfalls
+{Things to avoid or watch out for}
+
+## SUCCESS CRITERIA
+- [ ] {Measurable outcome 1}
+- [ ] {Measurable outcome 2}
+- [ ] {Measurable outcome 3}
+
+## NOTES
+{Any additional context, tips, or considerations}
+```
+
+## DIRECTORY STRUCTURE
+
+Learned skills are organized by category in the local project:
+
+```
+Local learned-skills directory structure:
+├── deployment/
+│   ├── our-k8s-deployment.md
+│   └── staging-validation.md
+├── code-review/
+│   ├── security-focused-review.md
+│   └── performance-review.md
+├── testing/
+│   ├── integration-test-strategy.md
+│   └── load-testing-protocol.md
+├── communication/
+│   ├── stakeholder-updates.md
+│   └── incident-response.md
+└── tools/
+    ├── custom-cli-usage.md
+    └── monitoring-setup.md
+```
+
+## CONVERSATION EXAMPLES
+
+### Example 1: Deployment Process
+```
+Agent: "What process would you like me to learn?"
+User: "Our deployment process is pretty specific - we use a custom K8s setup with manual approval gates"
+Agent: "Tell me more about these approval gates. Who approves and what do they check?"
+User: "The tech lead reviews the staging deployment, then ops approves production"
+Agent: "What tools do you use for the deployments?"
+User: "kubectl, our custom deploy script, and Slack for notifications"
+Agent: "Here's what I understand... [presents draft workflow]"
+User: "That's mostly right, but you missed the database migration step"
+Agent: "Got it, let me add that. Where does that fit in the process?"
+```
+
+### Example 2: Code Review Standards
+```
+Agent: "What skill should I learn?"
+User: "We have specific code review standards that aren't documented anywhere"
+Agent: "What makes your code reviews different from standard practices?"
+User: "We focus heavily on security since we handle financial data"
+Agent: "What specific security checks do reviewers perform?"
+User: "SQL injection prevention, input validation, audit logging..."
+Agent: "How do you handle performance reviews?"
+User: "Every PR that touches the API gets a performance review"
+```

package/dist/registry/workflows/learning/synthesize-learnings.md

@@ -0,0 +1,284 @@
+# Workflow: synthesize-learnings
+
+**Path:** `workflows/learning/synthesize-learnings.md`
+
+---
+
+# Synthesize Learnings
+
+## INTENT
+Analyze accumulated retrospectives and feedback to identify patterns, update agent rules, and prioritize common issues. This is the "sleep synthesis" moment where the system consolidates learning across all agents.
+
+## PRINCIPLES
+- **Pattern Recognition**: Identify recurring themes across multiple retrospectives
+- **Evidence-Based Updates**: Only update rules based on statistically significant patterns
+- **Priority Adjustment**: Elevate common issues, deprioritize rare ones
+- **Continuous Improvement**: System gets smarter with each synthesis cycle
+
+## WORKFLOW
+
+### Phase 1: Preparation and Scope Analysis
+**Objective**: Determine what retrospectives and feedback to analyze
+
+**Actions**:
+1. **Check Last Synthesis**: Read `lastSynthesisDate` from `.fraim/config.json`
+2. **Scan Retrospectives**: Find all files in `retrospectives/` modified after last synthesis date
+3. **Scan Evidence**: Find all files in `docs/evidence/` with feedback sections modified after last synthesis
+4. **Validate Scope**: Ensure minimum threshold (e.g., 5+ retrospectives) for meaningful analysis
+
+**Output**: List of files to analyze and date range
+
+### Phase 2: Pattern Extraction
+**Objective**: Extract learnings, patterns, and feedback themes
+
+**Analysis Categories**:
+
+#### A. Failure Patterns
+- **Root Causes**: What went wrong and why
+- **Phase-Specific Issues**: Which phases have highest failure rates
+- **Common Mistakes**: Recurring errors across different agents
+- **Context Patterns**: Types of issues that lead to specific failures
+
+#### B. Success Factors  
+- **What Worked Well**: Patterns from successful implementations
+- **Effective Approaches**: Techniques that consistently work
+- **Time Efficiency**: Patterns that lead to faster completion
+- **Quality Indicators**: What correlates with high-quality outcomes
+
+#### C. Feedback Analysis
+- **User Feedback Themes**: Common types of feedback received
+- **PR Comment Patterns**: Recurring review comments
+- **Learning Gaps**: Areas where agents consistently need guidance
+- **Communication Issues**: Misunderstandings between agents and users
+
+**Extraction Process**:
+1. **Text Analysis**: Parse retrospectives for key sections (Root Cause, Lessons Learned, etc.)
+2. **Frequency Counting**: Count occurrences of similar patterns
+3. **Categorization**: Group related patterns together
+4. **Impact Assessment**: Evaluate severity and frequency of each pattern
+
+### Phase 3: Rule Enhancement
+**Objective**: Update existing rules and create new ones based on patterns
+
+**Rule Update Categories**:
+
+#### A. High Priority Updates (>60% occurrence)
+- **Mandatory Rule Changes**: Update existing rules with new requirements
+- **New Critical Rules**: Create rules for newly identified critical patterns
+- **Phase Instruction Updates**: Enhance phase-specific guidance
+
+#### B. Medium Priority Updates (30-60% occurrence)
+- **Guideline Enhancements**: Add warnings and best practices
+- **Template Updates**: Improve evidence and retrospective templates
+- **Workflow Refinements**: Adjust workflow steps based on learnings
+
+#### C. Emerging Patterns (20-30% occurrence)
+- **Watch List**: Track patterns that may become significant
+- **Experimental Guidelines**: Test new approaches
+- **Research Areas**: Identify areas needing further investigation
+
+**Update Process**:
+1. **Identify Target Rules**: Determine which rule files need updates
+2. **Draft Enhancements**: Create specific rule additions/modifications
+3. **Validate Changes**: Ensure new rules don't conflict with existing ones
+4. **Apply Updates**: Modify rule files with new guidance
+
+### Phase 4: Priority Adjustment
+**Objective**: Update system priorities based on pattern frequency and impact
+
+**Priority Categories**:
+
+#### A. Critical Priorities (Immediate Attention)
+- Issues affecting >60% of implementations
+- High-impact failures (complete rework required)
+- Safety/security concerns
+- User satisfaction issues
+
+#### B. Important Priorities (Regular Attention)
+- Issues affecting 30-60% of implementations
+- Medium-impact failures (significant rework)
+- Efficiency improvements
+- Quality enhancements
+
+#### C. Monitor Priorities (Periodic Attention)
+- Issues affecting 10-30% of implementations
+- Low-impact failures (minor adjustments)
+- Nice-to-have improvements
+- Experimental features
+
+**Priority Updates**:
+1. **Update Config**: Modify `.fraim/config.json` with new priority rankings
+2. **Adjust Workflows**: Emphasize high-priority areas in workflow instructions
+3. **Update Templates**: Add priority-based guidance to templates
+
+### Phase 5: Documentation and Distribution
+**Objective**: Document synthesis results and distribute learnings
+
+**Outputs**:
+1. **Synthesis Report**: Comprehensive analysis of patterns and changes made
+2. **Updated Rules**: Modified rule files with new guidance
+3. **Priority Dashboard**: Summary of current system priorities
+4. **Change Log**: Record of all modifications made
+
+**Distribution**:
+1. **Update Config**: Record synthesis completion date in `.fraim/config.json`
+2. **Sync Rules**: Ensure updated rules are distributed to all agents
+3. **Notify Stakeholders**: Create summary for human oversight
+4. **Archive Results**: Store synthesis report for future reference
+
+## SYNTHESIS REPORT TEMPLATE
+
+```markdown
+# Learning Synthesis Report - {Date}
+
+## Analysis Scope
+- **Period**: {start_date} to {end_date}
+- **Retrospectives Analyzed**: {count}
+- **Evidence Files Reviewed**: {count}
+- **Total Issues Covered**: {count}
+
+## Pattern Analysis
+
+### Critical Patterns (>60% occurrence)
+1. **{Pattern Name}**: {frequency}% occurrence
+   - **Description**: {what happens}
+   - **Impact**: {consequences}
+   - **Rule Update**: {what was changed}
+
+### Important Patterns (30-60% occurrence)
+[Similar format]
+
+### Emerging Patterns (20-30% occurrence)
+[Similar format]
+
+## Rule Updates Made
+- **{Rule File}**: {description of changes}
+- **{Phase File}**: {description of enhancements}
+
+## Priority Adjustments
+- **Elevated to Critical**: {list}
+- **Elevated to Important**: {list}
+- **Demoted**: {list}
+
+## Recommendations
+1. **Immediate Actions**: {high-priority items}
+2. **Medium-term Focus**: {important improvements}
+3. **Long-term Considerations**: {strategic changes}
+
+## Next Synthesis
+- **Recommended Date**: {date}
+- **Focus Areas**: {areas to watch}
+```
+
+## CONFIG.JSON INTEGRATION
+
+Add to `.fraim/config.json`:
+
+```json
+{
+  "learning": {
+    "lastSynthesisDate": "2026-01-30T10:00:00Z"
+  }
+}
+```
+
+## PRIORITIZED LEARNINGS FILE
+
+Create prioritized learnings file (via `get_fraim_file({ path: "prioritized-learnings.md" })`):
+
+```markdown
+# Prioritized Learnings
+
+**Last Updated**: 2026-01-30T10:00:00Z  
+**Analysis Period**: 2026-01-15 to 2026-01-30  
+**Retrospectives Analyzed**: 12  
+
+## Critical Priorities (>60% occurrence)
+
+### Path Resolution Issues (73% occurrence)
+**Pattern**: Agents assume tool paths relative to current directory instead of synced framework structure
+**Impact**: Tool failures, incorrect file operations
+**Rule Updates**: 
+- Enhanced `mandatory-pre-completion-reflection.md` with path verification
+- Updated `implement-validate.md` with target repo testing requirement
+
+### Edge Case Testing Missing (67% occurrence)
+**Pattern**: Agents skip edge case testing during validation phase
+**Impact**: Bugs discovered in PR review, rework required
+**Rule Updates**:
+- Added edge case checklist to `implement-validate.md`
+- Enhanced validation evidence requirements
+
+## Important Priorities (30-60% occurrence)
+
+### Context Blindness (47% occurrence)
+**Pattern**: Agents misunderstand project context or user intent
+**Impact**: Implementing wrong solution, user feedback required
+**Rule Updates**:
+- Added context verification step to `implement-scoping.md`
+- Enhanced reflection questions about user intent
+
+## Monitor Priorities (20-30% occurrence)
+
+### Documentation Assumptions (27% occurrence)
+**Pattern**: Agents assume documentation is complete/accurate
+**Impact**: Minor implementation issues, clarification needed
+**Watch Status**: Monitoring for trend increase
+
+## Pattern Thresholds
+- **Critical**: ≥60% occurrence
+- **Important**: 30-59% occurrence  
+- **Monitor**: 20-29% occurrence
+- **Minimum Analysis**: 5+ retrospectives
+
+## Next Synthesis
+**Recommended Date**: 2026-02-06  
+**Focus Areas**: Path resolution improvements, edge case testing adoption
+```
+```
+
+## RULE ENHANCEMENT TARGETS
+
+Based on existing rule structure, synthesis would enhance:
+
+### Core Rules
+- `mandatory-pre-completion-reflection.md`: Add pattern-specific reflection questions
+- `agent-testing-guidelines.md`: Include common testing failure patterns
+- `code-quality-and-debugging-patterns.md`: Add newly identified quality issues
+
+### Phase Rules
+- `implement-scoping.md`: Add common scoping mistakes
+- `implement-validate.md`: Include validation patterns that work
+- `implement-code.md`: Add coding patterns and anti-patterns
+
+### New Rules (Created as Needed)
+- `common-failure-patterns.md`: Catalog of frequent mistakes
+- `success-patterns.md`: Proven approaches that work
+- `priority-guidance.md`: Current system priorities and focus areas
+
+## EXECUTION FREQUENCY
+
+**Recommended Schedule**:
+- **Weekly**: For active development periods
+- **Bi-weekly**: For stable periods
+- **Monthly**: For maintenance periods
+- **On-demand**: After significant issues or major changes
+
+## SUCCESS METRICS
+
+1. **Pattern Recognition**: % of patterns successfully identified and addressed
+2. **Rule Effectiveness**: Reduction in occurrence of addressed patterns
+3. **Agent Performance**: Improvement in success rates and time-to-completion
+4. **Feedback Quality**: Reduction in repeated feedback themes
+5. **System Evolution**: Continuous improvement in overall system effectiveness
+
+## SUMMARY
+
+The synthesize-learnings workflow creates a continuous improvement loop where:
+1. **Patterns are identified** from retrospectives and feedback
+2. **Rules are enhanced** based on statistical evidence
+3. **Priorities are adjusted** to focus on common issues
+4. **System gets smarter** with each synthesis cycle
+5. **Agents benefit** from accumulated organizational learning
+
+This transforms individual agent experiences into system-wide intelligence, creating a learning organization that continuously improves its effectiveness.