CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What This Is
Beagle is a Claude Code plugin providing code review skills and verification workflows. Designed to complement superpowers with pre-push reviews and GitHub bot feedback handling. It contains 45 skills (auto-loaded by Claude when relevant) and 14 commands (user-invoked via /beagle:<command>).
Plugin Architecture
beagle/
├── .claude-plugin/ # Plugin manifest (plugin.json) and marketplace config
├── commands/ # User-invoked slash commands (14 files)
└── skills/ # Model-invoked agent skills (45 skills, flat structure)
Skill categories (all in flat skills/ folder):
- Frontend: react-flow*, react-router-v7, tailwind-v4, shadcn-ui*, zustand-state, vitest-testing, dagre-react-flow
- Backend Python: python-code-review, fastapi-*, sqlalchemy-code-review, postgres-code-review, pytest-code-review
- Backend Go: go-code-review, bubbletea-code-review, wish-ssh-code-review, prometheus-go-code-review, go-testing-code-review
- AI Frameworks: pydantic-ai-* (6 skills), langgraph-* (3 skills), vercel-ai-sdk
- Utilities: docling, sqlite-vec, github-projects, 12-factor-apps, ai-elements, agent-architecture-analysis, receive-feedback, review-feedback-schema, review-skill-improver
Local Development
Test the plugin during development:
# In Claude Code settings (~/.claude/settings.json)
{
"plugins": ["/path/to/your/beagle"]
}
Restart Claude Code after changes to reload. For skills, start a conversation using trigger keywords. For commands, run /beagle:<command-name>.
Skills vs Commands
See Agent Skills and Slash commands for general concepts.
Skills (skills/ folder): Auto-loaded by Claude when relevant. Structure: skill-name/SKILL.md with optional references/ folder.
Commands (commands/ folder): User-invoked with /beagle:<name>. Single markdown file per command.
Creating New Skills
See Agent Skills best practices for authoring guidance.
Beagle-specific:
- Keep SKILL.md under 500 lines; use
references/ for details
- Some skills use multiple root-level .md files (e.g., react-router-v7)
- Code review skills: use format
[FILE:LINE] ISSUE_TITLE
Creating New Commands
Beagle command patterns:
- Start with context gathering (git diff, tech detection)
- Load relevant skills dynamically
- Include output format templates
- End with verification steps
Key Commands
| Command |
Purpose |
review-python |
Python/FastAPI code review with tech detection |
review-frontend |
React/TypeScript code review with tech detection |
review-go |
Go code review with BubbleTea/Wish/Prometheus detection |
review-tui |
BubbleTea TUI code review with Elm architecture focus |
review-plan |
Review implementation plans before execution |
commit-push |
Commit with Conventional Commits format |
create-pr |
Create PR with structured template |
gen-release-notes |
Generate changelog from git history |
skill-builder |
Guided skill creation workflow |
receive-feedback |
Process code review feedback with verification |
fetch-pr-feedback |
Fetch and evaluate bot review comments from PR |
respond-pr-feedback |
Post replies to bot review comments |
12-factor-apps-analysis |
Analyze codebase for 12-Factor compliance |
ensure-docs |
Documentation quality checking with language-specific standards |
llm-judge |
Compare implementations using LLM-as-judge methodology |
Conventions
- Commits: Conventional Commits format (feat, fix, docs, refactor, test, chore)
- Versioning: Semantic versioning in
.claude-plugin/plugin.json
- Release notes: Keep a Changelog format, generated via
/beagle:gen-release-notes
No Build System
This is a pure markdown plugin. No npm, no build, no tests. Validation is manual inspection of markdown syntax and YAML frontmatter.
Release Process
- Update CHANGELOG.md - Add new version section with changes (Keep a Changelog format)
- Bump version - Update
version in .claude-plugin/plugin.json (semver)
- Commit -
chore(release): bump version to X.Y.Z
- Push -
git push origin main
- Tag -
git tag -a vX.Y.Z -m "Release vX.Y.Z - Summary" and git push origin vX.Y.Z
- Release -
gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
Version bumping:
- Patch (x.y.Z): Bug fixes, documentation
- Minor (x.Y.0): New commands, skills, or features
- Major (X.0.0): Breaking changes to existing commands/skills
1---2name: what-this-is-73description: This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.4---5# CLAUDE.md67This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.89## What This Is1011Beagle is a Claude Code plugin providing code review skills and verification workflows. Designed to complement [superpowers](https://github.com/obra/superpowers) with pre-push reviews and GitHub bot feedback handling. It contains 45 skills (auto-loaded by Claude when relevant) and 14 commands (user-invoked via `/beagle:<command>`).1213## Plugin Architecture1415```16beagle/17├── .claude-plugin/ # Plugin manifest (plugin.json) and marketplace config18├── commands/ # User-invoked slash commands (14 files)19└── skills/ # Model-invoked agent skills (45 skills, flat structure)20```2122**Skill categories** (all in flat `skills/` folder):23- **Frontend**: react-flow*, react-router-v7, tailwind-v4, shadcn-ui*, zustand-state, vitest-testing, dagre-react-flow24- **Backend Python**: python-code-review, fastapi-*, sqlalchemy-code-review, postgres-code-review, pytest-code-review25- **Backend Go**: go-code-review, bubbletea-code-review, wish-ssh-code-review, prometheus-go-code-review, go-testing-code-review26- **AI Frameworks**: pydantic-ai-* (6 skills), langgraph-* (3 skills), vercel-ai-sdk27- **Utilities**: docling, sqlite-vec, github-projects, 12-factor-apps, ai-elements, agent-architecture-analysis, receive-feedback, review-feedback-schema, review-skill-improver2829## Local Development3031Test the plugin during development:3233```bash34# In Claude Code settings (~/.claude/settings.json)35{36 "plugins": ["/path/to/your/beagle"]37}38```3940Restart Claude Code after changes to reload. For skills, start a conversation using trigger keywords. For commands, run `/beagle:<command-name>`.4142## Skills vs Commands4344See [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) and [Slash commands](https://docs.claude.com/en/docs/claude-code/slash-commands) for general concepts.4546**Skills** (`skills/` folder): Auto-loaded by Claude when relevant. Structure: `skill-name/SKILL.md` with optional `references/` folder.4748**Commands** (`commands/` folder): User-invoked with `/beagle:<name>`. Single markdown file per command.4950## Creating New Skills5152See [Agent Skills best practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for authoring guidance.5354Beagle-specific:55- Keep SKILL.md under 500 lines; use `references/` for details56- Some skills use multiple root-level .md files (e.g., react-router-v7)57- Code review skills: use format `[FILE:LINE] ISSUE_TITLE`5859## Creating New Commands6061Beagle command patterns:62- Start with context gathering (git diff, tech detection)63- Load relevant skills dynamically64- Include output format templates65- End with verification steps6667## Key Commands6869| Command | Purpose |70|---------|---------|71| `review-python` | Python/FastAPI code review with tech detection |72| `review-frontend` | React/TypeScript code review with tech detection |73| `review-go` | Go code review with BubbleTea/Wish/Prometheus detection |74| `review-tui` | BubbleTea TUI code review with Elm architecture focus |75| `review-plan` | Review implementation plans before execution |76| `commit-push` | Commit with Conventional Commits format |77| `create-pr` | Create PR with structured template |78| `gen-release-notes` | Generate changelog from git history |79| `skill-builder` | Guided skill creation workflow |80| `receive-feedback` | Process code review feedback with verification |81| `fetch-pr-feedback` | Fetch and evaluate bot review comments from PR |82| `respond-pr-feedback` | Post replies to bot review comments |83| `12-factor-apps-analysis` | Analyze codebase for 12-Factor compliance |84| `ensure-docs` | Documentation quality checking with language-specific standards |85| `llm-judge` | Compare implementations using LLM-as-judge methodology |8687## Conventions8889- **Commits**: Conventional Commits format (feat, fix, docs, refactor, test, chore)90- **Versioning**: Semantic versioning in `.claude-plugin/plugin.json`91- **Release notes**: Keep a Changelog format, generated via `/beagle:gen-release-notes`9293## No Build System9495This is a pure markdown plugin. No npm, no build, no tests. Validation is manual inspection of markdown syntax and YAML frontmatter.9697## Release Process98991. **Update CHANGELOG.md** - Add new version section with changes (Keep a Changelog format)1002. **Bump version** - Update `version` in `.claude-plugin/plugin.json` (semver)1013. **Commit** - `chore(release): bump version to X.Y.Z`1024. **Push** - `git push origin main`1035. **Tag** - `git tag -a vX.Y.Z -m "Release vX.Y.Z - Summary"` and `git push origin vX.Y.Z`1046. **Release** - `gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."`105106Version bumping:107- **Patch** (x.y.Z): Bug fixes, documentation108- **Minor** (x.Y.0): New commands, skills, or features109- **Major** (X.0.0): Breaking changes to existing commands/skills
tools-only