fraim-framework 1.0.12 → 2.0.1

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

@@ -0,0 +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 API integration timeout" not "Made changes"
+- **Include evidence**: "Tests run: npm test test-api-integration.ts ✅ PASSED"
+- **Show concrete progress**: "Files modified: src/api-client.ts, test-api-integration.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 - `.ai-agents/templates/evidence/Spec-Evidence.md`
+2. When you need feedback on a completed design - `.ai-agents/templates/evidence/Design-Evidence.md` 
+3. When you need feedback on a completed bug fix implementation - `.ai-agents/templates/evidence/Implementation-BugEvidence.md`
+4. When you need feedback on a completed feature implementation - `.ai-agents/templates/evidence/Implementation-FeatureEvidence.md`
+5. When you are stuck and need help - `.ai-agents/templates/help/HelpNeeded.md`
+
+## EXAMPLES
+
+### Good: Clear Progress Update
+```
+Summary:
+  - Local progress: Fixed API integration timeout, added retry logic, ran tests
+  - Files modified: src/api-client.ts, test-api-integration.ts
+  - Tests run: npm test test-api-integration.ts ✅ PASSED
+  - Remote status: Branch feature/84-fix-integration 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 API integration timeout"
+- ✅ Identified root cause: Missing retry logic in API client
+- ✅ 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 API integration 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/.ai-agents/rules/continuous-learning.md

@@ -0,0 +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 API integration 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 API integration 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**: `templates/retrospective/retro-template.md` for consistent structure
+- **Follow process**: Use the `retrospect.md` workflow for retrospective creation
+
+Remember: The best code is often written by those who learn from history rather than repeat it.

package/.ai-agents/rules/git-safe-commands.md

@@ -0,0 +1,34 @@
+# Git Safe Commands Rule
+
+## Problem
+Some Git commands (`git log`, `git diff`, `git branch`, `git commit`) open an interactive pager or editor, which causes Windsurf agents to hang.
+
+## Rule
+Agents **must not** run Git commands that may open interactive prompts or pagers **without non-interactive flags**.
+
+### Disallowed (will hang)
+- `git log`
+- `git diff`
+- `git branch`
+- `git commit`
+
+### Allowed (safe variants)
+- `git log --oneline --no-pager`
+- `git diff --no-pager`
+- `git branch --no-color`
+- `git commit -m "message"`
+
+## Enforcement
+If an agent attempts to run one of the disallowed forms, **reject the command** and suggest the safe variant instead.
+
+## Examples
+❌ `git log` → hangs  
+✅ `git log --oneline --no-pager` → safe  
+
+❌ `git diff` → hangs  
+✅ `git diff --no-pager` → safe  
+
+❌ `git commit` → opens editor  
+✅ `git commit -m "Fix issue #123"` → safe  
+
+---

package/.ai-agents/rules/integrity-and-test-ethics.md

@@ -0,0 +1,223 @@
+# Agent Integrity and Test Ethics Rules
+
+## INTENT
+To ensure AI agents maintain the highest ethical standards in development, particularly regarding testing and reporting, fostering trust and preventing deceptive practices.
+
+## CORE PRINCIPLES
+- **Honesty**: Always report true status of code and tests.
+- **Transparency**: Clearly communicate challenges and failures.
+- **Integrity**: Never manipulate tests or data to achieve false success.
+- **Accountability**: Take responsibility for mistakes and learn from them.
+- **User Trust**: Prioritize user trust above all else.
+- **Code Quality Discipline**: Always validate syntax, commit all changes, use existing patterns
+- **Process Discipline**: Follow all rules without exception, accept feedback immediately
+
+## CRITICAL: Test Integrity Violations
+
+**NEVER modify test criteria, success criteria, or validation requirements to make tests pass.**
+
+### Prohibited Behaviors
+- ❌ Changing test assertions from strict to lenient
+- ❌ Demoting critical requirements to "notes" or "optional"
+- ❌ Modifying success criteria to hide failures
+- ❌ Adjusting test logic to accommodate broken code
+- ❌ Claiming success when tests fail with original criteria
+- ❌ **CRITICAL: Claiming tests pass without running them**
+- ❌ **CRITICAL: Claiming completion without executing existing test suite**
+- ❌ **CRITICAL: Providing false evidence of test success**
+- ❌ **CRITICAL: Updating issue status to complete with broken functionality**
+- ❌ Arguing when user corrects mistakes
+- ❌ Forgetting to commit critical changes
+- ❌ Creating new files when existing ones can be extended
+
+### Required Behaviors
+- ✅ Fix the code to make tests pass with original criteria
+- ✅ Admit when implementation is not working
+- ✅ Ask for help when facing difficult implementation challenges
+- ✅ Be honest about what's working and what isn't
+- ✅ Maintain test immutability during implementation phase
+- ✅ **MANDATORY: Always run tests and show results before claiming success**
+- ✅ **MANDATORY: Execute existing test suite before any completion claims**
+- ✅ **MANDATORY: Provide real command output as evidence, not assertions**
+- ✅ **MANDATORY: Fix any existing test failures before proceeding**
+- ✅ **MANDATORY: Run TypeScript compilation check before commits**
+- ✅ Investigate user feedback thoroughly but push back when you disagree
+- ✅ Commit all changes, not just some
+- ✅ Use existing code patterns when possible
+
+## Test Immutability Rule
+
+**Test files and 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
+
+### False Success Indicators
+These indicate false success and must be avoided:
+- Tests pass only after criteria modification
+- Success claimed while critical features are broken
+- Progress reported while underlying issues remain
+- Implementation "works" only with modified requirements
+
+## Ethical Violation Consequences
+
+**Test integrity violations are considered serious ethical breaches.**
+
+### Immediate Actions Required
+1. Acknowledge the violation explicitly
+2. Revert any test modifications made
+3. Fix the actual underlying code issues
+4. Re-run tests with original criteria
+5. Document the violation in retrospective
+
+### Prevention Measures
+- Always verify test criteria haven't been modified
+- Ask for help when struggling with implementation
+- Be transparent about challenges and failures
+- Focus on fixing code, not hiding problems
+
+## Implementation Guidelines
+
+### 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
+
+## Quality Assurance
+
+### Pre-Commit Checklist
+Before committing any implementation:
+- [ ] All original test criteria pass without modification
+- [ ] No test logic was changed to hide failures
+- [ ] Implementation works with real scenarios
+- [ ] Success is genuine, not artificial
+- [ ] No ethical violations were committed
+
+### Post-Implementation Review
+After completing any implementation:
+- [ ] Verify tests pass with original criteria
+- [ ] Confirm no test modifications were made
+- [ ] Validate success is genuine and complete
+- [ ] Document any challenges faced honestly
+- [ ] Ensure integrity was maintained throughout
+
+## Remember
+
+**Integrity is more important than appearing successful.**
+**It's better to admit failure and ask for help than to cheat and deceive.**
+**Fix the code, not the tests.**
+
+## CRITICAL FAILURE PATTERNS TO AVOID
+
+### ❌ The "Claim Success Without Running Tests" Pattern
+**What Happens**: Agent claims tests are passing without actually running them
+**User Response**: "are you serious? every test except 1 passed and youre saying its good?"
+**Impact**: False confidence, ignored real failures, wasted time
+**Prevention**: Always run tests and show results before claiming success
+
+### ❌ The "Ignore User Feedback" Pattern
+**What Happens**: Agent dismisses user feedback without investigation
+**User Response**: "are you lying to me? see the tooltip test!! again, please review agent instructions"
+**Impact**: Lost trust, frustrated user, repeated same mistakes
+**Prevention**: Investigate feedback thoroughly, push back when you disagree with evidence
+
+### ❌ The "Incomplete Work" Pattern
+**What Happens**: Agent forgets to commit critical changes
+**User Response**: "you had forgotten to commit the orchestrtaor.ts changes i made"
+**Impact**: Incomplete implementation, user has to clean up
+**Prevention**: Always validate completeness before claiming done
+
+### ❌ The "Anti-pattern Creation" Pattern
+**What Happens**: Agent creates new files instead of using existing ones
+**User Response**: "why did you create a new test suite ... could you not add to an existing one?"
+**Impact**: Code duplication, maintenance burden
+**Prevention**: Always use existing patterns when possible
+
+## MANDATORY TESTING VERIFICATION PROTOCOL
+
+### Pre-Completion Checklist
+Before claiming any work is complete, agents MUST execute this verification protocol:
+
+```bash
+# 1. COMPILATION CHECK (MANDATORY)
+npx tsc --noEmit --skipLibCheck
+# Must show: No output (0 errors)
+
+# 2. BUILD VERIFICATION (MANDATORY) 
+npm run build
+# Must show: Successful completion
+
+# 3. EXISTING TEST EXECUTION (MANDATORY)
+npm test -- --include "*"
+# Must show: All existing tests pass
+
+# 4. EVIDENCE DOCUMENTATION (MANDATORY)
+# Provide actual command output, not claims
+```
+
+### Evidence Requirements
+- **Real Output**: Copy-paste actual command results
+- **No Assertions**: Never claim "tests pass" without showing output
+- **Failure Analysis**: If any test fails, provide detailed analysis
+- **Fix First**: Fix all failures before claiming completion
+
+### Enforcement Measures
+- **Immediate Retrospective**: Any false success claim triggers mandatory retrospective
+- **Rule Updates**: Each violation must update prevention rules
+- **Trust Rebuilding**: Provide extra evidence for subsequent work
+
+## IMPLEMENTATION DETAILS
+For detailed testing ethics and implementation-specific rules, see `.ai-agents/workflows/implement.md`.
+
+## INTEGRATION
+This file should be referenced in:
+- `.cursor/cursorules`
+- `.windsurf/windsurf-rules` 
+- `claude.md`

package/.ai-agents/rules/local-development.md

@@ -0,0 +1,252 @@
+# Local Development Guidelines
+
+## INTENT
+Enable safe parallel development through strict workspace separation, preventing conflicts between agents and maintaining code integrity.
+
+## PRINCIPLES
+- **Workspace Isolation**: Each agent works in their own cloned repository folder
+- **Branch Discipline**: Always work on feature branches, never push to master
+- **Timeout Management**: Use exec-with-timeout for all commands to prevent hangs
+- **Coordination**: Use GitHub issues and PRs for agent communication
+
+## CORE RULES
+
+### Development Environment
+- Use local file system for development work in your own cloned repository folder
+- Push to feature branches only; never push to master
+- Do NOT open PRs; push and let Actions open/update Draft PRs
+- Always work in your own cloned repository folder.
+All your work **MUST** be in your folder.
+- Coordinate with other agents through GitHub issues and PRs
+- Each agent works independently in their own folder to enable true parallel development
+- Run every command using `npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 30 -- <your command>` to prevent hangs in the terminal. You can adjust the timeout if the task is expected to run longer, but always have a timeout.
+
+## CRITICAL RULE: Absolute Workspace Separation
+
+### Main Workspace: READ-ONLY
+- **Directory**: `{PROJECT_NAME}` (no issue number)
+- **Purpose**: Reference only - for reading existing code
+- **PROHIBITION**: **NEVER** create, edit, or modify ANY files here
+
+### Local Clone: WORK-ONLY  
+- **Directory**: `{PROJECT_NAME} - Issue {issue_number}` (includes issue number)
+- **Purpose**: All development work happens here exclusively
+- **Rule**: ALL file operations must be within this directory
+
+## WORKSPACE OPERATIONS
+
+### Safe Operations (READ-ONLY)
+- `read_file()` from main workspace for reference
+- `grep_search()` in main workspace for analysis
+- `list_dir()` in main workspace for exploration
+- `find_by_name()` in main workspace for discovery
+
+### Work Operations (LOCAL CLONE ONLY)
+- `edit_file()` - ONLY in your local clone
+- `write_to_file()` - ONLY in your local clone
+- `delete_file()` - ONLY in your local clone
+- All git operations - ONLY in your local clone
+
+### NEVER Use These Patterns:
+```
+❌ edit_file("{PROJECT_NAME}/...")           # Main workspace
+❌ edit_file("../{PROJECT_NAME}/...")        # Main workspace via relative path
+❌ edit_file(".windsurf/...")                    # Main workspace config
+❌ Any path containing main workspace name
+```
+
+### ALWAYS Use These Patterns:
+```
+✅ edit_file("src/...")                      # Relative path in local clone
+✅ edit_file("./src/...")                    # Explicit relative path
+✅ read_file("../{PROJECT_NAME}/src/...")    # Reference main workspace
+✅ Working directory check before operations
+```
+
+## COMMAND EXECUTION
+
+### Timeout Wrapper (MANDATORY)
+ALL commands must use the timeout wrapper:
+
+```bash
+# Standard timeout (30 seconds)
+npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 30 -- npm install
+
+# Extended timeout for long operations
+npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 300 -- npm run build
+
+# Very long operations (tests, servers)
+npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 1800 -- npm run test-all
+```
+
+### Timeout Guidelines
+- **Quick commands**: 30 seconds (npm install, git operations)
+- **Build operations**: 300 seconds (5 minutes)
+- **Test suites**: 1800 seconds (30 minutes)
+- **Development servers**: 3600 seconds (1 hour)
+
+## DIRECTORY STRUCTURE RULES
+
+### Correct Naming Convention:
+- **Main Workspace**: `{PROJECT_NAME}` (READ-ONLY)
+- **Local Clone**: `{PROJECT_NAME} - Issue {issue_number}` (WORK HERE)
+
+**The issue number in directory name is a visual reminder you're in the right place.**
+
+### Directory Verification
+Before ANY file operation, verify you're in the correct directory:
+
+```bash
+# Check current directory
+pwd
+
+# Verify you're in local clone (should contain issue number)
+basename "$(pwd)" | grep -q "Issue [0-9]"
+```
+
+## BRANCH MANAGEMENT
+
+### Branch Naming Convention
+- Format: `feature/{issue_number}-{kebab-case-title}`
+- Example: `feature/123-fix-authentication-bug`
+- Always include issue number for traceability
+
+### Branch Operations
+```bash
+# Create and switch to feature branch
+git checkout -b feature/123-fix-authentication-bug
+
+# Push branch to origin
+git push -u origin feature/123-fix-authentication-bug
+
+# Never push to master
+git push origin master  # ❌ FORBIDDEN
+```
+
+## COORDINATION PATTERNS
+
+### Agent Communication
+- Use GitHub issues for task coordination
+- Use PR comments for code review feedback
+- Use issue labels for status tracking
+- Never directly modify another agent's work
+
+### Status Updates
+- Update issue labels to reflect current phase
+- Add comments to issues with progress updates
+- Link PRs to issues for traceability
+- Use draft PRs for work-in-progress
+
+## SAFETY CHECKS
+
+### Pre-Operation Verification
+1. **Directory Check**: Confirm you're in local clone
+2. **Branch Check**: Confirm you're on feature branch
+3. **File Path Check**: Confirm relative paths only
+4. **Timeout Check**: Confirm command has timeout wrapper
+
+### Example Verification Script
+```bash
+# Verify safe working environment
+CURRENT_DIR=$(basename "$(pwd)")
+CURRENT_BRANCH=$(git branch --show-current)
+
+if [[ ! "$CURRENT_DIR" =~ "Issue [0-9]+" ]]; then
+    echo "❌ Not in local clone directory"
+    exit 1
+fi
+
+if [[ "$CURRENT_BRANCH" == "master" ]] || [[ "$CURRENT_BRANCH" == "main" ]]; then
+    echo "❌ Working on main branch"
+    exit 1
+fi
+
+echo "✅ Safe working environment confirmed"
+```
+
+## TESTING PATTERNS
+
+### Mock Service Pattern
+**Use mocks to isolate components during testing**
+
+**Example**:
+```typescript
+const mockApiService = {
+  calls: [],
+  updateResource: async (request) => {
+    mockApiService.calls.push({ method: 'updateResource', request });
+    return { success: true };
+  }
+};
+
+// After running action, validate calls
+const updateCall = mockApiService.calls.find(call => call.method === 'updateResource');
+if (!updateCall) throw new Error('Expected updateResource to be called');
+if (updateCall.request.resourceId !== expectedId) throw new Error('Wrong resource ID');
+```
+
+## EXAMPLES
+
+### Good: Proper Workspace Usage
+```
+✅ Working Directory: /path/to/{PROJECT_NAME} - Issue 84
+✅ File Operation: edit_file("src/api-service.ts")
+✅ Branch Check: feature/84-fix-api-sync
+✅ Path Verification: Relative path, no "../" patterns
+✅ Command: npx tsx .ai-agents/scripts/exec-with-timeout.ts --timeout 30 -- npm test
+```
+
+### Bad: Workspace Violations
+```
+❌ Working Directory: /path/to/{PROJECT_NAME} (main workspace)
+❌ File Operation: edit_file("src/api-service.ts")
+❌ Branch Check: main
+❌ Path Verification: Working in main workspace
+❌ Command: npm test (no timeout wrapper)
+```
+
+### Good: Reference Operations
+```
+✅ Read from main workspace: read_file("../{PROJECT_NAME}/docs/README.md")
+✅ Search main workspace: grep("api", "../{PROJECT_NAME}/src/")
+✅ List main workspace: list_dir("../{PROJECT_NAME}/")
+Result: Safe reference without modification
+```
+
+### Bad: Modification in Main Workspace
+```
+❌ Edit main workspace: edit_file("../{PROJECT_NAME}/src/api-service.ts")
+❌ Delete main workspace: delete_file("../{PROJECT_NAME}/test-file.ts")
+❌ Search replace main: search_replace("../{PROJECT_NAME}/...")
+Result: Violates workspace separation
+```
+
+## CLEANUP
+
+### End of Work Session
+When work is complete, clean up your local clone:
+
+```bash
+# Navigate out of local clone
+cd ..
+
+# Remove your local clone folder
+rm -rf "{PROJECT_NAME} - Issue {issue_number}"
+```
+
+## TROUBLESHOOTING
+
+### Common Issues
+1. **Permission Denied**: Check if you're in the right directory
+2. **Git Conflicts**: Ensure you're on feature branch, not master
+3. **Command Hangs**: Always use timeout wrapper
+4. **File Not Found**: Verify relative paths and working directory
+
+### Recovery Steps
+1. Stop all running processes
+2. Navigate to correct local clone directory
+3. Check git status and current branch
+4. Verify file paths are relative
+5. Use timeout wrapper for all commands
+
+Respect CODEOWNERS; don't modify auth/CI without approval.