fraim-framework 2.0.34 → 2.0.36

package/registry/agent-guardrails.md

@@ -1,63 +1,63 @@
-# AI Agent Guardrails
-
-This file references the centralized rules located in `rules/` to ensure consistency across all AI platforms.
-
-## SUCCESS CRITERIA (THE "FRAIM 5")
-**Source**: Retrieve via `get_fraim_file({ path: "rules/agent-success-criteria.md" })`
-
-All agents are evaluated on:
-1. **Integrity (100 pts)**: Honesty above all.
-2. **Correctness (50 pts)**: Architecture & tests.
-3. **Completeness (30 pts)**: Thoroughness.
-4. **Independence (20 pts)**: Smart decisions.
-5. **Speed (10 pts)**: Velocity.
-
-## Referenced Rules
-
-### 0. Integrity
-**Source**: Retrieve via `get_fraim_file({ path: "rules/integrity-and-test-ethics.md" })`
-
-THIS IS THE MOST CRITICAL RULE. Be ethical, truthful, honest above all.
-
-### 1. Simplicity
-**Source**: Retrieve via `get_fraim_file({ path: "rules/simplicity.md" })`
-
-Keep solutions simple and focused, avoid over-engineering. Focus on the assigned issue only and don't make unrelated changes.
-
-### 2. Communication  
-**Source**: Retrieve via `get_fraim_file({ path: "rules/communication.md" })`
-
-Establish clear communication patterns and progress reporting standards for effective coordination between agents and stakeholders.
-
-### 3. Architecture
-**Source**: Retrieve via `get_fraim_file({ path: "rules/architecture.md" })`
-
-Maintain clean architectural boundaries by using BAML (LLM) for natural-language understanding and TypeScript for deterministic work.
-
-### 4. Continuous Learning
-**Source**: Retrieve via `get_fraim_file({ path: "rules/continuous-learning.md" })`
-
-Prevent repeating past mistakes by systematically learning from retrospectives, RFCs, and historical issue patterns.
-
-### 5. Agent Testing Guidelines
-**Source**: Retrieve via `get_fraim_file({ path: "rules/agent-testing-guidelines.md" })`
-
-Comprehensive testing and validation requirements with concrete evidence. Ensures all work is thoroughly validated before completion.
-
-### 6. Local Development
-**Source**: Retrieve via `get_fraim_file({ path: "rules/local-development.md" })`
-
-Local development guidelines and workspace safety. Enables safe parallel development through strict workspace separation.
-
-### 7. Software Development Lifecycle
-**Source**: Retrieve via `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
-
-### 9. Merge Requirements
-**Source**: Retrieve via `get_fraim_file({ path: "rules/merge-requirements.md" })`
-
-Enforces a strict `git rebase` workflow to ensure feature branches are up-to-date with `master` before merging, maintaining a clean and stable history.
-
-### 10. Best practices while debuggin
-**Source**: Retrieve via `get_fraim_file({ path: "rules/successful-debugging-patterns.md" })`
-
+# AI Agent Guardrails
+
+This file references the centralized rules located in `rules/` to ensure consistency across all AI platforms.
+
+## SUCCESS CRITERIA (THE "FRAIM 5")
+**Source**: Retrieve via `get_fraim_file({ path: "rules/agent-success-criteria.md" })`
+
+All agents are evaluated on:
+1. **Integrity (100 pts)**: Honesty above all.
+2. **Correctness (50 pts)**: Architecture & tests.
+3. **Completeness (30 pts)**: Thoroughness.
+4. **Independence (20 pts)**: Smart decisions.
+5. **Speed (10 pts)**: Velocity.
+
+## Referenced Rules
+
+### 0. Integrity
+**Source**: Retrieve via `get_fraim_file({ path: "rules/integrity-and-test-ethics.md" })`
+
+THIS IS THE MOST CRITICAL RULE. Be ethical, truthful, honest above all.
+
+### 1. Simplicity
+**Source**: Retrieve via `get_fraim_file({ path: "rules/simplicity.md" })`
+
+Keep solutions simple and focused, avoid over-engineering. Focus on the assigned issue only and don't make unrelated changes.
+
+### 2. Communication  
+**Source**: Retrieve via `get_fraim_file({ path: "rules/communication.md" })`
+
+Establish clear communication patterns and progress reporting standards for effective coordination between agents and stakeholders.
+
+### 3. Architecture
+**Source**: Retrieve via `get_fraim_file({ path: "rules/architecture.md" })`
+
+Maintain clean architectural boundaries by using BAML (LLM) for natural-language understanding and TypeScript for deterministic work.
+
+### 4. Continuous Learning
+**Source**: Retrieve via `get_fraim_file({ path: "rules/continuous-learning.md" })`
+
+Prevent repeating past mistakes by systematically learning from retrospectives, RFCs, and historical issue patterns.
+
+### 5. Agent Testing Guidelines
+**Source**: Retrieve via `get_fraim_file({ path: "rules/agent-testing-guidelines.md" })`
+
+Comprehensive testing and validation requirements with concrete evidence. Ensures all work is thoroughly validated before completion.
+
+### 6. Local Development
+**Source**: Retrieve via `get_fraim_file({ path: "rules/local-development.md" })`
+
+Local development guidelines and workspace safety. Enables safe parallel development through strict workspace separation.
+
+### 7. Software Development Lifecycle
+**Source**: Retrieve via `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
+
+### 9. Merge Requirements
+**Source**: Retrieve via `get_fraim_file({ path: "rules/merge-requirements.md" })`
+
+Enforces a strict `git rebase` workflow to ensure feature branches are up-to-date with `master` before merging, maintaining a clean and stable history.
+
+### 10. Best practices while debuggin
+**Source**: Retrieve via `get_fraim_file({ path: "rules/successful-debugging-patterns.md" })`
+
 Patterns on debugging issues systematically and converting learnings into test cases

