.cursorrules

# Cursor Rules for claude-workflows
# These rules help prevent common issues and ensure consistent development practices

## Terminal Command Best Practices

### ZSH Escaping Issues - CRITICAL
- **ALWAYS** use single quotes for simple strings in terminal commands
- **AVOID** complex multi-line strings with special characters in terminal commands
- **USE** separate files for complex content (like release notes) instead of inline strings
- **PREFER** simple commands over complex ones with embedded content
- **NEVER** use emojis or special characters in inline git commands
- **ALWAYS** test simple commands first before complex ones

### Git Commands - Safe Patterns
- Use `git tag v1.0.0` instead of `git tag -a v1.0.0 -m "complex message"`
- Create release notes in separate files, then use `--notes-file` flag
- Avoid inline commit messages with special characters
- Use `git commit -m "simple message"` for commits
- Use `git push origin branch-name` for pushes

### GitHub CLI Commands - Safe Patterns
- Use `gh release create v1.0.0 --title "Simple Title" --notes-file release-notes.md`
- Avoid complex inline descriptions with emojis and special formatting
- Create temporary files for complex content, then delete them
- Use `gh pr create --title "Simple Title" --body-file pr-description.md`
- Use `gh release edit v1.0.0 --title "Simple Title" --notes-file notes.md`

### Safe Command Patterns
```bash
# ✅ Good - Simple, no escaping issues
git tag v1.0.0
git push origin v1.0.0
gh release create v1.0.0 --title "Simple Title"
gh pr create --title "Simple Title" --body-file description.md

# ❌ Bad - Complex inline content (causes zsh issues)
git tag -a v1.0.0 -m "🎉 Release with emojis and special chars"
gh release create v1.0.0 --notes "Complex content with @ symbols"
gh pr create --title "Complex Title" --body "Content with special chars"
```

### When ZSH Issues Occur
- **STOP** the command immediately (Ctrl+C)
- **BREAK DOWN** the operation into smaller steps
- **USE FILES** for complex content instead of inline strings
- **TEST** each step individually before combining

## File Management
- Create temporary files for complex content
- Use `edit_file` tool for creating content files
- Use `delete_file` tool to clean up temporary files
- Always verify file contents before using them
- Use descriptive filenames like `RELEASE_NOTES_v1.0.0.md`

## Error Prevention
- Test simple commands first
- Break complex operations into smaller steps
- Use file-based approaches for complex content
- Verify results after each step
- Check command output for zsh errors
- If you see `dquote>` or `>` prompts, cancel and simplify

## Release Process Checklist
1. ✅ Create release notes in separate file using `edit_file`
2. ✅ Use simple git tag command: `git tag v1.0.0`
3. ✅ Use `--notes-file` for GitHub releases
4. ✅ Clean up temporary files with `delete_file`
5. ✅ Verify tag points to correct commit
6. ✅ Test each command individually before combining

## Common ZSH Error Patterns to Avoid
- `dquote>` prompt - means unclosed quotes
- `>` prompt - means incomplete command
- `zsh: no such file or directory` - often means escaping issues
- `zsh: command not found` - often means special characters interpreted as commands

## Emergency Recovery
If you get stuck in a zsh prompt:
1. Press `Ctrl+C` to cancel
2. Press `Ctrl+D` to exit if needed
3. Start fresh with simple commands
4. Use file-based approach for complex content