fraim-framework 2.0.35 → 2.0.37

package/registry/rules/merge-requirements.md

@@ -1,231 +0,0 @@
-# Merge Requirements
-
-## INTENT
-To ensure the stability of the `master` branch and prevent accidental overwrites by requiring all agents to apply their local changes *on top of* the latest `master` branch changes, ensuring `master`'s history is never overwritten.
-
-## PRINCIPLES
-- **Rebase, Don't Merge:** Always rebase your feature branch on top of the latest `master` to maintain a clean, linear history and ensure changes from `master` are applied first.
-- **Verify After Rebase:** Run all tests and builds *after* a successful rebase to ensure stability before pushing.
-- **Document Conflict Resolution:** Clearly document how any rebase conflicts were resolved, emphasizing how `master`'s changes were preserved.
-- **Force-with-Lease:** When pushing a rebased branch, use `git push --force-with-lease` to avoid overwriting work from other contributors.
-
-## WORKFLOW
-
-## MANDATORY PRE-PUSH WORKFLOW
-
-### Before ANY push to your feature branch:
-```bash
-# 1. Sync with latest master
-git fetch origin
-git rebase origin/master
-
-# 2. If conflicts occur, resolve them using conflict resolution guide
-# (Git will pause and show you conflict markers)
-git rebase --continue
-
-# 3. Verify everything works
-npm run build
-npm run test-smoke test*.ts
-
-# 4. Only then push
-git push origin <your-feature-branch> --force-with-lease
-```
-
-### This workflow is MANDATORY because:
-- Prevents creating stale PRs
-- Ensures your changes work with latest master
-- Reduces merge conflicts
-- Required by GitHub branch protection rules
-
-## DETAILED REBASE PROCESS
-1.  **Sync with `master`:** Before pushing your changes, rebase your feature branch on top of the latest `master` branch. This applies `master`'s changes first, then your local changes on top.
-
-    ```bash
-    git checkout <your-feature-branch>
-    git fetch origin
-    git rebase origin/master
-    ```
-
-2.  **Resolve Rebase Conflicts:** If there are any conflicts during the rebase, you must resolve them intelligently. The rebase process will pause to allow you to fix the files. Your goal is to preserve the changes from `master` while reapplying your feature's changes.
-
-    ## CONFLICT RESOLUTION DURING REBASE
-
-    ### When Git Pauses for Conflicts:
-    1. **Read the conflict markers carefully:**
-       - `<<<<<<< HEAD` = Your changes
-       - `=======` = Separator  
-       - `>>>>>>> origin/master` = Master's changes
-
-    2. **Understand what each version does:**
-       - Master's version = What's already in production
-       - Your version = What you're trying to add
-
-    3. **Resolution Strategy:**
-       - **Keep master's base** (it's already tested/deployed)
-       - **Add your enhancements** on top
-       - **Never overwrite master's working code**
-       - **Never lose your new functionality**
-
-    4. **Common Conflict Scenarios:**
-
-       **Scenario 1: Same function, different implementations**
-       ```typescript
-       <<<<<<< HEAD (your changes)
-       async function processMessage(message: string) {
-         // Your new implementation
-         return await this.messageService.process(message);
-       }
-       =======
-       async function processMessage(message: string) {
-         // Master's updated implementation  
-         return await this.messageService.processWithValidation(message);
-       }
-       >>>>>>> origin/master
-       ```
-       
-       **Resolution:** Keep master's version + add your enhancements
-       ```typescript
-       async function processMessage(message: string) {
-         // Master's base implementation
-         const result = await this.messageService.processWithValidation(message);
-         // Your additional logic
-         return await this.enhanceResult(result);
-       }
-       ```
-
-       **Scenario 2: Different functions, no overlap**
-       ```typescript
-       <<<<<<< HEAD (your changes)
-       // Your new function
-       async function newFeature() {
-         return "new stuff";
-       }
-       =======
-       // Master's new function  
-       async function masterFeature() {
-         return "master stuff";
-       }
-       >>>>>>> origin/master
-       ```
-       
-       **Resolution:** Keep both (no conflict, just different functions)
-       ```typescript
-       // Master's function
-       async function masterFeature() {
-         return "master stuff";
-       }
-
-       // Your function
-       async function newFeature() {
-         return "new stuff";
-       }
-       ```
-
-    5. **After resolving conflicts:**
-       ```bash
-       # After resolving conflicts in your IDE
-       git add <resolved-file-1> <resolved-file-2>
-       git rebase --continue
-       ```
-
-    ### NEVER DO THIS:
-    ❌ "Accept Current Change" (your version) - overwrites master
-    ❌ "Accept Incoming Change" (master's version) - loses your work
-    ❌ "Accept Both Changes" - creates duplicate code
-
-    ### ALWAYS DO THIS:
-    ✅ Read both versions carefully
-    ✅ Understand what each change does
-    ✅ Merge intelligently or choose the better implementation
-    ✅ Test the resolution with: npm run build && npm run test-smoke
-    ✅ Document your resolution in the PR description
-
-3.  **Run Verification Checks:** After the rebase is complete, you must run all local verification checks to ensure the codebase is stable.
-    *   **Build the project:** Run the build command to ensure there are no compilation errors.
-    *   **Run tests:** Execute the full test suite to confirm that your changes have not introduced any regressions.
-
-4.  **Push Your Changes:** Once all checks have passed, push your rebased branch. You must use `--force-with-lease` because the rebase has rewritten your branch's commit history.
-
-    ```bash
-    git push origin <your-feature-branch> --force-with-lease
-    ```
-
-5.  **Pull Request:** When creating a pull request, the description must include a confirmation that this rebase process was followed and a detailed summary of how any conflicts were resolved.
-
-    ## PR Description Template
-    ```markdown
-    ## Merge Process Confirmation
-    - [ ] Rebased on latest master
-    - [ ] Resolved X conflicts in files: [list files]
-    - [ ] Resolution strategy: [explain what you did]
-    - [ ] Verified with: npm run build && npm run test-smoke
-    - [ ] All tests passing: ✅
-
-    ## Conflict Resolution Summary
-    ### Files with conflicts:
-    - `src/file1.ts`: [Brief description of how conflict was resolved]
-    - `src/file2.ts`: [Brief description of how conflict was resolved]
-
-    ### Resolution approach:
-    [Explain your overall strategy - e.g., "Kept master's base implementation and added my enhancements on top"]
-    ```
-
-## FINAL MERGE PROCESS (After PR Approval)
-
-### 6. **Execute the Merge:** Once your PR is approved and ready, perform the final merge:
-
-    ```bash
-    # 1. Navigate to your PR on GitHub
-    # 2. Click "Merge pull request" button
-    # 3. GitHub will automatically:
-    #    - Rebase your branch on latest master
-    #    - Apply your changes on top
-    #    - Create a clean, linear history
-    #    - Merge into master
-    ```
-
-### 7. **Post-Merge Cleanup:** After successful merge:
-
-    ```bash
-    # 1. Switch to master and pull latest changes
-    git checkout master
-    git pull origin master
-
-    # 2. Delete your feature branch (local)
-    git branch -d <your-feature-branch>
-
-    # 3. Delete your feature branch (remote)
-    git push origin --delete <your-feature-branch>
-
-    # 4. Verify the merge was successful
-    git log --oneline -5
-    ```
-
-### 8. **Final Verification:** Ensure everything is working:
-
-    ```bash
-    # Run final tests to confirm merge didn't break anything
-    npm run build
-    npm run test-smoke test*.ts
-    ```
-
-## MERGE WORKFLOW SUMMARY
-
-### Complete Process:
-1. **Development** → Work on feature branch
-2. **Pre-Push** → Rebase on master, resolve conflicts, test
-3. **Push** → Push to GitHub
-4. **PR Creation** → Create PR with detailed description
-5. **Review** → Wait for approval
-6. **Merge** → Click "Merge pull request" on GitHub
-7. **Cleanup** → Delete branches, verify merge
-8. **Verification** → Run final tests
-
-### Key Points:
-- ✅ **GitHub handles the final rebase** automatically during merge
-- ✅ **No manual rebasing** needed before merge
-- ✅ **Linear history** maintained automatically
-- ✅ **All conflicts resolved** during the merge process
-- ✅ **Clean, up-to-date master** branch
-
-By following this process, we ensure that the `master` branch always remains in a stable and deployable state. Failure to follow these rules will result in the rejection of your pull request.

package/registry/rules/simplicity.md

@@ -1,118 +0,0 @@
-# Rule: simplicity
- 
-**Path:** `rules/simplicity.md`
- 
----
- 
-# Simplicity
- 
-## INTENT
-To maintain code quality and development velocity by preventing over-engineering, ensuring agents focus on solving the specific problem at hand rather than building unnecessary complexity.
- 
-## PRINCIPLES
-- Keep it simple. Don't over-engineer.
-- Don't over-think it.
-- Focus on the assigned issue only.
-- Don't fix other issues or make unrelated changes.
-
-## REQUIREMENTS
-- While fixing an issue, focus on that issue only
-- Don't fix other issues or make unrelated changes
-- If you find other issues that must be fixed, include them in your final report as a suggested Git issue
-- Don't over-engineer solutions
-- Choose the simplest approach that solves the problem
-- **NEVER use placeholder comments** like "For now", "TODO", "FIXME", or "This is a placeholder"
-- **ALWAYS implement complete solutions** - if something needs to be customized later, implement it properly with clear configuration
-
-## PROTOTYPE-FIRST DEVELOPMENT PATTERN
-
-### Core Principle
-**Always prototype the end-to-end solution manually before engineering it correctly.**
-
-### Development Flow
-1. **Prototype**: Build simplest possible solution that works end-to-end
-2. **Manual Validation**: Test each step manually using browser/API calls
-3. **Verify**: Confirm everything works before creating automated tests
-4. **Engineer**: Refactor to production quality once proven to work
-5. **Automate**: Create Playwright tests only after manual validation
-
-### Anti-Patterns to Avoid
-- ❌ **"Assume It Works"**: Creating tests before manual validation
-- ❌ **"Over-Engineer First"**: Building complex architecture before proving simple solution works
-- ❌ **"Test-Driven Over-Engineering"**: Writing comprehensive test suites for unproven solutions
-- ❌ **"Band-Aid Fixes"**: Adding delays, retries, workarounds instead of fixing root cause
-- ❌ **"Resource Waste"**: Running expensive operations repeatedly without analyzing failures
-
-### Validation Requirements
-- **Manual Testing**: Use browser/curl to test each step manually
-- **End-to-End Flow**: Verify complete user journey works
-- **No Assumptions**: Don't assume anything works until manually verified
-- **Simple First**: Start with simplest possible implementation
-- **Prove Then Improve**: Only add complexity after proving simple version works
-
-## RESOURCE WASTE PREVENTION
-- Maximum 2 retries for expensive operations (Playwright, API calls, database)
-- After 2 failures: STOP, analyze, propose different approach
-- **STOP** if tests are consuming significant resources repeatedly
-- **Manual validation required** before creating automated tests
-
-## EXAMPLES
-
-### Good: Prototype-First Development
-```
-Issue: "Add OAuth login"
-Action: 
-1. Built simple OAuth callback → JWT → redirect
-2. Manually tested with browser (login → redirect → dashboard works)
-3. Verified end-to-end flow works
-4. Then created Playwright tests
-Result: Working solution, no overengineering
-```
-
-### Bad: Over-Engineering First
-```
-Issue: "Add OAuth login"
-Action: 
-1. Built complex session management system
-2. Created comprehensive test suite
-3. Added session validation endpoints
-4. Created infinite redirect loops
-5. Added delays/retries to fix timing issues
-Result: Over-engineered, resource waste, doesn't work
-```
-
-### Good: Manual Validation First
-```
-Issue: "Fix API endpoint"
-Action: 
-1. Fixed the code
-2. Tested with curl to verify it works
-3. Tested in browser to verify UI works
-4. Then created automated tests
-Result: Confident solution works before automation
-```
-
-### Bad: Assume It Works
-```
-Issue: "Fix API endpoint"
-Action: 
-1. Fixed the code
-2. Created Playwright tests immediately
-3. Tests fail because solution doesn't actually work
-4. Keep retrying tests instead of fixing code
-Result: Wasted resources, false confidence
-```
-
-### Good: Simple Solution
-```
-Issue: "Add error message for invalid input"
-Action: Added single validation check with clear error message
-Result: Clean, focused solution
-```
-
-### Bad: Complex Solution
-```
-Issue: "Add error message for invalid input"
-Action: Built comprehensive validation framework with multiple error types, internationalization, and complex state management
-Result: Over-engineered for simple requirement
-```

package/registry/rules/software-development-lifecycle.md

@@ -1,105 +0,0 @@
-# Software Development Lifecycle
-
-## INTENT
-To provide a structured, phase-based approach to issue resolution that ensures proper planning, implementation, testing, and cleanup while maintaining coordination with other agents and respecting project governance.
-
-## PRINCIPLES
-- **Phase-Based Development**: Clear phases with specific deliverables
-- **Branch Safety**: Never work on master, always use feature branches
-- **Local Development**: Work in isolated clones to prevent conflicts
-- **Coordination**: Use GitHub for agent coordination and status management
-- **Governance**: Respect CODEOWNERS and project policies
-
-## CORE WORKFLOW
-Always work on the feature branch for the current issue: `feature/<issue#>-<kebab-title>`. Never push to master.
-
-### Development Workflow
-1. **Clone Setup**: Work in your own cloned repository folder. Folder name should be `Ashley Calendar AI - Issue {issue_number}`
-2. **Branch Management**: Create/checkout feature branch for your issue
-3. **Local Development**: Make changes, run tests locally
-4. **Check before commit**: Only commit after approval from the user.
-5. **Remote Coordination**: Use GitHub MCP for issue labels
-
-## MANDATORY PRE-COMMIT VALIDATION
-Before ANY commit, run: `git branch` and verify NOT on master
-
-## PHASES
-
-### Design Phase
-- **Trigger**: Set ISSUE to `phase:design`
-- **Deliverable**: Create RFC document
-- **Status**: Automatically set to `status:wip`
-
-### Implementation Phase
-- **Trigger**: Set ISSUE to `phase:impl`
-- **Deliverable**: Working code with tests
-- **Status**: Set to `status:needs-review` when ready
-
-## STATUS MANAGEMENT
-- **WIP**: Automatically set when entering new phase
-- **Needs Review**: Set this when work is ready for review
-- **Complete**: Automatically set when PR is approved
-
-## EXAMPLES
-
-### Good: Proper Phase Management
-```
-Issue #84: "Fix calendar sync timeout"
-1. Set phase:design → Create RFC for retry logic
-2. Set phase:impl → Implement exponential backoff
-3. Set status:needs-review → Ready for code review
-4. PR approved → Set status:complete
-Result: Clear progression through phases
-```
-
-### Bad: Skipping Phases
-```
-Issue #84: "Fix calendar sync timeout"
-1. Jump straight to coding without design
-2. No RFC created
-3. Implementation lacks proper planning
-Result: Incomplete solution, potential rework
-```
-
-## PRE-PHASE VALIDATION
-
-### Before Starting Any Phase
-Agents MUST complete validation checklist:
-
-1. **Read Relevant Rules**:
-   - [ ] Read `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
-   - [ ] Read phase-specific workflow via `get_fraim_file` (e.g. `workflows/product-building/design.md`)
-   - [ ] Read retrospectives folder thoroughly and understand past learnings
-
-2. **Verify Environment**:
-   - [ ] Confirm working directory is correct
-   - [ ] Verify branch exists and is checked out
-   - [ ] Check issue labels are correct
-
-3. **Template Validation**:
-   - [ ] Locate correct template file
-   - [ ] Verify template exists and is readable
-   - [ ] Confirm naming convention understanding
-
-4. **Technical Understanding**:
-   - [ ] Understand relevant technical patterns for the issue
-   - [ ] Plan test strategy for core functionality
-
-### Validation Failure Response
-If any validation step fails:
-1. Stop work immediately
-2. Read missing documentation
-3. Ask clarifying questions if needed
-4. Resume only after validation complete
-
-## CLEANUP
-When user confirms code is correctly merged into master, confirm with the user, then 
-- delete remote branch
-- delete local branch
-- remove your local clone folder:
-```
-cd ..
-Remove-Item -Recurse -Force "Ashley Calendar AI - Issue {issue_number}"
-```
-
-Respect CODEOWNERS; don't modify auth/CI without approval.

package/registry/rules/spike-first-development.md

@@ -1,205 +0,0 @@
-# Rule: spike-first-development
- 
-**Path:** `rules/spike-first-development.md`
- 
----
- 
-# Spike-First Development Pattern
- 
-## INTENT
-Prevent the "Build First, Integrate Later" anti-pattern that leads to wasted work, technical debt, and incomplete implementations. Ensure agents validate technology compatibility and requirements understanding before building complex solutions.
- 
-## PRINCIPLES
-**"Validate Early, Validate Often"** - Always prove that your approach works with the smallest possible test before building anything complex.
-
-## THE ANTI-PATTERN: "Build First, Integrate Later" ❌
-
-### What It Looks Like
-1. **Build Infrastructure First**: Create complex modular systems, frameworks, or architectures
-2. **Assume Technology Support**: Assume unfamiliar technologies will support your approach
-3. **Attempt Integration**: Discover incompatibilities or limitations late in the process
-4. **Panic Implementation**: Rush to salvage work, often missing original requirements
-
-### Why It's Dangerous
-- **Wasted Work**: Build incompatible solutions that must be thrown away
-- **Rushed Integration**: Leads to incomplete implementations and missed requirements  
-- **Technical Debt**: Creates bloat and confusion in the codebase
-- **False Progress**: Appears productive while actually going backwards
-- **Missed Requirements**: Focus on infrastructure instead of actual goals
-
-## THE CORRECT PATTERN: "Spike, Analyze, Implement Incrementally" ✅
-
-### 1. SPIKE/PROOF-OF-CONCEPT FIRST (5-15 minutes)
-**Goal**: Validate the basic technology works with minimal effort
-
-**Examples**:
-- Testing Jinja in BAML: Add `{% if true %}Hello{% endif %}` to a prompt
-- Testing API integration: Make one simple API call
-- Testing database connection: Execute one basic query
-- Testing new library: Import and call one function
-
-**Questions to Answer**:
-- Does the technology support what I need?
-- What are the syntax requirements?
-- What are the limitations?
-- Does it integrate with existing systems?
-
-### 2. ANALYZE DATA STRUCTURES (10-20 minutes)
-**Goal**: Understand what data is available for your implementation
-
-**Examples**:
-- Examine input/output classes and their fields
-- Review existing data flows and transformations
-- Identify what fields are available for conditional logic
-- Map data relationships and dependencies
-
-**Questions to Answer**:
-- What fields can I use for conditionals?
-- What data is available at runtime?
-- How does data flow through the system?
-- What are the data constraints?
-
-### 3. IDENTIFY OPPORTUNITIES (15-30 minutes)
-**Goal**: Map requirements to implementation opportunities
-
-**Examples**:
-- Identify large code sections that should be conditional
-- Find repetitive patterns that can be optimized
-- Locate areas where data-driven logic would help
-- Spot opportunities for code reduction or simplification
-
-**Questions to Answer**:
-- Where should conditional logic be applied?
-- What sections are candidates for optimization?
-- How can I reduce complexity or bloat?
-- What are the highest-impact changes?
-
-### 4. IMPLEMENT INCREMENTALLY (Variable time)
-**Goal**: Build one small piece at a time with continuous validation
-
-**Process**:
-- Add ONE conditional/feature at a time
-- Test after each change
-- Ensure existing functionality is preserved
-- Validate requirements are being met
-- Only proceed to next change after current one works
-
-**Examples**:
-- Add one `{% if %}` conditional, test, then add next
-- Implement one API endpoint, test, then add next
-- Add one database operation, test, then add next
-
-### 5. VALIDATE CONTINUOUSLY (Throughout)
-**Goal**: Ensure each step works before proceeding
-
-**Validation Steps**:
-- Run tests after each change
-- Verify compilation/generation works
-- Check that existing functionality is preserved
-- Confirm requirements are being addressed
-- Get feedback early and often
-
-## GOOD vs BAD EXAMPLES
-
-### ❌ BAD: Jinja Templating Implementation
-```
-1. Create 15 modular Jinja template files
-2. Build complex include system
-3. Assume BAML supports {% include %}
-4. Discover BAML doesn't support includes
-5. Panic and rush minimal implementation
-6. Miss obvious conditional opportunities
-7. Break existing functionality
-```
-
-### ✅ GOOD: Jinja Templating Implementation
-```
-1. SPIKE: Test {% if true %}Hello{% endif %} in BAML (5 min)
-2. ANALYZE: Examine CalendarIntent/AccountabilityInfo classes (10 min)
-3. IDENTIFY: Map prompt sections to conditional opportunities (15 min)
-4. IMPLEMENT: Add {% if accountability.accountable_party == "@me" %} around booking logic (20 min)
-5. VALIDATE: Run tests, ensure functionality preserved (10 min)
-6. REPEAT: Add next conditional incrementally
-```
-
-### ❌ BAD: API Integration
-```
-1. Build complex API client framework
-2. Create elaborate error handling system
-3. Design sophisticated caching layer
-4. Discover API has rate limits that break the design
-5. Rush to add rate limiting as afterthought
-6. End up with over-engineered, fragile system
-```
-
-### ✅ GOOD: API Integration
-```
-1. SPIKE: Make one simple API call (5 min)
-2. ANALYZE: Read API documentation for limits/constraints (15 min)
-3. IDENTIFY: Determine what endpoints are needed (10 min)
-4. IMPLEMENT: Add one endpoint call with basic error handling (30 min)
-5. VALIDATE: Test the call works reliably (10 min)
-6. REPEAT: Add next endpoint incrementally
-```
-
-### ❌ BAD: Database Schema Changes
-```
-1. Design complete new schema
-2. Write migration scripts for all tables
-3. Update all model classes
-4. Discover performance issues with new design
-5. Rush to add indexes and optimize queries
-6. Break existing functionality in multiple places
-```
-
-### ✅ GOOD: Database Schema Changes
-```
-1. SPIKE: Test schema change on one small table (10 min)
-2. ANALYZE: Review existing queries and performance (20 min)
-3. IDENTIFY: Plan migration strategy and rollback plan (15 min)
-4. IMPLEMENT: Change one table with migration (45 min)
-5. VALIDATE: Test performance and functionality (15 min)
-6. REPEAT: Migrate next table incrementally
-```
-
-## ENFORCEMENT RULES
-
-### MANDATORY SPIKE REQUIREMENTS
-- **Any unfamiliar technology**: Must spike basic functionality first
-- **Any complex integration**: Must test simplest case first
-- **Any architectural changes**: Must validate approach with minimal example
-- **Any new libraries/frameworks**: Must test basic usage first
-
-### VALIDATION CHECKPOINTS
-- After spike: Technology compatibility confirmed
-- After analysis: Data structures and constraints understood
-- After identification: Implementation plan is clear and achievable
-- After each increment: Functionality works and tests pass
-- Before completion: All requirements met and validated
-
-### RED FLAGS (Stop and Spike)
-- Building complex systems without testing basic functionality
-- Making assumptions about unfamiliar technology capabilities
-- Creating elaborate architectures before validating core concepts
-- Spending significant time on infrastructure before proving it works
-- Claiming progress without demonstrable working functionality
-
-## BENEFITS OF SPIKE-FIRST DEVELOPMENT
-
-1. **Reduced Risk**: Discover incompatibilities early when they're cheap to fix
-2. **Faster Delivery**: Avoid wasted work on incompatible approaches
-3. **Better Quality**: Continuous validation ensures functionality is preserved
-4. **Clearer Requirements**: Understanding constraints leads to better solutions
-5. **Increased Confidence**: Each step is validated before proceeding
-6. **Easier Debugging**: Problems are isolated to small, recent changes
-
-## SUMMARY
-
-The spike-first development pattern prevents catastrophic failures by ensuring agents:
-- Validate technology compatibility before building
-- Understand data structures and constraints upfront
-- Implement incrementally with continuous validation
-- Focus on requirements rather than infrastructure
-- Avoid the dangerous "Build First, Integrate Later" anti-pattern
-
-**Remember**: It's always faster to spike first than to rebuild later.