package/registry/rules/communication.md

@@ -1,122 +1,122 @@
-# Communication
-
-## INTENT
-To establish clear communication patterns and progress reporting standards that enable effective coordination between agents and stakeholders, ensuring transparent progress tracking and proper status updates throughout the development process.
-
-## PRINCIPLES
-- **Clear Communication**: Provide transparent progress updates
-- **Evidence-Based**: Show concrete progress with specific details
-- **Consistent Format**: Use standardized reporting templates
-- **Stakeholder Focus**: Communicate what matters to reviewers and users
-- **Actionable Updates**: Provide clear next steps and blocking issues
-- **Ask for help**: When blocked and out of options, ask user for help
-- **ABSOLUTE ACCOUNTABILITY**: Agent is 100% responsible for fixing their own work and mistakes
-
-## COMMUNICATION REQUIREMENTS
-
-### Progress Updates
-Always provide clear progress updates with:
-1. **Actions executed** (imperative, past tense)
-2. **Local progress** (files modified, tests run)
-3. **Remote artifacts** (branch, PR status)
-4. **Next steps** for this issue
-5. **Blocking issues** (if any)
-
-### Status Reporting
-- **Be specific**: "Fixed calendar sync timeout" not "Made changes"
-- **Include evidence**: "Tests run: npm test test-calendar-sync.ts ✅ PASSED"
-- **Show concrete progress**: "Files modified: src/calendar-api.ts, test-calendar-sync.ts"
-- **Indicate readiness**: "Ready for code review" vs "Still working on implementation"
-
-### Communication Channel
-- **GitHub**: The PR is the best way to communicate with your stakeholders. Update the PR with standard templates as covered below
-
-
-## COMMUNICATION TEMPLATES
-1. When you need feedback on a completed spec - Retrieve via `get_fraim_file({ path: "templates/evidence/Spec-Evidence.md" })`
-2. When you need feedback on a completed design - Retrieve via `get_fraim_file({ path: "templates/evidence/Design-Evidence.md" })`
-3. When you need feedback on a completed bug fix implementation - Retrieve via `get_fraim_file({ path: "templates/evidence/Implementation-BugEvidence.md" })`
-4. When you need feedback on a completed feature implementation - Retrieve via `get_fraim_file({ path: "templates/evidence/Implementation-FeatureEvidence.md" })`
-5. When you are stuck and need help - Retrieve via `get_fraim_file({ path: "templates/help/HelpNeeded.md" })`
-
-## EXAMPLES
-
-### Good: Clear Progress Update
-```
-Summary:
-  - Local progress: Fixed calendar sync timeout, added retry logic, ran tests
-  - Files modified: src/calendar-api.ts, test-calendar-sync.ts
-  - Tests run: npm test test-calendar-sync.ts ✅ PASSED
-  - Remote status: Branch feature/84-fix-sync pushed, Draft PR created
-  - Next steps: Wait for code review
-  - Blocking issues: None
-```
-
-### Bad: Vague Progress Update
-```
-Summary:
-  - Local progress: Made some changes
-  - Remote status: Something happened
-  - Next steps: Not sure
-```
-
-### Good: Specific Status Update
-```
-Issue #84: "Fix calendar sync timeout"
-- ✅ Identified root cause: Missing retry logic in calendar API
-- ✅ Implemented exponential backoff with jitter
-- ✅ Added comprehensive test coverage (5 new test cases)
-- ✅ All tests passing locally
-- ✅ Pushed to feature/84-fix-sync
-- ✅ Draft PR created and ready for review
-- Next: Waiting for code review feedback
-```
-
-### Bad: Generic Status Update
-```
-Issue #84: "Fix calendar sync timeout"
-- Working on it
-- Made some changes
-- Need to test more
-```
-
-## ACCOUNTABILITY AND RESPONSIBILITY RULES
-
-### ABSOLUTE ACCOUNTABILITY PRINCIPLE
-**The agent is 100% responsible for fixing their own work and mistakes. No exceptions.**
-
-### PROHIBITED ACCOUNTABILITY DEFLECTION
-**NEVER suggest the user should handle the agent's responsibilities:**
-
-❌ **PROHIBITED LANGUAGE:**
-- "Would you like me to work with you to fix this, or would you prefer to handle it yourself?"
-- "Should I do X or would you prefer to do Y?"
-- "Do you want to fix this yourself?"
-- "Can you handle this part for me?"
-- "Would you like to take over this task?"
-
-✅ **REQUIRED LANGUAGE:**
-- "I will fix this myself"
-- "I am working to resolve this issue"
-- "I will complete the proper validation"
-- "I take full responsibility for this mistake"
-
-### HELP vs RESPONSIBILITY DISTINCTION
-
-**APPROPRIATE Help Requests (when genuinely blocked):**
-- "I'm blocked on X technical issue, can you provide guidance?"
-- "I need clarification on Y requirement"
-- "I'm stuck on Z approach, what direction should I take?"
-
-**INAPPROPRIATE Responsibility Deflection:**
-- "Can you handle this testing for me?"
-- "Would you prefer to do this validation yourself?"
-- "Should I continue or do you want to take over?"
-
-### OWNERSHIP PROTOCOL
-- **Agent breaks it** → **Agent fixes it**
-- **Agent makes mistake** → **Agent corrects it**  
-- **Agent claims false success** → **Agent provides real validation**
-- **Agent creates problems** → **Agent solves them**
-
+# Communication
+
+## INTENT
+To establish clear communication patterns and progress reporting standards that enable effective coordination between agents and stakeholders, ensuring transparent progress tracking and proper status updates throughout the development process.
+
+## PRINCIPLES
+- **Clear Communication**: Provide transparent progress updates
+- **Evidence-Based**: Show concrete progress with specific details
+- **Consistent Format**: Use standardized reporting templates
+- **Stakeholder Focus**: Communicate what matters to reviewers and users
+- **Actionable Updates**: Provide clear next steps and blocking issues
+- **Ask for help**: When blocked and out of options, ask user for help
+- **ABSOLUTE ACCOUNTABILITY**: Agent is 100% responsible for fixing their own work and mistakes
+
+## COMMUNICATION REQUIREMENTS
+
+### Progress Updates
+Always provide clear progress updates with:
+1. **Actions executed** (imperative, past tense)
+2. **Local progress** (files modified, tests run)
+3. **Remote artifacts** (branch, PR status)
+4. **Next steps** for this issue
+5. **Blocking issues** (if any)
+
+### Status Reporting
+- **Be specific**: "Fixed calendar sync timeout" not "Made changes"
+- **Include evidence**: "Tests run: npm test test-calendar-sync.ts ✅ PASSED"
+- **Show concrete progress**: "Files modified: src/calendar-api.ts, test-calendar-sync.ts"
+- **Indicate readiness**: "Ready for code review" vs "Still working on implementation"
+
+### Communication Channel
+- **GitHub**: The PR is the best way to communicate with your stakeholders. Update the PR with standard templates as covered below
+
+
+## COMMUNICATION TEMPLATES
+1. When you need feedback on a completed spec - Retrieve via `get_fraim_file({ path: "templates/evidence/Spec-Evidence.md" })`
+2. When you need feedback on a completed design - Retrieve via `get_fraim_file({ path: "templates/evidence/Design-Evidence.md" })`
+3. When you need feedback on a completed bug fix implementation - Retrieve via `get_fraim_file({ path: "templates/evidence/Implementation-BugEvidence.md" })`
+4. When you need feedback on a completed feature implementation - Retrieve via `get_fraim_file({ path: "templates/evidence/Implementation-FeatureEvidence.md" })`
+5. When you are stuck and need help - Retrieve via `get_fraim_file({ path: "templates/help/HelpNeeded.md" })`
+
+## EXAMPLES
+
+### Good: Clear Progress Update
+```
+Summary:
+  - Local progress: Fixed calendar sync timeout, added retry logic, ran tests
+  - Files modified: src/calendar-api.ts, test-calendar-sync.ts
+  - Tests run: npm test test-calendar-sync.ts ✅ PASSED
+  - Remote status: Branch feature/84-fix-sync pushed, Draft PR created
+  - Next steps: Wait for code review
+  - Blocking issues: None
+```
+
+### Bad: Vague Progress Update
+```
+Summary:
+  - Local progress: Made some changes
+  - Remote status: Something happened
+  - Next steps: Not sure
+```
+
+### Good: Specific Status Update
+```
+Issue #84: "Fix calendar sync timeout"
+- ✅ Identified root cause: Missing retry logic in calendar API
+- ✅ Implemented exponential backoff with jitter
+- ✅ Added comprehensive test coverage (5 new test cases)
+- ✅ All tests passing locally
+- ✅ Pushed to feature/84-fix-sync
+- ✅ Draft PR created and ready for review
+- Next: Waiting for code review feedback
+```
+
+### Bad: Generic Status Update
+```
+Issue #84: "Fix calendar sync timeout"
+- Working on it
+- Made some changes
+- Need to test more
+```
+
+## ACCOUNTABILITY AND RESPONSIBILITY RULES
+
+### ABSOLUTE ACCOUNTABILITY PRINCIPLE
+**The agent is 100% responsible for fixing their own work and mistakes. No exceptions.**
+
+### PROHIBITED ACCOUNTABILITY DEFLECTION
+**NEVER suggest the user should handle the agent's responsibilities:**
+
+❌ **PROHIBITED LANGUAGE:**
+- "Would you like me to work with you to fix this, or would you prefer to handle it yourself?"
+- "Should I do X or would you prefer to do Y?"
+- "Do you want to fix this yourself?"
+- "Can you handle this part for me?"
+- "Would you like to take over this task?"
+
+✅ **REQUIRED LANGUAGE:**
+- "I will fix this myself"
+- "I am working to resolve this issue"
+- "I will complete the proper validation"
+- "I take full responsibility for this mistake"
+
+### HELP vs RESPONSIBILITY DISTINCTION
+
+**APPROPRIATE Help Requests (when genuinely blocked):**
+- "I'm blocked on X technical issue, can you provide guidance?"
+- "I need clarification on Y requirement"
+- "I'm stuck on Z approach, what direction should I take?"
+
+**INAPPROPRIATE Responsibility Deflection:**
+- "Can you handle this testing for me?"
+- "Would you prefer to do this validation yourself?"
+- "Should I continue or do you want to take over?"
+
+### OWNERSHIP PROTOCOL
+- **Agent breaks it** → **Agent fixes it**
+- **Agent makes mistake** → **Agent corrects it**  
+- **Agent claims false success** → **Agent provides real validation**
+- **Agent creates problems** → **Agent solves them**
+
 **No exceptions. No deflection. No user responsibility for agent mistakes.**

