fraim-framework 1.0.12 → 2.0.1

package/.ai-agents/rules/merge-requirements.md

@@ -0,0 +1,231 @@
+# 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/.ai-agents/rules/pr-workflow-completeness.md

@@ -0,0 +1,191 @@
+# PR Workflow Completeness
+
+## ⚠️ CRITICAL: Complete PR Lifecycle Required
+**EVERY PR MUST BE MONITORED FROM CREATION TO MERGE**
+- Design PRs, Test Plan PRs, Implementation PRs - ALL need monitoring
+- NO EXCEPTIONS - even if you think the work is "complete"
+- If you push code, you MUST poll for feedback
+
+
+## INTENT
+To ensure AI agents autonomously handle the complete PR lifecycle with proper monitoring, feedback handling, and testing, eliminating gaps that require human intervention and ensuring thorough end-to-end handling of development processes.
+
+**This applies to every phase - design, test, implementation ... anytime you submit a PR, you must follow all these rules.**
+
+## PRINCIPLES
+- **Complete Autonomy**: Agents should handle the entire PR workflow without requiring human prompting
+- **Proactive Monitoring**: Continuously check status of actions and PRs
+- **Comprehensive Feedback**: Address all comments before resubmission
+- **Evidence-Based Progress**: Document test results and implementation status
+- **Standardized Bug Fixing**: Follow consistent reproduce-test-fix workflow
+
+## REQUIREMENTS
+
+### 1. Git Action Monitoring
+- **MUST** set issue to status:needs-review only after all Git actions associated with the PR are successful
+- **MUST** monitor these actions after commit and sync
+- **MUST** check every 30 seconds until completion
+- **MUST** timeout after 10 minutes (20 attempts) and notify the user
+- **MUST** handle network failures with exponential backoff
+- **MUST** report action failures with detailed error information
+
+#### Implementation
+```
+After commit and push:
+1. Check GitHub Actions status every 30 seconds
+2. If actions are still running, continue polling
+3. If actions fail, understand the failure, debug and fix it, iterate until actions succeed. If actions do not succeed after 3 tries, give up and give the user an analysis of the failures and next steps
+4. If 10 minutes elapse and the GitHub Action hasn't made progress, timeout and notify user
+5. If actions succeed, proceed to set issue status as per your workflow stage, and then poll as below. 
+```
+
+### 2. PR Feedback Polling
+- **MUST** poll every 1 minute awaiting PR feedback after submission
+- **MUST NOT** expect a human to come back and tell what to do
+- **MUST** timeout after 24 hours and notify the user
+- **MUST** handle network failures with exponential backoff
+- **MUST** process all types of feedback (comments, suggestions, reviews)
+- **🔥 REMINDER: This applies to DESIGN PRs too! Even if you just created a design document, you MUST poll for feedback on the PR.**
+
+#### Implementation
+```
+After PR submission:
+1. Poll for PR feedback every 1 minute
+2. If new feedback is found, process it immediately
+3. If no feedback after 24 hours, notify user
+4. Continue polling until PR has been reviewed, then take action based on the phase of the workflow you are in
+```
+
+### 3. PR Comment Handling
+- **MUST** address every comment in the PR before resubmitting for review
+- **MUST** handle threaded discussions and follow all conversation threads
+- **MUST** implement code suggestions or explain why not
+- **MUST** reply to each comment indicating how it was addressed
+- **MUST** verify all comments are addressed before changing status back to needs-review
+
+#### Implementation
+```
+When PR feedback is received:
+1. Set status:wip
+2. Track each comment that requires action
+3. Address each comment with appropriate changes
+4. Reply to each comment explaining how it was addressed
+5. Verify all comments are addressed
+6. Set status:needs-review when complete
+```
+
+### 4. Test Result Documentation
+- **MUST** add a comment to the issue with results of test cases before setting status:needs-review
+- **MUST** include which tests failed and analysis on failures
+- **MUST** document test coverage and any gaps
+- **MUST** provide evidence of test execution
+- **MUST** include specific test commands run and their output
+- **MUST** clean up cruft that was created for temporary testing, logs, debugs, etc. Do not commit these files.
+
+#### Implementation
+```
+Before setting status:needs-review:
+1. Run all relevant tests
+2. Document test results in a comment on the issue
+3. Include test command output
+4. Analyze any failures
+5. Document test coverage
+6. Only then set status:needs-review
+```
+
+### 5. Bug Fix Workflow
+- **MUST** reproduce the issue first
+- **MUST** write a test case that fails
+- **MUST** implement the fix
+- **MUST** ensure the test case passes
+- **MUST** document the entire process
+
+#### Implementation
+```
+When fixing a bug:
+1. Reproduce the issue and document steps
+2. Write a test case that fails due to the bug
+3. Implement the fix
+4. Verify the test now passes
+5. Document the entire process in the PR
+```
+
+## EXAMPLES
+
+### Good: Complete Git Action Monitoring
+```
+Action: Pushed changes to feature branch
+Monitoring: Checking GitHub Actions status every 30s
+Status at 30s: 2 workflows running
+Status at 60s: 1 workflow running, 1 completed
+Status at 90s: All workflows completed successfully
+Result: Setting status:needs-review
+```
+
+### Bad: Incomplete Monitoring
+```
+Action: Pushed changes to feature branch
+Result: Immediately set status:needs-review without checking actions
+```
+
+### Good: Proper PR Feedback Handling
+```
+Action: PR submitted for review
+Monitoring: Polling for feedback every 1 minute
+Feedback at 10m: 3 comments received
+Response: 
+- Set status:wip
+- Addressed each comment with code changes
+- Replied to each comment explaining changes
+- Verified all comments addressed
+- Set status:needs-review
+```
+
+### Bad: Incomplete Feedback Handling
+```
+Action: PR submitted for review
+Response: Waiting for user to tell me about feedback
+```
+
+### Good: Thorough Test Documentation
+```
+Before setting status:needs-review:
+- Ran tests: npm test test-api-integration.ts
+- Results: 10/10 tests passing
+- Coverage: 95% of code paths tested
+- Evidence: Full test output included in comment
+```
+
+### Bad: Missing Test Documentation
+```
+Action: Set status:needs-review
+Documentation: None provided about test results
+```
+
+### Good: Proper Bug Fix Workflow
+```
+Bug: API integration timeout
+Process:
+1. Reproduced by setting up test environment with slow network
+2. Wrote test case that fails due to timeout
+3. Implemented exponential backoff with jitter
+4. Verified test now passes
+5. Documented entire process in PR
+```
+
+### Bad: Incomplete Bug Fix
+```
+Bug: API integration timeout
+Process: Added retry logic without reproducing or testing
+```
+
+## FAILURE MODES & TIMEOUTS
+- Git action polling timeout: 10 minutes (20 attempts)
+- PR feedback polling timeout: 24 hours
+- Network failures: Use exponential backoff starting at 30s
+
+## OBSERVABILITY
+- Log all polling attempts and results
+- Track time spent in each phase of the workflow
+- Alert on polling timeouts or repeated failures
+- Record metrics on time to address PR feedback

package/.ai-agents/rules/simplicity.md

@@ -0,0 +1,112 @@
+# 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
+```