fraim-framework 1.0.11 → 2.0.1

package/.ai-agents/workflows/implement.md

@@ -0,0 +1,170 @@
+# Implementation Phase
+
+## INTENT
+To implement solutions based on approved design documents, ensuring minimal, testable code that meets requirements while following established patterns and maintaining code quality.
+
+## PRINCIPLES
+- **Design-Driven**: Follow approved RFCs and design documents
+- **Minimal Implementation**: Write only the code needed for the issue
+- **Test-First**: Ensure comprehensive test coverage
+- **Quality Focus**: Maintain code quality and follow patterns
+- **Complete**: All aspects of technical spec are implemented, tested, validated
+- **Spike-First Development**: Follow `.ai-agents/rules/spike-first-development.md` to validate technology compatibility before building complex solutions
+
+## IMPLEMENTATION WORKFLOW
+
+### Step 1: Issue Identification
+Ask for {issue_number} (and optional {slug}); confirm target branch feature/{issue_number}-{slug}.
+
+### Step 2: Phase Initiation
+Label the issue 'phase:impl'. (GitHub Action will automatically label the issue `status:wip` and update the existing draft PR)
+
+### Step 3: Environment Setup
+**IMPORTANT**: The user has already run `prep-issue.sh` which has:
+- ✅ Created the feature branch
+- ✅ Checked out the branch
+- ✅ Created draft PR
+- ✅ Indexed the codebase with Serena
+- ✅ Opened the editor in the prepared workspace
+
+You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
+
+### Step 4: Work Location
+You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working.
+
+### Step 5: Implementation Work
+Your work entails the following:
+
+- **SPIKE-FIRST CHECK**: Read and follow `.ai-agents/rules/spike-first-development.md`
+- If implementation involves unfamiliar technology, create spike/proof-of-concept first
+- Validate technology compatibility before building complex solutions
+- Review the RFC associated with this issue.
+- Determine whether changes need to be made to existing code, or brand new code needs to be written.
+- Write the minimal set of code and test cases needed for this issue.
+- **CRITICAL INTEGRITY CHECK**: Ensure test cases pass with original, unmodified criteria
+- **VERIFICATION REQUIRED**: Run tests with original criteria before claiming success
+- When ready for review, flip issue to 'status:needs-review' and remove 'status:wip'
+- While submitting review, add a comment to the PR with evidence - use template `.ai-agents/templates/evidence/Implementation-BugEvidence.md` for bugs, `.ai-agents/templates/evidence/Implementation-FeatureEvidence.md` for features.
+
+### Step 6: MANDATORY FINAL STATUS UPDATE
+**🚨 CRITICAL - DO NOT SKIP THIS STEP:**
+
+Once all implementation work is complete and evidence is provided:
+
+1. **REQUIRED**: Update issue status from `status:wip` to `status:needs-review`
+2. **REQUIRED**: Verify the status change was applied successfully
+3. **REQUIRED**: Confirm issue is ready for user review
+
+**This step is MANDATORY and must not be forgotten. Add it to your todo list at the start of implementation.**
+
+## TEST INTEGRITY REQUIREMENTS
+
+### Test Immutability Rule
+**Test success criteria are immutable during implementation phase.**
+
+#### What This Means
+- Test criteria must remain unchanged from design phase
+- Success requirements cannot be modified to hide failures
+- Test logic cannot be adjusted to accommodate broken code
+- Any changes to test requirements must be explicitly approved and documented
+
+#### Verification Process
+Before claiming any implementation is working:
+1. Run tests with original, unmodified criteria
+2. Verify ALL requirements pass without exception
+3. Document any test modifications if absolutely necessary
+4. Get explicit approval for any test changes
+
+### Progress Transparency Requirements
+**Always be honest about implementation status and challenges.**
+
+#### Required Statements
+When facing implementation challenges, explicitly state:
+- "I am struggling with [specific issue] and need help"
+- "The implementation is not working because [specific reason]"
+- "I need to fix [specific problem] before claiming success"
+
+#### Prohibited Statements
+- "The implementation is working" (when tests fail)
+- "Core functionality is complete" (when critical features broken)
+- "Tests are passing" (when criteria were modified)
+- "Issue is resolved" (when underlying problems exist)
+
+### Success Verification Standards
+**Genuine success requires meeting ALL original criteria without modification.**
+
+#### Verification Checklist
+Before marking any task complete:
+- [ ] All original test criteria pass without modification
+- [ ] No test logic was changed to accommodate broken code
+- [ ] Success requirements are met exactly as originally defined
+- [ ] Implementation works with real data/scenarios
+- [ ] No critical functionality is missing or broken
+
+### When Tests Fail
+1. **Don't modify tests** - Fix the code instead
+2. **Don't claim success** - Admit the failure
+3. **Ask for help** - Be transparent about challenges
+4. **Fix root causes** - Address underlying issues
+5. **Verify with original criteria** - Ensure genuine success
+
+### When Facing Difficult Challenges
+1. **Be honest** - State what's not working
+2. **Ask for guidance** - Don't try to fake success
+3. **Focus on solutions** - Work on fixing the code
+4. **Maintain integrity** - Don't compromise standards
+5. **Document struggles** - Help others learn from challenges
+
+### Step 7: Iteration
+If workflow actions or reviewer feedback indicates more work is needed:
+
+- Label the issue 'status:wip' and remove 'status:needs-review'
+- Go back to Step 5 and iterate until PR is approved
+
+## EXAMPLES
+
+### Good: Proper Implementation Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84, branch feature/84-fix-sync
+2. ✅ Phase: Set phase:impl, PR created
+3. ✅ Environment: User ran prep-issue.sh, ready to work
+4. ✅ Location: Working in prepared workspace with Serena indexing
+5. ✅ RFC Review: Read docs/rfcs/84-fix-sync-timeout.md
+6. ✅ Analysis: Determined need to modify existing retry logic
+7. ✅ Implementation: Added exponential backoff with jitter
+8. ✅ Tests: Created test cases, all passing
+9. ✅ Review: Set status:needs-review
+10. ✅ Iteration: Incorporated feedback, updated implementation
+Result: Clean, tested implementation following design
+```
+
+### Bad: Incomplete Implementation Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84
+2. ❌ Skip: Didn't review RFC
+3. ❌ Skip: Started coding without understanding requirements
+4. ❌ Skip: No test cases written
+5. ❌ Skip: Didn't verify tests pass
+6. ❌ Skip: No code review process
+Result: Incomplete, untested implementation
+```
+
+## 🔥 MANDATORY COMPLETION CHECKLIST
+
+**Before claiming implementation is complete, verify ALL items:**
+
+### ✅ Implementation Checklist
+- [ ] RFC reviewed and understood
+- [ ] Code changes implemented according to design
+- [ ] All test cases created and passing
+- [ ] Evidence provided in GitHub issue
+- [ ] PR feedback addressed (if applicable)
+
+### ✅ CRITICAL FINAL STEPS
+- [ ] **Issue status updated from `status:wip` to `status:needs-review`**
+- [ ] **Status change verified successfully**
+- [ ] **User notified that issue is ready for review**
+
+**🚨 FAILURE TO COMPLETE THE STATUS UPDATE MEANS THE WORK IS NOT DONE! 🚨**

