Skip to content

AGENTS.md

Latest commit

 

History

History
118 lines (92 loc) · 6.27 KB

AGENTS.md

File metadata and controls

118 lines (92 loc) · 6.27 KB

AGENTS.md

This file provides guidance to Codex when working with code in this repository.

What This Is

Beagle is a Claude Code plugin marketplace providing framework-aware code review skills and verification workflows for pre-push reviews and GitHub bot feedback handling. It contains 11 focused plugins with 122 skills.

Marketplace Architecture

beagle/
├── .claude-plugin/
│   └── marketplace.json         # Marketplace manifest (11 plugins)
└── plugins/
    ├── beagle-core/             # Shared workflows, verification, git workflows (18 skills)
    ├── beagle-python/           # Python, FastAPI, SQLAlchemy, PostgreSQL, pytest (7 skills)
    ├── beagle-go/               # Go, BubbleTea, Wish SSH, Prometheus (13 skills)
    ├── beagle-elixir/           # Elixir, Phoenix, LiveView, ExUnit, ExDoc (11 skills)
    ├── beagle-ios/              # Swift, SwiftUI, SwiftData, iOS frameworks (16 skills)
    ├── beagle-react/            # React, React Flow, shadcn/ui, Tailwind, Vitest (16 skills)
    ├── beagle-rust/             # Rust, tokio, axum, sqlx, serde (8 skills)
    ├── beagle-ai/               # Pydantic AI, LangGraph, DeepAgents, Vercel AI SDK (13 skills)
    ├── beagle-docs/             # Documentation quality, AI writing detection (10 skills)
    ├── beagle-analysis/         # Brainstorming, 12-Factor, ADRs, LLM-as-judge (8 skills)
    └── beagle-testing/          # Test plan generation and execution (2 skills)

Each plugin is self-contained with its own plugin.json and skills/ directory.

Local Development

Test the marketplace during development:

# In Claude Code settings (~/.claude/settings.json)
{
  "plugins": ["/path/to/your/beagle"]
}

Restart Claude Code after changes to reload. Skills are discovered from plugin skills/ directories and trigger keywords in skill frontmatter. Codex users can install the same skills by linking each plugin into ~/.agents/skills/ (see .codex/INSTALL.md).

Skills

See Agent Skills for the canonical format.

Beagle treats skills as the canonical format. Former command workflows were unified into SKILL.md files under each plugin's skills/ directory, where frontmatter controls user exposure and behavior.

Skills (plugins/<name>/skills/ folders): Auto-loaded when relevant. Structure: skill-name/SKILL.md with optional references/ folder and frontmatter such as disable-model-invocation and user-invocable.

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
  • Place new skills in the appropriate plugin directory
  • Mark workflow skills with disable-model-invocation: true
  • Mark internal-only reference skills with user-invocable: false

Key Skills

Plugin Skill Purpose
beagle-python review-python Python/FastAPI code review with tech detection
beagle-react review-frontend React/TypeScript code review with tech detection
beagle-go review-go Go code review with BubbleTea/Wish/Prometheus detection
beagle-go review-tui BubbleTea TUI code review with Elm architecture focus
beagle-ios review-ios iOS/SwiftUI code review
beagle-elixir review-elixir Elixir/Phoenix/LiveView code review
beagle-core review-plan Review implementation plans before execution
beagle-core commit-push Commit with Conventional Commits format
beagle-core create-pr Create PR with structured template
beagle-core gen-release-notes Generate changelog from git history
beagle-core skill-builder Guided skill creation workflow
beagle-core receive-feedback Process code review feedback with verification
beagle-core fetch-pr-feedback Fetch and evaluate bot review comments from PR
beagle-core respond-pr-feedback Post replies to bot review comments
beagle-core review-llm-artifacts Detect LLM coding artifacts
beagle-core fix-llm-artifacts Fix detected artifacts
beagle-core prompt-improver Optimize prompts
beagle-analysis llm-judge Compare implementations using LLM-as-judge
beagle-analysis write-adr Generate ADRs from decisions
beagle-docs draft-docs Generate documentation drafts
beagle-docs improve-doc Improve docs using Diataxis principles
beagle-docs ensure-docs Documentation coverage check
beagle-docs review-ai-writing Detect AI writing patterns in docs and code
beagle-docs humanize-beagle Fix AI writing with safe/risky classification
beagle-testing gen-test-plan Generate YAML test plan from branch changes
beagle-testing run-test-plan Execute test plan, stop on first failure

Conventions

  • Commits: Conventional Commits format (feat, fix, docs, refactor, test, chore)
  • Versioning: Semantic versioning in marketplace.json and each plugin's plugin.json
  • Release notes: Keep a Changelog format, generated via /beagle-core:gen-release-notes
  • Skill references: Use <plugin-name>:<skill-name> format (e.g., beagle-python:python-code-review)

No Build System

This is a pure markdown plugin marketplace. No npm, no build, no tests. Validation is manual inspection of markdown syntax and YAML frontmatter.

Release Process

  1. Update CHANGELOG.md - Add new version section with changes (Keep a Changelog format)
  2. Bump version - Update version in .claude-plugin/marketplace.json and affected plugin.json files (semver)
  3. Commit - chore(release): bump version to X.Y.Z
  4. Push - git push origin main
  5. Tag - git tag -a vX.Y.Z -m "Release vX.Y.Z - Summary" and git push origin vX.Y.Z
  6. 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 skills or features
  • Major (X.0.0): Breaking changes to existing skills