From 21220a3be2fce01a54bc32b16c8718f87c10eb2b Mon Sep 17 00:00:00 2001 From: Austin Gregg-Smith Date: Sat, 17 Jan 2026 13:36:12 +0000 Subject: [PATCH] Add agent instructions and fix-issue command - Add AGENTS.md with devcontainer/gh cli documentation - Symlink CLAUDE.md to AGENTS.md for Claude Code compatibility - Add /project:fix-issue command for GitHub issue workflow - Remove .claude/README.md (not part of memory system) Co-Authored-By: Claude Opus 4.5 --- .claude/README.md | 63 ----------------------------------- .claude/commands/fix-issue.md | 20 +++++++++++ AGENTS.md | 17 ++++++++++ CLAUDE.md | 1 + 4 files changed, 38 insertions(+), 63 deletions(-) delete mode 100644 .claude/README.md create mode 100644 .claude/commands/fix-issue.md create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.claude/README.md b/.claude/README.md deleted file mode 100644 index 168d163..0000000 --- a/.claude/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# Claude Code Configuration - -This directory contains configuration for using this project with Claude Code, particularly in the online environment. - -## SessionStart Hook - -The `hooks/SessionStart` script automatically runs when a new Claude Code session begins. It: - -1. **Installs pixi** (if not already installed) - The package and environment manager -2. **Installs project dependencies** - All Python packages and tools defined in `pyproject.toml` -3. **Sets up prek hooks** - For automatic code quality checks -4. **Configures git** - Sets up merge drivers for lockfiles - -## Usage with Claude Code Online - -When you start a Claude Code online session, the SessionStart hook will automatically run and set up your environment. You'll see output indicating the setup progress. - -### Available Commands - -Once setup is complete, Claude can use these pixi tasks: - -#### Testing & Quality -- `pixi run test` - Run pytest tests -- `pixi run coverage` - Run tests with coverage report -- `pixi run lint` - Run ruff and pylint linters -- `pixi run format` - Format code with ruff - -#### CI Tasks -- `pixi run ci` - Run full CI pipeline (format, lint, test, coverage) -- `pixi run fix` - Auto-fix common issues (update lock, format, lint) - -#### Prek Hooks -- `pixi run prek` - Run all prek hooks -- `pixi run prek-update` - Update prek hook versions - -### How It Works - -1. **First session**: The hook installs pixi and all dependencies (may take a few minutes) -2. **Subsequent sessions**: The hook verifies the environment is ready (much faster) -3. **Environment activated**: All pixi commands are available to Claude - -### Troubleshooting - -If you encounter issues: - -1. **Dependencies not found**: Run `pixi install` manually -2. **Lockfile conflicts**: Run `pixi run update-lock` -3. **Prek issues**: Run `pixi run prek-update` -4. **Full reset**: Delete `.pixi` directory and restart session - -### Customization - -You can modify `hooks/SessionStart` to: -- Install additional tools -- Run custom setup scripts -- Configure environment variables -- Set up external services - -## Learn More - -- [Claude Code Documentation](https://docs.claude.com/claude-code) -- [Pixi Documentation](https://pixi.sh) -- [Project README](../README.md) diff --git a/.claude/commands/fix-issue.md b/.claude/commands/fix-issue.md new file mode 100644 index 0000000..1af6c35 --- /dev/null +++ b/.claude/commands/fix-issue.md @@ -0,0 +1,20 @@ +# Fix GitHub Issue + +Fix the GitHub issue: $ARGUMENTS + +## Steps + +1. Fetch issue details: `pixi run gh issue view $ARGUMENTS` +2. Extract the issue number from the URL for commit messages +3. Understand the problem and locate relevant code +4. Implement the fix +5. Run `pixi run ci` to verify (format, lint, test, coverage) +6. Commit with message referencing the issue (e.g., `Fixes #123`) +7. Create PR: `pixi run gh pr create` + +## Notes + +- Input can be a GitHub URL (e.g., `https://github.com/owner/repo/issues/123`) or issue number +- Keep changes minimal and focused on the issue +- Add tests if fixing a bug +- Run full CI before committing diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b9c826c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# Agent Instructions + +## Development Environment + +This project uses a devcontainer with pixi for environment management. + +### Available Tools + +- **GitHub CLI (`gh`)**: Available via `pixi run gh` or directly if using a login shell. The container mounts the host's `~/.config/gh` directory, so if the user is authenticated on the host, authentication is shared automatically. + +### Running Commands + +When using pixi tasks, prefer `pixi run `. See `pixi task list` for available tasks. + +For tools installed as dependencies (like `gh`), you can run them via: +- `pixi run gh ` - works in any shell +- `gh ` - works in login shells (`bash -l -c '...'`) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file