package/.ai-agents/workflows/resolve.md

@@ -0,0 +1,152 @@
+# Issue Resolution Workflow
+
+## INTENT
+To provide a systematic approach to resolving issues from development through merge verification and cleanup, ensuring no work is lost and all changes are properly integrated into the main codebase.
+
+## PRINCIPLES
+- **Verification First**: Always verify merges before closing issues
+- **Complete Cleanup**: Remove all traces of feature branches
+- **No Work Loss**: Prevent incidents like Issue #112 through proper verification
+- **Systematic Process**: Follow established steps in order
+- **Evidence-Based**: Provide concrete verification of completion
+
+## CRITICAL DEPENDENCY
+**This workflow MUST be used in conjunction with `.ai-agents/rules/merge-requirements.md`** which contains:
+- **Pre-Push Workflow** (for feature branches during development)
+- **PR Description Template** (for PR creation)
+- **Final Merge Process** (for merging to master - used in this workflow)
+- **Conflict Resolution Guide** (for resolving conflicts during rebase)
+
+**Note**: The Pre-Push workflow applies to feature branch development. This resolve.md workflow focuses on the **final merge into master** and uses the Final Merge Process from merge-requirements.md.
+
+## RESOLUTION WORKFLOW
+
+**PREREQUISITE**: This workflow assumes:
+- ✅ All development work is complete
+- ✅ All tests have been run on the feature branch
+- ✅ PR has been created and approved
+- ✅ Feature branch is ready for merge
+
+### 1. Execute the Merge
+Use GitHub MCP to merge the PR:
+
+```bash
+# Merge the PR using GitHub MCP
+gh pr merge <PR_NUMBER> --rebase
+```
+
+**If conflicts occur during merge:**
+- GitHub will reject the merge with conflict details
+- Use `gh pr view <PR_NUMBER>` to see conflict details
+- Resolve conflicts intelligently using the **Conflict Resolution Guide** from `merge-requirements.md`
+- Keep master's base implementation and add your enhancements on top
+- Test the resolution: `npm run build && npm run test-smoke test*.ts`
+- Push the resolved changes and retry the merge
+
+### 2. Wait for Master CI Smoke Tests
+After successful merge, monitor the master branch CI:
+- Check GitHub Actions for the master branch
+- Wait for smoke tests to complete successfully
+- **CRITICAL**: Do not proceed until CI passes
+
+### 3. Verify Code Made it to Master
+**MANDATORY**: Confirm the merge was successful:
+```bash
+# Check PR is merged, not just closed
+gh pr view <PR_NUMBER> --json merged
+
+# Verify merge commit in master
+git fetch origin master
+git log origin/master --oneline | grep "PR #<PR_NUMBER>"
+
+# Verify files in master
+git show origin/master:path/to/expected/file
+```
+
+### 4. Handle CI Failures
+**If master CI fails:**
+- Debug the issue immediately
+- Fix the problem in the feature branch
+- Push the fix and re-merge
+- Repeat until CI passes
+- **Do not close the issue until CI passes**
+
+### 5. Confirm all good
+**Only after CI passes successfully:**
+
+**Add Resolution Comment if conflicts with master had to be resolved:**
+- Add a comment to the issue using GitHub MCP:
+```bash
+gh issue comment <ISSUE_NUMBER> --body "✅ Encountered conflicts during merge with master.
+
+**Conflict Resolution Notes:**
+- Resolved conflicts in: [list files with conflicts]
+- Resolution strategy: [explain what was done]
+- Kept master's base implementation and added enhancements on top"
+```
+
+**Verify the following:**
+1. ✅ **PR Status**: PR shows "merged" status, not just "closed"
+2. ✅ **Merge Commit**: Verify merge commit exists in master
+3. ✅ **Files in Master**: Confirm expected files are present in master
+
+### **Verification Commands**
+```bash
+# Check PR is merged, not just closed
+gh pr view <PR_NUMBER> --json merged
+
+# Verify merge commit in master
+git fetch origin master
+git log origin/master --oneline | grep "PR #<PR_NUMBER>"
+
+# Verify files in master
+git show origin/master:path/to/expected/file
+```
+
+**CRITICAL**: Do not close the issue until merge verification passes. This prevents work loss incidents 
+
+### 6. Issue Resolution & Cleanup
+**Close the Issue:**
+- Close the issue with resolution comment using GitHub MCP:
+```bash
+gh issue close <ISSUE_NUMBER> --comment "✅ Issue resolved and merged to master. CI smoke tests passed."
+```
+
+**Cleanup Branch:**
+    ```bash
+    npx tsx .ai-agents/scripts/cleanup-branch.ts
+    ```
+
+### 7. Celebrate
+- Say Hoorah !
+
+
+## EXAMPLES
+
+### Good: Proper Resolution Process
+```
+Issue #84: "Fix API integration timeout"
+PREREQUISITE: ✅ Development complete, tests passed, PR approved
+1. ✅ Merge: Used `gh pr merge <PR_NUMBER> --rebase`
+2. ✅ Conflicts: Resolved conflicts intelligently (kept master's base)
+3. ✅ CI Wait: Waited for master CI smoke tests to pass
+4. ✅ Verification: Confirmed merge commit exists in master
+5. ✅ Schema: Cleaned up database schema BEFORE branch deletion
+6. ✅ Comment: Added resolution comment with conflict resolution notes
+7. ✅ Close: Closed issue with resolution comment using `gh issue close`
+8. ✅ Cleanup: Deleted branch after schema cleanup
+Result: Complete resolution with no work loss
+```
+
+### Bad: Incomplete Resolution
+```
+Issue #84: "Fix API integration timeout"
+PREREQUISITE: ✅ Development complete, tests passed, PR approved
+1. ✅ Merge: Used `gh pr merge <PR_NUMBER> --rebase`
+2. ❌ Skip: Didn't wait for master CI smoke tests
+3. ❌ Skip: Didn't verify merge commit exists
+4. ❌ Skip: Didn't clean up schema BEFORE branch deletion
+5. ❌ Skip: Didn't add resolution comment with conflict notes
+6. ❌ Close: Closed issue without CI verification
+Result: Work lost, schema not cleaned up, CI may have failed
+```