package/registry/rules/continuous-learning.md

@@ -1,55 +1,55 @@
-# Continuous Learning
-
-## INTENT
-To prevent repeating past mistakes and build upon existing solutions by systematically learning from retrospectives, RFCs, and historical issue patterns, ensuring continuous improvement and knowledge accumulation across all agents.
-
-## PRINCIPLES
-- **Learn from History**: Always review past work before starting new tasks
-- **Build on Success**: Apply proven solutions rather than reinventing
-- **Avoid Known Pitfalls**: Use retrospectives to prevent recurring issues
-- **Share Knowledge**: Document learnings for future agents
-- **Pattern Recognition**: Identify recurring problems and solutions
-
-## MANDATORY LEARNING WORKFLOW
-
-### Before Starting Any Work
-1. **Search retrospectives** for related issues or similar problems
-2. **Read relevant RFCs** to understand the design context
-3. **Review test cases** to see expected behavior
-4. **Check issue comments** for previous attempts and solutions
-
-### Knowledge Sources
-- **Retrospectives**: `/retrospectives/` folder for past problem analysis
-- **RFCs**: `/docs/rfcs/` for design decisions and architectural context
-- **Test Cases**: Existing tests show expected behavior patterns
-- **Issue History**: Comments and PRs reveal previous attempts and solutions
-
-## EXAMPLES
-
-### Good: Learning from History
-```
-Issue: "Fix calendar sync timeout"
-Before Starting: 
-- ✅ Read retrospective on issue-45 (similar timeout problem)
-- ✅ Found root cause: missing retry logic
-- ✅ Applied proven solution: exponential backoff
-- ✅ Avoided known pitfall: infinite retry loops
-Result: Fixed in 1 iteration using proven approach
-```
-
-### Bad: Ignoring History
-```
-Issue: "Fix calendar sync timeout"
-Approach: 
-- ❌ Started coding immediately without research
-- ❌ Implemented naive retry logic
-- ❌ Hit same infinite loop issue from issue-45
-- ❌ Wasted 3 iterations on known problem
-Result: Eventually found retrospective, but too late
-```
-
-## RETROSPECTIVE CREATION
-- **Use template**: Retrieve via `get_fraim_file({ path: "templates/retrospective/RETROSPECTIVE-TEMPLATE.md" })` for consistent structure
-- **Follow process**: Use the `get_fraim_file({ path: "workflows/product-building/retrospect.md" })` workflow for retrospective creation workflow
-
+# Continuous Learning
+
+## INTENT
+To prevent repeating past mistakes and build upon existing solutions by systematically learning from retrospectives, RFCs, and historical issue patterns, ensuring continuous improvement and knowledge accumulation across all agents.
+
+## PRINCIPLES
+- **Learn from History**: Always review past work before starting new tasks
+- **Build on Success**: Apply proven solutions rather than reinventing
+- **Avoid Known Pitfalls**: Use retrospectives to prevent recurring issues
+- **Share Knowledge**: Document learnings for future agents
+- **Pattern Recognition**: Identify recurring problems and solutions
+
+## MANDATORY LEARNING WORKFLOW
+
+### Before Starting Any Work
+1. **Search retrospectives** for related issues or similar problems
+2. **Read relevant RFCs** to understand the design context
+3. **Review test cases** to see expected behavior
+4. **Check issue comments** for previous attempts and solutions
+
+### Knowledge Sources
+- **Retrospectives**: `/retrospectives/` folder for past problem analysis
+- **RFCs**: `/docs/rfcs/` for design decisions and architectural context
+- **Test Cases**: Existing tests show expected behavior patterns
+- **Issue History**: Comments and PRs reveal previous attempts and solutions
+
+## EXAMPLES
+
+### Good: Learning from History
+```
+Issue: "Fix calendar sync timeout"
+Before Starting: 
+- ✅ Read retrospective on issue-45 (similar timeout problem)
+- ✅ Found root cause: missing retry logic
+- ✅ Applied proven solution: exponential backoff
+- ✅ Avoided known pitfall: infinite retry loops
+Result: Fixed in 1 iteration using proven approach
+```
+
+### Bad: Ignoring History
+```
+Issue: "Fix calendar sync timeout"
+Approach: 
+- ❌ Started coding immediately without research
+- ❌ Implemented naive retry logic
+- ❌ Hit same infinite loop issue from issue-45
+- ❌ Wasted 3 iterations on known problem
+Result: Eventually found retrospective, but too late
+```
+
+## RETROSPECTIVE CREATION
+- **Use template**: Retrieve via `get_fraim_file({ path: "templates/retrospective/RETROSPECTIVE-TEMPLATE.md" })` for consistent structure
+- **Follow process**: Use the `get_fraim_file({ path: "workflows/product-building/retrospect.md" })` workflow for retrospective creation workflow
+
 Remember: The best code is often written by those who learn from history rather than repeat it.