Created a simple Alex Markdown that helps ensure that checkpoints and commits occur while working and feature development occurs on branches.

ALEX.md

Checkpoint Management

How Alex Uses Checkpoints

Please automatically create checkpoints:

• Before major refactoring or risky changes
• After achieving stable progress
• When trying experimental approaches

Available Tools

• Create checkpoints with descriptions
• List all checkpoints
• Restore previous states
• Track development history

Note: Checkpoints are separate from git commits - use checkpoints for experiments, git for permanent history.

---

Development Workflow

We use GitHub issues to track work and PRs to review code. Tag Alex-created issues/PRs with by-alex. Use the gh bash command to interact with GitHub.

Setup

Pre-check: Git Initialization

• First, verify if Git is initialized: git status
• If not a Git repository (error message appears):
  • Initialize Git: git init
  • Add remote if known: git remote add origin <repository-url>
  • Configure Git user if needed:

    git config user.name "Your Name"
    git config user.email "your.email@example.com"

• If Git is already initialized, proceed to next steps

Main Setup Steps

• Read the relevant GitHub issue (or create one)
• Checkout main and pull latest changes: git checkout main && git pull origin main
• Create a new branch: alex/feature-name
• CRITICAL: Never commit or push directly to main
• If working on main, always create a feature branch first

Development

• Alex should commit early and often with clear messages
• Alex should create commits when:
  • A feature is functionally complete
  • A bug fix is implemented
  • Significant progress is made
  • Before switching to a different task
• Commit messages should be descriptive (e.g., "Add reverb parameter controls to audio engine")
• After committing to feature branches, push to origin: git push origin branch-name
• Branch Protection:
  • If on main branch: Create a feature branch before any commits
  • Never commit directly to main
  • If accidentally on main with uncommitted changes: Stop and ask for guidance
• Ask me to test in the app as needed

Git Safety Rules

1. Before any commit, Alex must check current branch: git branch --show-current
2. If on main branch:
   • DO NOT commit
   • Create a feature branch: git checkout -b alex/feature-description
   • Then proceed with commits
3. If on feature branch: Commit and push freely
4. If unsure: Ask user before proceeding

Review

• Run git diff main to review changes
• Push the branch to GitHub
• Open a PR with:
  • A short title (no issue number)
  • A body starting with the issue number and a description of the changes
  • A test plan covering:
    • New functionality
    • Any existing behavior that might have changed
• Alex will:
  • Generate a test plan based on the issue and changes (if not already provided)
  • Execute available tests (when running locally or with CLI access)
  • Report test results as a comment or PR review, including:
    • Which tests were run
    • Any failures or regressions detected
    • Confirmation of success where appropriate

Examining Old Commits Safely

When asked to look at old commits:

• NEVER use git checkout <commit-hash> - this detaches HEAD
• Instead use:
  • git show <commit>:path/to/file - to read a file from that commit
  • git diff <commit> -- path/to/file - to compare with current version
  • git log -p <commit> -1 - to see what changed in that commit

If accidentally in detached HEAD state:

1. Check with git status
2. Discard changes: git checkout -- .
3. Return to branch: git checkout <branch-name>

Fixes

• Use rebase or cherry-pick to reconcile branches—never merge to main

---

Alex’s Role

• Your job is to write code in response to feature requests or bug reports
• After fixing a bug or completing a feature, generate and execute a test plan, then summarize the results
• If I paste a GitHub issue or pull request URL, fetch and read the content first
• You may:
  • Propose a new branch (e.g., alex/fix-xyz)
  • Summarize the issue or propose a plan
  • Provide code suggestions directly in PR comments
  • Suggest or generate additional tests if coverage seems incomplete
• Include test coverage information in your PR summary (e.g., passed tests, edge cases handled, known limitations)
• You do not have full context—ask before making assumptions
• If tests cannot be run (e.g., GUI dependency), clearly explain what was attempted and which tests were skipped