package/.ai-agents/workflows/retrospect.md

@@ -0,0 +1,84 @@
+# Retrospective Creation
+
+## INTENT
+To capture learnings and insights from completed issues, enabling continuous improvement and preventing future similar problems through systematic analysis and documentation.
+
+## PRINCIPLES
+- Every completed issue requires a retrospective
+- Focus on root causes, not just symptoms
+- Document both successes and failures
+- Create actionable prevention measures
+- Share learnings with other agents
+
+## WORKFLOW
+
+1. **Label the issue** `status:wip` and remove `status:complete`
+2. **Create retrospective document** using the template
+3. **Complete retrospective** following the quality checklist
+4. **When ready for review**, flip issue to `status:needs-review` and remove `status:wip`
+5. **Iterate** until the PR is approved
+
+## RETROSPECTIVE TRIGGERS
+
+- **All Issues**: Every completed issue requires a retrospective
+- **Complex Issues (>3 iterations)**: Must create detailed retrospective
+- **Process Violations**: Any workflow rule violations require detailed retrospectives
+- **Work Loss Incidents**: Any incidents where work is lost require detailed retrospectives
+
+## RETROSPECTIVE CREATION PROCESS
+
+### 1. Create Retrospective File
+- **File path**: `retrospectives/issue-{issue-number}-{kebab-title}-postmortem.md`
+- **Template**: Use `.ai-agents/templates/retrospective/RETROSPECTIVE-TEMPLATE.md` as the base
+- **Copy template**: Copy the template file and fill in the placeholders
+
+### 2. Root Cause Analysis
+- Identify underlying causes, not just symptoms
+- Document what went wrong and why
+- Analyze process failures and human errors
+- Look for patterns that could affect other issues
+
+### 3. Prevention Measures
+- Document specific actions to prevent recurrence
+- Update rules and workflows based on learnings
+- Share solutions with other agents through issue comments
+- Identify process improvements
+
+### 4. Document Success Factors
+- What worked well and why
+- Best practices discovered
+- Tools and techniques that helped
+- Lessons that can be applied to future issues
+
+## RETROSPECTIVE QUALITY CHECKLIST
+
+Before marking retrospective complete, verify:
+- [ ] Root cause analysis completed (not just symptoms)
+- [ ] Prevention measures documented
+- [ ] Process improvements identified
+- [ ] Success factors captured
+- [ ] Action items are specific and actionable
+- [ ] Template followed completely
+- [ ] File saved in correct location
+- [ ] All placeholders replaced with actual content
+- [ ] Timeline of events is accurate and complete
+- [ ] Lessons learned are actionable
+
+## EXAMPLES
+
+### Good: Comprehensive Retrospective
+```
+- Root cause: "Agent didn't verify workspace directory before file operations"
+- Prevention: "Added mandatory pwd check before any file operation"
+- Learning: "Workspace violations are common without explicit safeguards"
+- Git Issues Suggested: "Update local-development.mdc with verification checklist"
+```
+
+### Bad: Surface-Level Retrospective
+```
+- Problem: "File created in wrong location"
+- Solution: "Moved file to correct location"
+- Learning: "Need to be more careful"
+```
+
+**CRITICAL**: Do not close the issue until retrospective is created, reviewed, and approved.

package/.ai-agents/workflows/spec.md

@@ -0,0 +1,103 @@
+# Specification Phase
+
+## INTENT
+To create comprehensive, detailed product specifications that clarify the Why, What and User Experiences for new features
+
+## PRINCIPLES
+- **Start with the User**: Understand the user's needs and experiences before implementing
+- **User Experience Matters**: Focus on creating a great user experience right from the beginning
+- **Validation Criteria**: Define clear validation criteria to ensure the feature meets user needs
+
+## SPECIFICATION WORKFLOW
+
+### Step 1: Issue Identification
+Ask for {issue_number} (and optional {slug}). Get slug details using GitHub MCP.
+
+### Step 2: Phase Initiation
+Label the issue 'phase:spec' (GitHub Action will automatically label the issue `status:wip` and update the existing draft PR)
+
+### Step 3: Environment Setup
+**IMPORTANT**: The user has already run `prep-issue.sh` which has:
+- ✅ Created the feature branch
+- ✅ Checked out the branch
+- ✅ Created draft PR
+- ✅ Indexed the codebase with Serena
+- ✅ Opened the editor in the prepared workspace
+
+You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
+
+### Step 4: Work Location
+You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working.
+
+### Step 5: Pre-Creation Validation
+Before creating any specification document, agents MUST:
+
+1. **Verify Template Selection**:
+   - Use `.ai-agents/templates/specs/FEATURESPEC-TEMPLATE.md`
+   
+2. **Validate Naming Convention**:
+   - Format: `docs/feature specs/{issue_number}-{kebab-title}.md`
+   - Example: `docs/feature specs/228-improve-token-refresh.md`
+   - NO other naming patterns allowed
+
+3. **Template Compliance Check**:
+   - Read and understand the template first
+   
+### Step 6: Specification Document Creation
+Your work entails the following:
+- Create docs/feature specs/{issue_number}-{slug}.md.  
+- Understand the issue, the existing product functionality. Use playwright for manually looking through the UI if needed.
+- Research and document the why, what and user experiences for the feature.
+- Create UI mockups for the feature under `docs/feature specs/mocks/` directory. Make them good looking and user friendly.
+- Create a validation plan for the feature. You will be validating what the engineers build.
+
+### Step 7: Specification Creation Checklist
+Before commiting your work, verify:
+- [ ] Correct template used
+- [ ] Proper file naming: `{issue_number}-{kebab-title}.md`
+- [ ] All template sections completed
+- [ ] No placeholder text remaining
+- [ ] Issue labeled `phase:spec`
+- [ ] Working in correct branch
+- [ ] File saved in `docs/feature specs/` directory
+- [ ] UI mocks, if needed, created in `docs/feature specs/mocks/` directory
+- [ ] Validation plan created
+
+### Step 8: Submit for Review
+- Commit and sync your work
+- Label the issue 'status:needs-review' and remove 'status:wip'
+- Update the PR with a comment to include evidence - Use template `.ai-agents/templates/evidence/Spec-Evidence.md`
+- Follow `.ai-agents/rules/pr-workflow-completeness.md`
+
+### Step 9: Iteration
+If workflow actions or reviewer feedback indicates more work is needed:
+- Label the issue 'status:wip' and remove 'status:needs-review'
+- Go back to Step 6 and iterate until PR is approved
+
+## EXAMPLES
+
+### Good: Comprehensive Specification Process
+```
+Issue #228: "Improve token refresh mechanism"
+1. ✅ Identified: Issue #228, slug: "improve-token-refresh"
+2. ✅ Phase: Set phase:spec, PR created
+3. ✅ Environment: User ran prep-issue.sh, ready to work
+4. ✅ Location: Working in prepared workspace with Serena indexing
+5. ✅ Specification: Created docs/feature specs/228-improve-token-refresh.md
+6. ✅ Template: Used FEATURESPEC-TEMPLATE.md
+7. ✅ Review: Set status:needs-review, provided evidence
+8. ✅ Iteration: Incorporated feedback, updated specification
+Result: Clear, actionable specification document
+```
+
+### Bad: Incomplete Specification Process
+```
+Issue #228: "Improve token refresh mechanism"
+1. ✅ Identified: Issue #228
+2. ❌ Skip: Didn't set phase:spec
+3. ❌ Skip: Didn't create branch
+4. ❌ Skip: Started without proper template
+5. ❌ Skip: No UI mockups created
+6. ❌ Skip: No validation plan
+Result: Incomplete, unclear specification
+```

package/.ai-agents/workflows/test.md

@@ -0,0 +1,90 @@
+# Testing Phase
+
+## INTENT
+To create comprehensive test coverage that accurately reproduces issues and validates solutions, ensuring robust testing through proper test structure, failure verification, and systematic test execution.
+
+## PRINCIPLES
+- **Test-Driven**: Write tests that reproduce the issue before fixing
+- **Comprehensive Coverage**: Ensure all scenarios are tested
+- **Failure Verification**: Confirm tests fail before implementation
+- **Proper Structure**: Use established test patterns and frameworks
+- **Systematic Execution**: Follow consistent testing procedures
+
+## TESTING WORKFLOW
+
+### Step 1: Issue Identification
+Ask for {issue_number} (and optional {slug}); confirm target branch feature/{issue_number}-{slug}.
+
+### Step 2: Phase Initiation
+Label the issue 'phase:tests'. (GitHub Action will automatically label the issue `status:wip` and update the existing draft PR)
+
+### Step 3: Environment Setup
+**IMPORTANT**: The user has already run `prep-issue.sh` which has:
+- ✅ Created the feature branch
+- ✅ Checked out the branch
+- ✅ Created draft PR
+- ✅ Indexed the codebase with Serena
+- ✅ Opened the editor in the prepared workspace
+
+You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
+
+### Step 4: Work Location
+You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working. 
+
+### Step 5: Testing Work
+Your work entails the following:
+
+- Review the RFC associated with this issue.
+- Determine whether tests need to be added to an existing test suite, or a new one needs to be created.
+- **CRITICAL: Write INTEGRATION tests that demonstrate the REAL USER SCENARIO**
+  - Test the actual end-to-end user experience, not unit tests for hypothetical fixes
+  - Use real services and APIs where possible (not mocks)
+  - Verify the issue occurs in the real system as described in the issue
+  - Example: For messaging threading issues, actually send messages and verify they appear as new messages vs replies
+- Run the test cases to ensure they fail (demonstrating the issue exists)
+- Flip issue to 'status:needs-review' and remove 'status:wip'
+
+**❌ DO NOT:**
+- Write unit tests for code that doesn't exist yet
+- Test hypothetical fixes or solutions
+- Create mock tests that don't use real services
+- Test individual components in isolation
+
+**✅ DO:**
+- Test the complete user workflow end-to-end
+- Use real APIs and services when possible
+- Verify the actual problem described in the issue
+- Create tests that will pass AFTER the fix is implemented
+
+### Step 6: Iteration
+If workflow actions or reviewer feedback indicates more work is needed, ensure the issue is set back to `status:wip` and continue working as above.
+
+## EXAMPLES
+
+### Good: Comprehensive Testing Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84, branch feature/84-fix-api
+2. ✅ Phase: Set phase:tests, PR created
+3. ✅ Environment: User ran prep-issue.sh, ready to work
+4. ✅ Location: Working in prepared workspace with Serena indexing
+5. ✅ RFC Review: Read docs/rfcs/84-fix-api-timeout.md
+6. ✅ Analysis: Determined need to add timeout tests
+7. ✅ Test Creation: Added test cases for timeout scenarios
+8. ✅ Failure Verification: Confirmed tests fail before fix
+9. ✅ Review: Set status:needs-review
+10. ✅ Iteration: Incorporated feedback, updated tests
+Result: Comprehensive test coverage with proper structure
+```
+
+### Bad: Incomplete Testing Process
+```
+Issue #84: "Fix API integration timeout"
+1. ✅ Identified: Issue #84
+2. ❌ Skip: Didn't review RFC
+3. ❌ Skip: Started testing without understanding requirements
+4. ❌ Skip: No test cases written
+5. ❌ Skip: Didn't verify tests fail
+6. ❌ Skip: No test structure followed
+Result: Incomplete, ineffective testing
+```

package/.cursor/rules/cursor-rules.mdc

@@ -0,0 +1,8 @@
+---
+description: Centralized AI agent rules for Cursor
+alwaysApply: true
+---
+
+# Cursor AI Agent Rules
+
+Thoroughly review `.ai-agents/agent-guardrails.md`

package/.cursor/rules/design.mdc

@@ -0,0 +1,4 @@
+---
+alwaysApply: false
+---
+Follow instructions in `.ai-agents/workflows/design.md`

package/.cursor/rules/implement.mdc

@@ -0,0 +1,6 @@
+---
+
+alwaysApply: false
+---
+
+Follow instructions in `.ai-agents/workflows/implement.md`

package/.cursor/rules/resolve.mdc

@@ -0,0 +1,5 @@
+---
+alwaysApply: false
+---
+
+Follow instructions in `.ai-agents/workflows/resolve.md`

package/.cursor/rules/retrospect.mdc

@@ -0,0 +1,4 @@
+---
+alwaysApply: false
+---
+Follow instructions in `.ai-agents/workflows/retrospect.md`

package/.cursor/rules/spec.mdc

@@ -0,0 +1,4 @@
+---
+alwaysApply: false
+---
+Follow instructions in `.ai-agents/workflows/spec.md`

package/.cursor/rules/test.mdc

@@ -0,0 +1,5 @@
+---
+alwaysApply: false
+---
+
+Follow instructions in `.ai-agents/workflows/test.md`

package/.windsurf/rules/windsurf-rules.md

@@ -0,0 +1,7 @@
+---
+trigger: always_on
+---
+
+# Windsurf AI Agent Rules
+
+Thoroughly review `.ai-agents/agent-guardrails.md`

package/.windsurf/workflows/resolve-issue.md

@@ -0,0 +1,6 @@
+---
+description: Resolve issue (once confirmed complete)
+auto_execution_mode: 3
+---
+
+Follow instructions in `.ai-agents/workflows/resolve.md`

package/.windsurf/workflows/retrospect.md

@@ -0,0 +1,6 @@
+---
+description: Resolve issue (once confirmed complete)
+auto_execution_mode: 3
+---
+
+Follow instructions in `.ai-agents/workflows/retrospect.md`

package/.windsurf/workflows/start-design.md

@@ -0,0 +1,6 @@
+---
+description: Start working on the issue
+auto_execution_mode: 3
+---
+
+Follow instructions in `.ai-agents/workflows/design.md`