Merge upstream v2.34.0 with FastAPI pivot (v2.35.0)
Some checks failed
CI / test (push) Has been cancelled
Some checks failed
CI / test (push) Has been cancelled
Incorporate 42 upstream commits while preserving the Ruby/Rails → Python/FastAPI pivot. All 24 conflicting files individually triaged and resolved. Key changes: - Added tiangolo-fastapi-reviewer, python-package-readme-writer, fastapi-style, python-package-writer skills - Removed Rails/Ruby agents and skills (DHH, Ankane, DSPy.rb, design agents) - Merged pressure test into workflows/review, updated reviewer references - Upstream additions: schema-drift-detector, slfg, setup skill, document-review, orchestrating-swarms, resolve-pr-parallel, new converter targets (cursor, gemini, droid, pi) - Version 2.35.0: 25 agents, 23 commands, 18 skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Lamb
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "compound-engineering",
|
||||
"version": "2.30.0",
|
||||
"description": "AI-powered development tools. 27 agents, 25 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.",
|
||||
"version": "2.35.0",
|
||||
"description": "AI-powered development tools. 25 agents, 23 commands, 18 skills, 1 MCP server for code review, research, design, and workflow automation.",
|
||||
"author": {
|
||||
"name": "Kieran Klaassen",
|
||||
"email": "kieran@every.to",
|
||||
|
||||
@@ -5,79 +5,149 @@ All notable changes to the compound-engineering plugin will be documented in thi
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [2.30.0] - 2026-02-03
|
||||
|
||||
### Added
|
||||
|
||||
- **`/pr-comments-to-todos` command** - Fetch PR review comments and convert them into todo files for triage
|
||||
- Fetches all comments from a GitHub PR using `gh` CLI
|
||||
- Converts each actionable comment into a structured todo file following the file-todos skill format
|
||||
- Assigns priority levels (P1/P2/P3) based on comment severity
|
||||
- Creates todo files compatible with `/triage` command for approval workflow
|
||||
- Skips non-actionable comments (LGTM, resolved threads, etc.)
|
||||
- Supports PR number, GitHub URL, or "current" for current branch
|
||||
|
||||
### Summary
|
||||
|
||||
- 27 agents, 25 commands, 15 skills, 1 MCP server
|
||||
|
||||
---
|
||||
|
||||
## [2.29.0] - 2026-01-26
|
||||
## [2.35.0] - 2026-02-16
|
||||
|
||||
### Changed
|
||||
|
||||
- **Backend focus shift: Ruby/Rails → Python/FastAPI** - Comprehensive conversion of backend-focused components
|
||||
- **Backend focus shift: Ruby/Rails -> Python/FastAPI** - Comprehensive conversion of backend-focused components
|
||||
- All backend-related agents and skills now target Python/FastAPI instead of Ruby/Rails
|
||||
- TypeScript/React frontend components remain unchanged
|
||||
|
||||
### Added
|
||||
|
||||
- **`tiangolo-fastapi-reviewer` agent** - FastAPI code review from Sebastián Ramírez's perspective
|
||||
- Reviews for Pydantic model patterns, async/await discipline, dependency injection
|
||||
- Identifies Flask/Django patterns contaminating FastAPI codebases
|
||||
- Enforces OpenAPI schema design and type hints
|
||||
|
||||
- **`python-package-readme-writer` agent** - Create concise READMEs for Python packages
|
||||
- Follows modern Python packaging conventions (pyproject.toml, src layout)
|
||||
- Targets PyPI publication with pip/uv/poetry installation instructions
|
||||
|
||||
- **`fastapi-style` skill** - Write FastAPI code following opinionated best practices
|
||||
- Thin routers, rich Pydantic models with validation
|
||||
- SQLAlchemy 2.0 async patterns, dependency injection
|
||||
- References for routers, models, database, testing, security, background tasks
|
||||
|
||||
- **`python-package-writer` skill** - Write Python packages following production-ready patterns
|
||||
- Modern packaging with pyproject.toml, src layout, pytest
|
||||
- Zero or minimal dependencies philosophy
|
||||
- Type hints, configuration patterns, FastAPI integration
|
||||
|
||||
- **`dspy-python` skill** - Build LLM applications with DSPy framework
|
||||
- Signature-based prompting, teleprompter optimization
|
||||
- FastAPI integration patterns, pytest testing
|
||||
- Replaced dspy-ruby skill
|
||||
|
||||
- **Enhanced `kieran-python-reviewer` agent** - Now includes FastAPI-specific sections
|
||||
- Pydantic model patterns, async/await discipline
|
||||
- Dependency injection, OpenAPI schema design
|
||||
- SQLAlchemy 2.0 async, router organization, security patterns
|
||||
|
||||
- **Enhanced `kieran-python-reviewer` agent** - Now includes 9 FastAPI-specific convention sections
|
||||
- **Updated `lint` agent** - Now targets Python files
|
||||
- Uses ruff for linting/formatting, mypy for type checking
|
||||
- bandit for security scanning, djlint for Jinja2 templates
|
||||
- **`/pr-comments-to-todos` command** - Fetch PR review comments and convert them into todo files for triage
|
||||
- **Pressure Test framework** in workflows:review - Critical evaluation of agent findings before creating todos
|
||||
|
||||
### Removed
|
||||
|
||||
- **`dhh-rails-reviewer` agent** - Replaced by tiangolo-fastapi-reviewer
|
||||
- **`kieran-rails-reviewer` agent** - Functionality merged into kieran-python-reviewer
|
||||
- **`ankane-readme-writer` agent** - Replaced by python-package-readme-writer
|
||||
- **3 design agents** - design-implementation-reviewer, design-iterator, figma-design-sync
|
||||
- **`dhh-rails-style` skill** - Replaced by fastapi-style
|
||||
- **`andrew-kane-gem-writer` skill** - Replaced by python-package-writer
|
||||
- **`dspy-ruby` skill** - Replaced by dspy-python
|
||||
- **`dspy-ruby` skill** - Removed (not used; LangChain/LangGraph is the actual stack)
|
||||
- **`dspy-python` skill** - Removed (not used; LangChain/LangGraph is the actual stack)
|
||||
- **`/plan_review` command** - Absorbed into workflows/plan via document-review skill
|
||||
|
||||
### Summary
|
||||
---
|
||||
|
||||
- 27 agents, 24 commands, 15 skills, 1 MCP server
|
||||
## [2.34.0] - 2026-02-14
|
||||
|
||||
### Added
|
||||
|
||||
- **Gemini CLI target** — New converter target for [Gemini CLI](https://github.com/google-gemini/gemini-cli). Install with `--to gemini` to convert agents to `.gemini/skills/*/SKILL.md`, commands to `.gemini/commands/*.toml` (TOML format with `description` + `prompt`), and MCP servers to `.gemini/settings.json`. Skills pass through unchanged (identical SKILL.md standard). Namespaced commands create directory structure (`workflows:plan` → `commands/workflows/plan.toml`). 29 new tests. ([#190](https://github.com/EveryInc/compound-engineering-plugin/pull/190))
|
||||
|
||||
---
|
||||
|
||||
## [2.33.1] - 2026-02-13
|
||||
|
||||
### Changed
|
||||
|
||||
- **`/workflows:plan` command** - All plan templates now include `status: active` in YAML frontmatter. Plans are created with `status: active` and marked `status: completed` when work finishes.
|
||||
- **`/workflows:work` command** - Phase 4 now updates plan frontmatter from `status: active` to `status: completed` after shipping. Agents can grep for status to distinguish current vs historical plans.
|
||||
|
||||
---
|
||||
|
||||
## [2.33.0] - 2026-02-12
|
||||
|
||||
### Added
|
||||
|
||||
- **`setup` skill** — Interactive configurator for review agents
|
||||
- Auto-detects project type (Rails, Python, TypeScript, etc.)
|
||||
- Two paths: "Auto-configure" (one click) or "Customize" (pick stack, focus areas, depth)
|
||||
- Writes `compound-engineering.local.md` in project root (tool-agnostic — works for Claude, Codex, OpenCode)
|
||||
- Invoked automatically by `/workflows:review` when no settings file exists
|
||||
- **`learnings-researcher` in `/workflows:review`** — Always-run agent that searches `docs/solutions/` for past issues related to the PR
|
||||
- **`schema-drift-detector` wired into `/workflows:review`** — Conditional agent for PRs with migrations
|
||||
|
||||
### Changed
|
||||
|
||||
- **`/workflows:review`** — Now reads review agents from `compound-engineering.local.md` settings file. Falls back to invoking setup skill if no file exists.
|
||||
- **`/workflows:work`** — Review agents now configurable via settings file
|
||||
- **`/release-docs` command** — Moved from plugin to local `.claude/commands/` (repo maintenance, not distributed)
|
||||
|
||||
### Removed
|
||||
|
||||
- **`/technical_review` command** — Superseded by configurable review agents
|
||||
|
||||
---
|
||||
|
||||
## [2.32.0] - 2026-02-11
|
||||
|
||||
### Added
|
||||
|
||||
- **Factory Droid target** — New converter target for [Factory Droid](https://docs.factory.ai). Install with `--to droid` to output agents, commands, and skills to `~/.factory/`. Includes tool name mapping (Claude → Factory), namespace prefix stripping, Task syntax conversion, and agent reference rewriting. 13 new tests (9 converter + 4 writer). ([#174](https://github.com/EveryInc/compound-engineering-plugin/pull/174))
|
||||
|
||||
---
|
||||
|
||||
## [2.31.1] - 2026-02-09
|
||||
|
||||
### Changed
|
||||
|
||||
- **`dspy-ruby` skill** — Complete rewrite to DSPy.rb v0.34.3 API: `.call()` / `result.field` patterns, `T::Enum` classes, `DSPy::Tools::Base` / `Toolset`. Added events system, lifecycle callbacks, fiber-local LM context, GEPA optimization, evaluation framework, typed context pattern, BAML/TOON schema formats, storage system, score reporting, RubyLLM adapter. 5 reference files (2 new: toolsets, observability), 3 asset templates rewritten.
|
||||
|
||||
## [2.31.0] - 2026-02-08
|
||||
|
||||
### Added
|
||||
|
||||
- **`document-review` skill** — Brainstorm and plan refinement through structured review ([@Trevin Chow](https://github.com/trevin))
|
||||
- **`/sync` command** — Sync Claude Code personal config across machines ([@Terry Li](https://github.com/terryli))
|
||||
|
||||
### Changed
|
||||
|
||||
- **Context token optimization (79% reduction)** — Plugin was consuming 316% of the context description budget, causing Claude Code to silently exclude components. Now at 65% with room to grow:
|
||||
- All 29 agent descriptions trimmed from ~1,400 to ~180 chars avg (examples moved to agent body)
|
||||
- 18 manual commands marked `disable-model-invocation: true` (side-effect commands like `/lfg`, `/deploy-docs`, `/triage`, etc.)
|
||||
- 6 manual skills marked `disable-model-invocation: true` (`orchestrating-swarms`, `git-worktree`, `skill-creator`, `compound-docs`, `file-todos`, `resolve-pr-parallel`)
|
||||
- **git-worktree**: Remove confirmation prompt for worktree creation ([@Sam Xie](https://github.com/samxie))
|
||||
- **Prevent subagents from writing intermediary files** in compound workflow ([@Trevin Chow](https://github.com/trevin))
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix crash when hook entries have no matcher ([@Roberto Mello](https://github.com/robertomello))
|
||||
- Fix git-worktree detection where `.git` is a file, not a directory ([@David Alley](https://github.com/davidalley))
|
||||
- Backup existing config files before overwriting in sync ([@Zac Williams](https://github.com/zacwilliams))
|
||||
- Note new repository URL ([@Aarni Koskela](https://github.com/aarnikoskela))
|
||||
- Plugin component counts corrected: 29 agents, 24 commands, 18 skills
|
||||
|
||||
---
|
||||
|
||||
## [2.30.0] - 2026-02-05
|
||||
|
||||
### Added
|
||||
|
||||
- **`orchestrating-swarms` skill** - Comprehensive guide to multi-agent orchestration
|
||||
- Covers primitives: Agent, Team, Teammate, Leader, Task, Inbox, Message, Backend
|
||||
- Documents two spawning methods: subagents vs teammates
|
||||
- Explains all 13 TeammateTool operations
|
||||
- Includes orchestration patterns: Parallel Specialists, Pipeline, Self-Organizing Swarm
|
||||
- Details spawn backends: in-process, tmux, iterm2
|
||||
- Provides complete workflow examples
|
||||
- **`/slfg` command** - Swarm-enabled variant of `/lfg` that uses swarm mode for parallel execution
|
||||
|
||||
### Changed
|
||||
|
||||
- **`/workflows:work` command** - Added optional Swarm Mode section for parallel execution with coordinated agents
|
||||
|
||||
---
|
||||
|
||||
## [2.29.0] - 2026-02-04
|
||||
|
||||
### Added
|
||||
|
||||
- **`schema-drift-detector` agent** - Detects unrelated schema.rb changes in PRs
|
||||
- Compares schema.rb diff against migrations in the PR
|
||||
- Catches columns, indexes, and tables from other branches
|
||||
- Prevents accidental inclusion of local database state
|
||||
- Provides clear fix instructions (checkout + migrate)
|
||||
- Essential pre-merge check for any PR with database changes
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -59,7 +59,7 @@ When adding or modifying skills, verify compliance with skill-creator spec:
|
||||
### YAML Frontmatter (Required)
|
||||
|
||||
- [ ] `name:` present and matches directory name (lowercase-with-hyphens)
|
||||
- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...")
|
||||
- [ ] `description:` present and describes **what it does and when to use it** (per official spec: "Explains code with diagrams. Use when exploring how code works.")
|
||||
|
||||
### Reference Links (Required if references/ exists)
|
||||
|
||||
@@ -80,9 +80,8 @@ When adding or modifying skills, verify compliance with skill-creator spec:
|
||||
grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
|
||||
# Should return nothing if all refs are properly linked
|
||||
|
||||
# Check description format
|
||||
grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill'
|
||||
# Should return nothing if all use third person
|
||||
# Check description format - should describe what + when
|
||||
grep -E '^description:' skills/*/SKILL.md
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -6,16 +6,16 @@ AI-powered development tools that get smarter with every use. Make each unit of
|
||||
|
||||
| Component | Count |
|
||||
|-----------|-------|
|
||||
| Agents | 27 |
|
||||
| Commands | 24 |
|
||||
| Skills | 15 |
|
||||
| Agents | 25 |
|
||||
| Commands | 23 |
|
||||
| Skills | 18 |
|
||||
| MCP Servers | 1 |
|
||||
|
||||
## Agents
|
||||
|
||||
Agents are organized into categories for easier discovery.
|
||||
|
||||
### Review (13)
|
||||
### Review (14)
|
||||
|
||||
| Agent | Description |
|
||||
|-------|-------------|
|
||||
@@ -25,13 +25,14 @@ Agents are organized into categories for easier discovery.
|
||||
| `data-integrity-guardian` | Database migrations and data integrity |
|
||||
| `data-migration-expert` | Validate ID mappings match production, check for swapped values |
|
||||
| `deployment-verification-agent` | Create Go/No-Go deployment checklists for risky data changes |
|
||||
| `kieran-python-reviewer` | Python/FastAPI code review with strict conventions |
|
||||
| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
|
||||
| `kieran-python-reviewer` | Python code review with strict conventions |
|
||||
| `kieran-typescript-reviewer` | TypeScript code review with strict conventions |
|
||||
| `tiangolo-fastapi-reviewer` | FastAPI review from Sebastián Ramírez's perspective |
|
||||
| `pattern-recognition-specialist` | Analyze code for patterns and anti-patterns |
|
||||
| `performance-oracle` | Performance analysis and optimization |
|
||||
| `schema-drift-detector` | Detect unrelated schema changes in PRs |
|
||||
| `security-sentinel` | Security audits and vulnerability assessments |
|
||||
| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
|
||||
| `tiangolo-fastapi-reviewer` | FastAPI code review from tiangolo's perspective |
|
||||
|
||||
### Research (5)
|
||||
|
||||
@@ -40,17 +41,9 @@ Agents are organized into categories for easier discovery.
|
||||
| `best-practices-researcher` | Gather external best practices and examples |
|
||||
| `framework-docs-researcher` | Research framework documentation and best practices |
|
||||
| `git-history-analyzer` | Analyze git history and code evolution |
|
||||
| `learnings-researcher` | Research and extract learnings from documentation |
|
||||
| `learnings-researcher` | Search institutional learnings for relevant past solutions |
|
||||
| `repo-research-analyst` | Research repository structure and conventions |
|
||||
|
||||
### Design (3)
|
||||
|
||||
| Agent | Description |
|
||||
|-------|-------------|
|
||||
| `design-implementation-reviewer` | Verify UI implementations match Figma designs |
|
||||
| `design-iterator` | Iteratively refine UI through systematic design iterations |
|
||||
| `figma-design-sync` | Synchronize web implementations with Figma designs |
|
||||
|
||||
### Workflow (5)
|
||||
|
||||
| Agent | Description |
|
||||
@@ -65,7 +58,7 @@ Agents are organized into categories for easier discovery.
|
||||
|
||||
| Agent | Description |
|
||||
|-------|-------------|
|
||||
| `python-package-readme-writer` | Create concise READMEs for Python packages |
|
||||
| `python-package-readme-writer` | Create READMEs following concise documentation style for Python packages |
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -85,25 +78,24 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/agent-native-audit` | Run comprehensive agent-native architecture review with scored principles |
|
||||
| `/lfg` | Full autonomous engineering workflow |
|
||||
| `/slfg` | Full autonomous workflow with swarm mode for parallel execution |
|
||||
| `/deepen-plan` | Enhance plans with parallel research agents for each section |
|
||||
| `/changelog` | Create engaging changelogs for recent merges |
|
||||
| `/create-agent-skill` | Create or edit Claude Code skills |
|
||||
| `/deepen-plan` | Enhance plans with parallel research agents for each section |
|
||||
| `/deploy-docs` | Validate and prepare documentation for GitHub Pages deployment |
|
||||
| `/feature-video` | Record video walkthroughs and add to PR description |
|
||||
| `/generate_command` | Generate new slash commands |
|
||||
| `/heal-skill` | Fix skill documentation issues |
|
||||
| `/lfg` | Full autonomous engineering workflow |
|
||||
| `/plan_review` | Multi-agent plan review in parallel |
|
||||
| `/release-docs` | Build and update the documentation site with current plugin components |
|
||||
| `/report-bug` | Report a bug in the plugin |
|
||||
| `/reproduce-bug` | Reproduce bugs using logs and console |
|
||||
| `/resolve_parallel` | Resolve TODO comments in parallel |
|
||||
| `/resolve_pr_parallel` | Resolve PR comments in parallel |
|
||||
| `/resolve_todo_parallel` | Resolve todos in parallel |
|
||||
| `/test-browser` | Run browser tests on PR-affected pages |
|
||||
| `/triage` | Triage and prioritize issues |
|
||||
| `/xcode-test` | Build and test iOS apps on simulator |
|
||||
| `/test-browser` | Run browser tests on PR-affected pages |
|
||||
| `/test-xcode` | Build and test iOS apps on simulator |
|
||||
| `/feature-video` | Record video walkthroughs and add to PR description |
|
||||
| `/agent-native-audit` | Run comprehensive agent-native architecture review |
|
||||
| `/deploy-docs` | Validate and prepare documentation for GitHub Pages |
|
||||
| `/pr-comments-to-todos` | Fetch PR comments and convert to todo files |
|
||||
|
||||
## Skills
|
||||
|
||||
@@ -119,8 +111,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
|
||||
|-------|-------------|
|
||||
| `compound-docs` | Capture solved problems as categorized documentation |
|
||||
| `create-agent-skills` | Expert guidance for creating Claude Code skills |
|
||||
| `dspy-python` | Build LLM applications with DSPy framework |
|
||||
| `fastapi-style` | Write FastAPI code following opinionated best practices |
|
||||
| `fastapi-style` | Write Python/FastAPI code following opinionated best practices |
|
||||
| `frontend-design` | Create production-grade frontend interfaces |
|
||||
| `python-package-writer` | Write Python packages following production-ready patterns |
|
||||
| `skill-creator` | Guide for creating effective Claude Code skills |
|
||||
@@ -129,10 +120,19 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `brainstorming` | Explore requirements and approaches before planning |
|
||||
| `brainstorming` | Explore requirements and approaches through collaborative dialogue |
|
||||
| `document-review` | Improve documents through structured self-review |
|
||||
| `every-style-editor` | Review copy for Every's style guide compliance |
|
||||
| `file-todos` | File-based todo tracking system |
|
||||
| `git-worktree` | Manage Git worktrees for parallel development |
|
||||
| `resolve-pr-parallel` | Resolve PR review comments in parallel |
|
||||
| `setup` | Configure which review agents run for your project |
|
||||
|
||||
### Multi-Agent Orchestration
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `orchestrating-swarms` | Comprehensive guide to multi-agent swarm orchestration |
|
||||
|
||||
### File Transfer
|
||||
|
||||
@@ -174,7 +174,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
|
||||
- `resolve-library-id` - Find library ID for a framework/package
|
||||
- `get-library-docs` - Get documentation for a specific library
|
||||
|
||||
Supports 100+ frameworks including Rails, React, Next.js, Vue, Django, Laravel, and more.
|
||||
Supports 100+ frameworks including FastAPI, React, Next.js, Vue, Django, SQLAlchemy, and more.
|
||||
|
||||
MCP servers start automatically when the plugin is enabled.
|
||||
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: best-practices-researcher
|
||||
description: "Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards. <example>Context: User wants to know the best way to structure GitHub issues for their FastAPI project. user: \"I need to create some GitHub issues for our project. Can you research best practices for writing good issues?\" assistant: \"I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and FastAPI-specific conventions.\" <commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary></example> <example>Context: User is implementing a new authentication system and wants to follow security best practices. user: \"We're adding JWT authentication to our FastAPI API. What are the current best practices?\" assistant: \"Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and FastAPI-specific implementation patterns.\" <commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary></example>"
|
||||
description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User wants to know the best way to structure GitHub issues for their FastAPI project.
|
||||
user: "I need to create some GitHub issues for our project. Can you research best practices for writing good issues?"
|
||||
assistant: "I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and FastAPI-specific conventions."
|
||||
<commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is implementing a new authentication system and wants to follow security best practices.
|
||||
user: "We're adding JWT authentication to our FastAPI API. What are the current best practices?"
|
||||
assistant: "Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and FastAPI-specific implementation patterns."
|
||||
<commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
|
||||
|
||||
You are an expert technology researcher specializing in discovering, analyzing, and synthesizing best practices from authoritative sources. Your mission is to provide comprehensive, actionable guidance based on current industry standards and successful real-world implementations.
|
||||
@@ -21,7 +36,7 @@ Before going online, check if curated knowledge already exists in skills:
|
||||
|
||||
2. **Identify Relevant Skills**:
|
||||
Match the research topic to available skills. Common mappings:
|
||||
- Rails/Ruby → `dhh-rails-style`, `andrew-kane-gem-writer`, `dspy-ruby`
|
||||
- Python/FastAPI → `fastapi-style`, `python-package-writer`
|
||||
- Frontend/Design → `frontend-design`, `swiss-design`
|
||||
- TypeScript/React → `react-best-practices`
|
||||
- AI/Agents → `agent-native-architecture`, `create-agent-skills`
|
||||
@@ -79,7 +94,7 @@ Only after checking skills AND verifying API availability, gather additional inf
|
||||
|
||||
2. **Organize Discoveries**:
|
||||
- Organize into clear categories (e.g., "Must Have", "Recommended", "Optional")
|
||||
- Clearly indicate source: "From skill: dhh-rails-style" vs "From official docs" vs "Community consensus"
|
||||
- Clearly indicate source: "From skill: fastapi-style" vs "From official docs" vs "Community consensus"
|
||||
- Provide specific examples from real projects when possible
|
||||
- Explain the reasoning behind each best practice
|
||||
- Highlight any technology-specific or domain-specific considerations
|
||||
@@ -102,7 +117,7 @@ For GitHub issue best practices specifically, you will research:
|
||||
## Source Attribution
|
||||
|
||||
Always cite your sources and indicate the authority level:
|
||||
- **Skill-based**: "The dhh-rails-style skill recommends..." (highest authority - curated)
|
||||
- **Skill-based**: "The fastapi-style skill recommends..." (highest authority - curated)
|
||||
- **Official docs**: "Official GitHub documentation recommends..."
|
||||
- **Community**: "Many successful projects tend to..."
|
||||
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: framework-docs-researcher
|
||||
description: "Use this agent when you need to gather comprehensive documentation and best practices for frameworks, libraries, or dependencies in your project. This includes fetching official documentation, exploring source code, identifying version-specific constraints, and understanding implementation patterns. <example>Context: The user needs to understand how to properly implement a new feature using a specific library. user: \"I need to implement file uploads using Active Storage\" assistant: \"I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage\" <commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary></example> <example>Context: The user is troubleshooting an issue with a gem. user: \"Why is the turbo-rails gem not working as expected?\" assistant: \"Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code\" <commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary></example>"
|
||||
description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user needs to understand how to properly implement a new feature using a specific library.
|
||||
user: "I need to implement file uploads using Active Storage"
|
||||
assistant: "I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage"
|
||||
<commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is troubleshooting an issue with a gem.
|
||||
user: "Why is the turbo-rails gem not working as expected?"
|
||||
assistant: "Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code"
|
||||
<commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and version information.
|
||||
|
||||
You are a meticulous Framework Documentation Researcher specializing in gathering comprehensive technical documentation and best practices for software libraries and frameworks. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: git-history-analyzer
|
||||
description: "Use this agent when you need to understand the historical context and evolution of code changes, trace the origins of specific code patterns, identify key contributors and their expertise areas, or analyze patterns in commit history. This agent excels at archaeological analysis of git repositories to provide insights about code evolution and development patterns. <example>Context: The user wants to understand the history and evolution of recently modified files.\\nuser: \"I've just refactored the authentication module. Can you analyze the historical context?\"\\nassistant: \"I'll use the git-history-analyzer agent to examine the evolution of the authentication module files.\"\\n<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary></example> <example>Context: The user needs to understand why certain code patterns exist.\\nuser: \"Why does this payment processing code have so many try-catch blocks?\"\\nassistant: \"Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns.\"\\n<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary></example>"
|
||||
description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to understand the history and evolution of recently modified files.
|
||||
user: "I've just refactored the authentication module. Can you analyze the historical context?"
|
||||
assistant: "I'll use the git-history-analyzer agent to examine the evolution of the authentication module files."
|
||||
<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user needs to understand why certain code patterns exist.
|
||||
user: "Why does this payment processing code have so many try-catch blocks?"
|
||||
assistant: "Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns."
|
||||
<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when interpreting commit dates and recent changes.
|
||||
|
||||
You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions.
|
||||
@@ -40,3 +55,5 @@ When analyzing, consider:
|
||||
- The evolution of coding patterns and practices over time
|
||||
|
||||
Your insights should help developers understand not just what the code does, but why it evolved to its current state, informing better decisions for future changes.
|
||||
|
||||
Note that files in `docs/plans/` and `docs/solutions/` are compound-engineering pipeline artifacts created by `/workflows:plan`. They are intentional, permanent living documents — do not recommend their removal or characterize them as unnecessary.
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: learnings-researcher
|
||||
description: "Use this agent when you need to search institutional learnings in docs/solutions/ for relevant past solutions before implementing a new feature or fixing a problem. This agent efficiently filters documented solutions by frontmatter metadata (tags, category, module, symptoms) to find applicable patterns, gotchas, and lessons learned. The agent excels at preventing repeated mistakes by surfacing relevant institutional knowledge before work begins.\\n\\n<example>Context: User is about to implement a feature involving email processing.\\nuser: \"I need to add email threading to the brief system\"\\nassistant: \"I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations.\"\\n<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary></example>\\n\\n<example>Context: User is debugging a performance issue.\\nuser: \"Brief generation is slow, taking over 5 seconds\"\\nassistant: \"Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries.\"\\n<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary></example>\\n\\n<example>Context: Planning a new feature that touches multiple modules.\\nuser: \"I need to add Stripe subscription handling to the payments module\"\\nassistant: \"I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically.\"\\n<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary></example>"
|
||||
description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
|
||||
model: haiku
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User is about to implement a feature involving email processing.
|
||||
user: "I need to add email threading to the brief system"
|
||||
assistant: "I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations."
|
||||
<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is debugging a performance issue.
|
||||
user: "Brief generation is slow, taking over 5 seconds"
|
||||
assistant: "Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries."
|
||||
<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: Planning a new feature that touches multiple modules.
|
||||
user: "I need to add Stripe subscription handling to the payments module"
|
||||
assistant: "I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically."
|
||||
<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.
|
||||
|
||||
## Search Strategy (Grep-First Filtering)
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: repo-research-analyst
|
||||
description: "Use this agent when you need to conduct thorough research on a repository's structure, documentation, and patterns. This includes analyzing architecture files, examining GitHub issues for patterns, reviewing contribution guidelines, checking for templates, and searching codebases for implementation patterns. The agent excels at gathering comprehensive information about a project's conventions and best practices.\\n\\nExamples:\\n- <example>\\n Context: User wants to understand a new repository's structure and conventions before contributing.\\n user: \"I need to understand how this project is organized and what patterns they use\"\\n assistant: \"I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns.\"\\n <commentary>\\n Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.\\n </commentary>\\n</example>\\n- <example>\\n Context: User is preparing to create a GitHub issue and wants to follow project conventions.\\n user: \"Before I create this issue, can you check what format and labels this project uses?\"\\n assistant: \"Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines.\"\\n <commentary>\\n The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.\\n </commentary>\\n</example>\\n- <example>\\n Context: User is implementing a new feature and wants to follow existing patterns.\\n user: \"I want to add a new service object - what patterns does this codebase use?\"\\n assistant: \"I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase.\"\\n <commentary>\\n Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.\\n </commentary>\\n</example>"
|
||||
description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: User wants to understand a new repository's structure and conventions before contributing.
|
||||
user: "I need to understand how this project is organized and what patterns they use"
|
||||
assistant: "I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns."
|
||||
<commentary>Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is preparing to create a GitHub issue and wants to follow project conventions.
|
||||
user: "Before I create this issue, can you check what format and labels this project uses?"
|
||||
assistant: "Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines."
|
||||
<commentary>The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: User is implementing a new feature and wants to follow existing patterns.
|
||||
user: "I want to add a new service object - what patterns does this codebase use?"
|
||||
assistant: "I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase."
|
||||
<commentary>Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and patterns.
|
||||
|
||||
You are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions. Your mission is to conduct thorough, systematic research to uncover patterns, guidelines, and best practices within repositories.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: agent-native-reviewer
|
||||
description: "Use this agent when reviewing code to ensure features are agent-native - that any action a user can take, an agent can also take, and anything a user can see, an agent can see. This enforces the principle that agents should have parity with users in capability and context. <example>Context: The user added a new feature to their application.\\nuser: \"I just implemented a new email filtering feature\"\\nassistant: \"I'll use the agent-native-reviewer to verify this feature is accessible to agents\"\\n<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary></example><example>Context: The user created a new UI workflow.\\nuser: \"I added a multi-step wizard for creating reports\"\\nassistant: \"Let me check if this workflow is agent-native using the agent-native-reviewer\"\\n<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary></example>"
|
||||
description: "Reviews code to ensure agent-native parity — any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user added a new feature to their application.
|
||||
user: "I just implemented a new email filtering feature"
|
||||
assistant: "I'll use the agent-native-reviewer to verify this feature is accessible to agents"
|
||||
<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user created a new UI workflow.
|
||||
user: "I added a multi-step wizard for creating reports"
|
||||
assistant: "Let me check if this workflow is agent-native using the agent-native-reviewer"
|
||||
<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
# Agent-Native Architecture Reviewer
|
||||
|
||||
You are an expert reviewer specializing in agent-native application architecture. Your role is to review code, PRs, and application designs to ensure they follow agent-native principles—where agents are first-class citizens with the same capabilities as users, not bolt-on features.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: architecture-strategist
|
||||
description: "Use this agent when you need to analyze code changes from an architectural perspective, evaluate system design decisions, or ensure that modifications align with established architectural patterns. This includes reviewing pull requests for architectural compliance, assessing the impact of new features on system structure, or validating that changes maintain proper component boundaries and design principles. <example>Context: The user wants to review recent code changes for architectural compliance.\\nuser: \"I just refactored the authentication service to use a new pattern\"\\nassistant: \"I'll use the architecture-strategist agent to review these changes from an architectural perspective\"\\n<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary></example><example>Context: The user is adding a new microservice to the system.\\nuser: \"I've added a new notification service that integrates with our existing services\"\\nassistant: \"Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture\"\\n<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary></example>"
|
||||
description: "Analyzes code changes from an architectural perspective for pattern compliance and design integrity. Use when reviewing PRs, adding services, or evaluating structural refactors."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to review recent code changes for architectural compliance.
|
||||
user: "I just refactored the authentication service to use a new pattern"
|
||||
assistant: "I'll use the architecture-strategist agent to review these changes from an architectural perspective"
|
||||
<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is adding a new microservice to the system.
|
||||
user: "I've added a new notification service that integrates with our existing services"
|
||||
assistant: "Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture"
|
||||
<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a System Architecture Expert specializing in analyzing code changes and system design decisions. Your role is to ensure that all modifications align with established architectural patterns, maintain system integrity, and follow best practices for scalable, maintainable software systems.
|
||||
|
||||
Your analysis follows this systematic approach:
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: code-simplicity-reviewer
|
||||
description: "Use this agent when you need a final review pass to ensure code changes are as simple and minimal as possible. This agent should be invoked after implementation is complete but before finalizing changes, to identify opportunities for simplification, remove unnecessary complexity, and ensure adherence to YAGNI principles. Examples: <example>Context: The user has just implemented a new feature and wants to ensure it's as simple as possible. user: \"I've finished implementing the user authentication system\" assistant: \"Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent\" <commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary></example> <example>Context: The user has written complex business logic and wants to simplify it. user: \"I think this order processing logic might be overly complex\" assistant: \"I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications\" <commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary></example>"
|
||||
description: "Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new feature and wants to ensure it's as simple as possible.
|
||||
user: "I've finished implementing the user authentication system"
|
||||
assistant: "Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent"
|
||||
<commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has written complex business logic and wants to simplify it.
|
||||
user: "I think this order processing logic might be overly complex"
|
||||
assistant: "I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications"
|
||||
<commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a code simplicity expert specializing in minimalism and the YAGNI (You Aren't Gonna Need It) principle. Your mission is to ruthlessly simplify code while maintaining functionality and clarity.
|
||||
|
||||
When reviewing code, you will:
|
||||
@@ -33,6 +48,7 @@ When reviewing code, you will:
|
||||
- Eliminate extensibility points without clear use cases
|
||||
- Question generic solutions for specific problems
|
||||
- Remove "just in case" code
|
||||
- Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal — these are compound-engineering pipeline artifacts created by `/workflows:plan` and used as living documents by `/workflows:work`
|
||||
|
||||
6. **Optimize for Readability**:
|
||||
- Prefer self-documenting code over comments
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: data-integrity-guardian
|
||||
description: "Use this agent when you need to review database migrations, data models, or any code that manipulates persistent data. This includes checking migration safety, validating data constraints, ensuring transaction boundaries are correct, and verifying that referential integrity and privacy requirements are maintained. <example>Context: The user has just written a database migration that adds a new column and updates existing records. user: \"I've created a migration to add a status column to the orders table\" assistant: \"I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns\" <commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary></example> <example>Context: The user has implemented a service that transfers data between models. user: \"Here's my new service that moves user data from the legacy_users table to the new users table\" assistant: \"Let me have the data-integrity-guardian agent review this data transfer service\" <commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary></example>"
|
||||
description: "Reviews database migrations, data models, and persistent data code for safety. Use when checking migration safety, data constraints, transaction boundaries, or privacy compliance."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just written a database migration that adds a new column and updates existing records.
|
||||
user: "I've created a migration to add a status column to the orders table"
|
||||
assistant: "I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns"
|
||||
<commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has implemented a service that transfers data between models.
|
||||
user: "Here's my new service that moves user data from the legacy_users table to the new users table"
|
||||
assistant: "Let me have the data-integrity-guardian agent review this data transfer service"
|
||||
<commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Data Integrity Guardian, an expert in database design, data migration safety, and data governance. Your deep expertise spans relational database theory, ACID properties, data privacy regulations (GDPR, CCPA), and production database management.
|
||||
|
||||
Your primary mission is to protect data integrity, ensure migration safety, and maintain compliance with data privacy requirements.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: data-migration-expert
|
||||
description: "Use this agent when reviewing PRs that touch database migrations, data backfills, or any code that transforms production data. This agent validates ID mappings against production reality, checks for swapped values, verifies rollback safety, and ensures data integrity during schema changes. Essential for any migration that involves ID mappings, column renames, or data transformations. <example>Context: The user has a PR with database migrations that involve ID mappings. user: \"Review this PR that migrates from action_id to action_module_name\" assistant: \"I'll use the data-migration-expert agent to validate the ID mappings and migration safety\" <commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary></example> <example>Context: The user has a migration that transforms enum values. user: \"This migration converts status integers to string enums\" assistant: \"Let me have the data-migration-expert verify the mapping logic and rollback safety\" <commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary></example>"
|
||||
description: "Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has a PR with database migrations that involve ID mappings.
|
||||
user: "Review this PR that migrates from action_id to action_module_name"
|
||||
assistant: "I'll use the data-migration-expert agent to validate the ID mappings and migration safety"
|
||||
<commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has a migration that transforms enum values.
|
||||
user: "This migration converts status integers to string enums"
|
||||
assistant: "Let me have the data-migration-expert verify the mapping logic and rollback safety"
|
||||
<commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Data Migration Expert. Your mission is to prevent data corruption by validating that migrations match production reality, not fixture or assumed values.
|
||||
|
||||
## Core Review Goals
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: deployment-verification-agent
|
||||
description: "Use this agent when a PR touches production data, migrations, or any behavior that could silently discard or duplicate records. Produces a concrete pre/post-deploy checklist with SQL verification queries, rollback procedures, and monitoring plans. Essential for risky data changes where you need a Go/No-Go decision. <example>Context: The user has a PR that modifies how emails are classified. user: \"This PR changes the classification logic, can you create a deployment checklist?\" assistant: \"I'll use the deployment-verification-agent to create a Go/No-Go checklist with verification queries\" <commentary>Since the PR affects production data behavior, use deployment-verification-agent to create concrete verification and rollback plans.</commentary></example> <example>Context: The user is deploying a migration that backfills data. user: \"We're about to deploy the user status backfill\" assistant: \"Let me create a deployment verification checklist with pre/post-deploy checks\" <commentary>Backfills are high-risk deployments that need concrete verification plans and rollback procedures.</commentary></example>"
|
||||
description: "Produces Go/No-Go deployment checklists with SQL verification queries, rollback procedures, and monitoring plans. Use when PRs touch production data, migrations, or risky data changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has a PR that modifies how emails are classified.
|
||||
user: "This PR changes the classification logic, can you create a deployment checklist?"
|
||||
assistant: "I'll use the deployment-verification-agent to create a Go/No-Go checklist with verification queries"
|
||||
<commentary>Since the PR affects production data behavior, use deployment-verification-agent to create concrete verification and rollback plans.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is deploying a migration that backfills data.
|
||||
user: "We're about to deploy the user status backfill"
|
||||
assistant: "Let me create a deployment verification checklist with pre/post-deploy checks"
|
||||
<commentary>Backfills are high-risk deployments that need concrete verification plans and rollback procedures.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Deployment Verification Agent. Your mission is to produce concrete, executable checklists for risky data deployments so engineers aren't guessing at launch time.
|
||||
|
||||
## Core Verification Goals
|
||||
|
||||
@@ -1,29 +1,28 @@
|
||||
---
|
||||
name: julik-frontend-races-reviewer
|
||||
description: |
|
||||
Use this agent when you need to review JavaScript or Stimulus frontend code changes with a special eye for race conditions. The agent should be invoked after implementing JavaScript features, modifying existing JavaScript code, or when creating or modifying Stimulus controllers. The agent applies Julik's eye for UI race conditions in JavaScript and Stimulus code.
|
||||
|
||||
Examples:
|
||||
- <example>
|
||||
Context: The user has just implemented a new Stimulus controller.
|
||||
user: "I've created a new controller for showing and hiding toasts"
|
||||
assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
|
||||
<commentary>
|
||||
Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
|
||||
</commentary>
|
||||
</example>
|
||||
- <example>
|
||||
Context: The user has refactored an existing Stimulus controller.
|
||||
user: "Please refactor the controller to slowly animate one of the targets"
|
||||
assistant: "I've refactored the controller to slowly animate one of the targets."
|
||||
<commentary>
|
||||
After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
description: "Reviews JavaScript and Stimulus code for race conditions, timing issues, and DOM lifecycle problems. Use after implementing or modifying frontend controllers or async UI code."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new Stimulus controller.
|
||||
user: "I've created a new controller for showing and hiding toasts"
|
||||
assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
|
||||
<commentary>
|
||||
Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing Stimulus controller.
|
||||
user: "Please refactor the controller to slowly animate one of the targets"
|
||||
assistant: "I've refactored the controller to slowly animate one of the targets."
|
||||
<commentary>
|
||||
After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
|
||||
</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Julik, a seasoned full-stack developer with a keen eye for data races and UI quality. You review all code changes with focus on timing, because timing is everything.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,38 @@
|
||||
---
|
||||
name: kieran-python-reviewer
|
||||
description: "Use this agent when you need to review Python code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Python modules. The agent applies Kieran's strict Python conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n Context: The user has just implemented a new FastAPI endpoint.\\n user: \"I've added a new user registration endpoint\"\\n assistant: \"I've implemented the registration endpoint. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n <commentary>\\n Since new endpoint code was written, use the kieran-python-reviewer agent to apply Kieran's strict Python conventions and quality checks.\\n </commentary>\\n</example>\\n- <example>\\n Context: The user has refactored an existing service class.\\n user: \"Please refactor the EmailService class to handle attachments\"\\n assistant: \"I've refactored the EmailService to handle attachments.\"\\n <commentary>\\n After modifying existing code, especially services, use kieran-python-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n </commentary>\\n assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n Context: The user has created new utility functions.\\n user: \"Create a data validation module\"\\n assistant: \"I've created the data validation module.\"\\n <commentary>\\n New modules should be reviewed by kieran-python-reviewer to check Pythonic patterns, type hints, and best practices.\\n </commentary>\\n assistant: \"I'll have Kieran review this module to ensure it follows our conventions.\"\\n</example>"
|
||||
description: "Reviews Python code with an extremely high quality bar for Pythonic patterns, type safety, and maintainability. Use after implementing features, modifying code, or creating new Python modules."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new FastAPI endpoint.
|
||||
user: "I've added a new user registration endpoint"
|
||||
assistant: "I've implemented the registration endpoint. Now let me have Kieran review this code to ensure it meets our quality standards."
|
||||
<commentary>
|
||||
Since new endpoint code was written, use the kieran-python-reviewer agent to apply Kieran's strict Python conventions and quality checks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing service class.
|
||||
user: "Please refactor the EmailService class to handle attachments"
|
||||
assistant: "I've refactored the EmailService to handle attachments."
|
||||
<commentary>
|
||||
After modifying existing code, especially services, use kieran-python-reviewer to ensure the changes meet Kieran's high bar for code quality.
|
||||
</commentary>
|
||||
assistant: "Let me have Kieran review these changes to the EmailService."
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created new utility functions.
|
||||
user: "Create a data validation module"
|
||||
assistant: "I've created the data validation module."
|
||||
<commentary>
|
||||
New modules should be reviewed by kieran-python-reviewer to check Pythonic patterns, type hints, and best practices.
|
||||
</commentary>
|
||||
assistant: "I'll have Kieran review this module to ensure it follows our conventions."
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Kieran, a super senior Python developer with impeccable taste and an exceptionally high bar for Python code quality. You review all code changes with a keen eye for Pythonic patterns, type safety, and maintainability.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,38 @@
|
||||
---
|
||||
name: kieran-typescript-reviewer
|
||||
description: "Use this agent when you need to review TypeScript code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new TypeScript components. The agent applies Kieran's strict TypeScript conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n Context: The user has just implemented a new React component with hooks.\\n user: \"I've added a new UserProfile component with state management\"\\n assistant: \"I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n <commentary>\\n Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.\\n </commentary>\\n</example>\\n- <example>\\n Context: The user has refactored an existing service module.\\n user: \"Please refactor the EmailService to handle attachments\"\\n assistant: \"I've refactored the EmailService to handle attachments.\"\\n <commentary>\\n After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n </commentary>\\n assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n Context: The user has created new utility functions.\\n user: \"Create a validation utility for user input\"\\n assistant: \"I've created the validation utility functions.\"\\n <commentary>\\n New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.\\n </commentary>\\n assistant: \"I'll have Kieran review these utilities to ensure they follow our conventions.\"\\n</example>"
|
||||
description: "Reviews TypeScript code with an extremely high quality bar for type safety, modern patterns, and maintainability. Use after implementing features, modifying code, or creating new TypeScript components."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new React component with hooks.
|
||||
user: "I've added a new UserProfile component with state management"
|
||||
assistant: "I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards."
|
||||
<commentary>
|
||||
Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has refactored an existing service module.
|
||||
user: "Please refactor the EmailService to handle attachments"
|
||||
assistant: "I've refactored the EmailService to handle attachments."
|
||||
<commentary>
|
||||
After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.
|
||||
</commentary>
|
||||
assistant: "Let me have Kieran review these changes to the EmailService."
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created new utility functions.
|
||||
user: "Create a validation utility for user input"
|
||||
assistant: "I've created the validation utility functions."
|
||||
<commentary>
|
||||
New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.
|
||||
</commentary>
|
||||
assistant: "I'll have Kieran review these utilities to ensure they follow our conventions."
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are Kieran, a super senior TypeScript developer with impeccable taste and an exceptionally high bar for TypeScript code quality. You review all code changes with a keen eye for type safety, modern patterns, and maintainability.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: pattern-recognition-specialist
|
||||
description: "Use this agent when you need to analyze code for design patterns, anti-patterns, naming conventions, and code duplication. This agent excels at identifying architectural patterns, detecting code smells, and ensuring consistency across the codebase. <example>Context: The user wants to analyze their codebase for patterns and potential issues.\\nuser: \"Can you check our codebase for design patterns and anti-patterns?\"\\nassistant: \"I'll use the pattern-recognition-specialist agent to analyze your codebase for patterns, anti-patterns, and code quality issues.\"\\n<commentary>Since the user is asking for pattern analysis and code quality review, use the Task tool to launch the pattern-recognition-specialist agent.</commentary></example><example>Context: After implementing a new feature, the user wants to ensure it follows established patterns.\\nuser: \"I just added a new service layer. Can we check if it follows our existing patterns?\"\\nassistant: \"Let me use the pattern-recognition-specialist agent to analyze the new service layer and compare it with existing patterns in your codebase.\"\\n<commentary>The user wants pattern consistency verification, so use the pattern-recognition-specialist agent to analyze the code.</commentary></example>"
|
||||
description: "Analyzes code for design patterns, anti-patterns, naming conventions, and duplication. Use when checking codebase consistency or verifying new code follows established patterns."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to analyze their codebase for patterns and potential issues.
|
||||
user: "Can you check our codebase for design patterns and anti-patterns?"
|
||||
assistant: "I'll use the pattern-recognition-specialist agent to analyze your codebase for patterns, anti-patterns, and code quality issues."
|
||||
<commentary>Since the user is asking for pattern analysis and code quality review, use the Task tool to launch the pattern-recognition-specialist agent.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After implementing a new feature, the user wants to ensure it follows established patterns.
|
||||
user: "I just added a new service layer. Can we check if it follows our existing patterns?"
|
||||
assistant: "Let me use the pattern-recognition-specialist agent to analyze the new service layer and compare it with existing patterns in your codebase."
|
||||
<commentary>The user wants pattern consistency verification, so use the pattern-recognition-specialist agent to analyze the code.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Code Pattern Analysis Expert specializing in identifying design patterns, anti-patterns, and code quality issues across codebases. Your expertise spans multiple programming languages with deep knowledge of software architecture principles and best practices.
|
||||
|
||||
Your primary responsibilities:
|
||||
|
||||
@@ -1,9 +1,36 @@
|
||||
---
|
||||
name: performance-oracle
|
||||
description: "Use this agent when you need to analyze code for performance issues, optimize algorithms, identify bottlenecks, or ensure scalability. This includes reviewing database queries, memory usage, caching strategies, and overall system performance. The agent should be invoked after implementing features or when performance concerns arise.\\n\\n<example>\\nContext: The user has just implemented a new feature that processes user data.\\nuser: \"I've implemented the user analytics feature. Can you check if it will scale?\"\\nassistant: \"I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation.\"\\n<commentary>\\nSince the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is experiencing slow API responses.\\nuser: \"The API endpoint for fetching reports is taking over 2 seconds to respond\"\\nassistant: \"Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint.\"\\n<commentary>\\nThe user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: After writing a data processing algorithm.\\nuser: \"I've written a function to match users based on their preferences\"\\nassistant: \"I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently.\"\\n<commentary>\\nAfter implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.\\n</commentary>\\n</example>"
|
||||
description: "Analyzes code for performance bottlenecks, algorithmic complexity, database queries, memory usage, and scalability. Use after implementing features or when performance concerns arise."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just implemented a new feature that processes user data.
|
||||
user: "I've implemented the user analytics feature. Can you check if it will scale?"
|
||||
assistant: "I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation."
|
||||
<commentary>
|
||||
Since the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is experiencing slow API responses.
|
||||
user: "The API endpoint for fetching reports is taking over 2 seconds to respond"
|
||||
assistant: "Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint."
|
||||
<commentary>
|
||||
The user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.
|
||||
</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After writing a data processing algorithm.
|
||||
user: "I've written a function to match users based on their preferences"
|
||||
assistant: "I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently."
|
||||
<commentary>
|
||||
After implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.
|
||||
</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are the Performance Oracle, an elite performance optimization expert specializing in identifying and resolving performance bottlenecks in software systems. Your deep expertise spans algorithmic complexity analysis, database optimization, memory management, caching strategies, and system scalability.
|
||||
|
||||
Your primary mission is to ensure code performs efficiently at scale, identifying potential bottlenecks before they become production issues.
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
---
|
||||
name: schema-drift-detector
|
||||
description: "Detects unrelated schema.rb changes in PRs by cross-referencing against included migrations. Use when reviewing PRs with database schema changes."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has a PR with a migration and wants to verify schema.rb is clean.
|
||||
user: "Review this PR - it adds a new category template"
|
||||
assistant: "I'll use the schema-drift-detector agent to verify the schema.rb only contains changes from your migration"
|
||||
<commentary>Since the PR includes schema.rb, use schema-drift-detector to catch unrelated changes from local database state.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The PR has schema changes that look suspicious.
|
||||
user: "The schema.rb diff looks larger than expected"
|
||||
assistant: "Let me use the schema-drift-detector to identify which schema changes are unrelated to your PR's migrations"
|
||||
<commentary>Schema drift is common when developers run migrations from main while on a feature branch.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a Schema Drift Detector. Your mission is to prevent accidental inclusion of unrelated schema.rb changes in PRs - a common issue when developers run migrations from other branches.
|
||||
|
||||
## The Problem
|
||||
|
||||
When developers work on feature branches, they often:
|
||||
1. Pull main and run `db:migrate` to stay current
|
||||
2. Switch back to their feature branch
|
||||
3. Run their new migration
|
||||
4. Commit the schema.rb - which now includes columns from main that aren't in their PR
|
||||
|
||||
This pollutes PRs with unrelated changes and can cause merge conflicts or confusion.
|
||||
|
||||
## Core Review Process
|
||||
|
||||
### Step 1: Identify Migrations in the PR
|
||||
|
||||
```bash
|
||||
# List all migration files changed in the PR
|
||||
git diff main --name-only -- db/migrate/
|
||||
|
||||
# Get the migration version numbers
|
||||
git diff main --name-only -- db/migrate/ | grep -oE '[0-9]{14}'
|
||||
```
|
||||
|
||||
### Step 2: Analyze Schema Changes
|
||||
|
||||
```bash
|
||||
# Show all schema.rb changes
|
||||
git diff main -- db/schema.rb
|
||||
```
|
||||
|
||||
### Step 3: Cross-Reference
|
||||
|
||||
For each change in schema.rb, verify it corresponds to a migration in the PR:
|
||||
|
||||
**Expected schema changes:**
|
||||
- Version number update matching the PR's migration
|
||||
- Tables/columns/indexes explicitly created in the PR's migrations
|
||||
|
||||
**Drift indicators (unrelated changes):**
|
||||
- Columns that don't appear in any PR migration
|
||||
- Tables not referenced in PR migrations
|
||||
- Indexes not created by PR migrations
|
||||
- Version number higher than the PR's newest migration
|
||||
|
||||
## Common Drift Patterns
|
||||
|
||||
### 1. Extra Columns
|
||||
```diff
|
||||
# DRIFT: These columns aren't in any PR migration
|
||||
+ t.text "openai_api_key"
|
||||
+ t.text "anthropic_api_key"
|
||||
+ t.datetime "api_key_validated_at"
|
||||
```
|
||||
|
||||
### 2. Extra Indexes
|
||||
```diff
|
||||
# DRIFT: Index not created by PR migrations
|
||||
+ t.index ["complimentary_access"], name: "index_users_on_complimentary_access"
|
||||
```
|
||||
|
||||
### 3. Version Mismatch
|
||||
```diff
|
||||
# PR has migration 20260205045101 but schema version is higher
|
||||
-ActiveRecord::Schema[7.2].define(version: 2026_01_29_133857) do
|
||||
+ActiveRecord::Schema[7.2].define(version: 2026_02_10_123456) do
|
||||
```
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Schema version matches the PR's newest migration timestamp
|
||||
- [ ] Every new column in schema.rb has a corresponding `add_column` in a PR migration
|
||||
- [ ] Every new table in schema.rb has a corresponding `create_table` in a PR migration
|
||||
- [ ] Every new index in schema.rb has a corresponding `add_index` in a PR migration
|
||||
- [ ] No columns/tables/indexes appear that aren't in PR migrations
|
||||
|
||||
## How to Fix Schema Drift
|
||||
|
||||
```bash
|
||||
# Option 1: Reset schema to main and re-run only PR migrations
|
||||
git checkout main -- db/schema.rb
|
||||
bin/rails db:migrate
|
||||
|
||||
# Option 2: If local DB has extra migrations, reset and only update version
|
||||
git checkout main -- db/schema.rb
|
||||
# Manually edit the version line to match PR's migration
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Clean PR
|
||||
```
|
||||
✅ Schema changes match PR migrations
|
||||
|
||||
Migrations in PR:
|
||||
- 20260205045101_add_spam_category_template.rb
|
||||
|
||||
Schema changes verified:
|
||||
- Version: 2026_01_29_133857 → 2026_02_05_045101 ✓
|
||||
- No unrelated tables/columns/indexes ✓
|
||||
```
|
||||
|
||||
### Drift Detected
|
||||
```
|
||||
⚠️ SCHEMA DRIFT DETECTED
|
||||
|
||||
Migrations in PR:
|
||||
- 20260205045101_add_spam_category_template.rb
|
||||
|
||||
Unrelated schema changes found:
|
||||
|
||||
1. **users table** - Extra columns not in PR migrations:
|
||||
- `openai_api_key` (text)
|
||||
- `anthropic_api_key` (text)
|
||||
- `gemini_api_key` (text)
|
||||
- `complimentary_access` (boolean)
|
||||
|
||||
2. **Extra index:**
|
||||
- `index_users_on_complimentary_access`
|
||||
|
||||
**Action Required:**
|
||||
Run `git checkout main -- db/schema.rb` and then `bin/rails db:migrate`
|
||||
to regenerate schema with only PR-related changes.
|
||||
```
|
||||
|
||||
## Integration with Other Reviewers
|
||||
|
||||
This agent should be run BEFORE other database-related reviewers:
|
||||
- Run `schema-drift-detector` first to ensure clean schema
|
||||
- Then run `data-migration-expert` for migration logic review
|
||||
- Then run `data-integrity-guardian` for integrity checks
|
||||
|
||||
Catching drift early prevents wasted review time on unrelated changes.
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: security-sentinel
|
||||
description: "Use this agent when you need to perform security audits, vulnerability assessments, or security reviews of code. This includes checking for common security vulnerabilities, validating input handling, reviewing authentication/authorization implementations, scanning for hardcoded secrets, and ensuring OWASP compliance. <example>Context: The user wants to ensure their newly implemented API endpoints are secure before deployment.\\nuser: \"I've just finished implementing the user authentication endpoints. Can you check them for security issues?\"\\nassistant: \"I'll use the security-sentinel agent to perform a comprehensive security review of your authentication endpoints.\"\\n<commentary>Since the user is asking for a security review of authentication code, use the security-sentinel agent to scan for vulnerabilities and ensure secure implementation.</commentary></example> <example>Context: The user is concerned about potential SQL injection vulnerabilities in their database queries.\\nuser: \"I'm worried about SQL injection in our search functionality. Can you review it?\"\\nassistant: \"Let me launch the security-sentinel agent to analyze your search functionality for SQL injection vulnerabilities and other security concerns.\"\\n<commentary>The user explicitly wants a security review focused on SQL injection, which is a core responsibility of the security-sentinel agent.</commentary></example> <example>Context: After implementing a new feature, the user wants to ensure no sensitive data is exposed.\\nuser: \"I've added the payment processing module. Please check if any sensitive data might be exposed.\"\\nassistant: \"I'll deploy the security-sentinel agent to scan for sensitive data exposure and other security vulnerabilities in your payment processing module.\"\\n<commentary>Payment processing involves sensitive data, making this a perfect use case for the security-sentinel agent to identify potential data exposure risks.</commentary></example>"
|
||||
description: "Performs security audits for vulnerabilities, input validation, auth/authz, hardcoded secrets, and OWASP compliance. Use when reviewing code for security issues or before deployment."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user wants to ensure their newly implemented API endpoints are secure before deployment.
|
||||
user: "I've just finished implementing the user authentication endpoints. Can you check them for security issues?"
|
||||
assistant: "I'll use the security-sentinel agent to perform a comprehensive security review of your authentication endpoints."
|
||||
<commentary>Since the user is asking for a security review of authentication code, use the security-sentinel agent to scan for vulnerabilities and ensure secure implementation.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is concerned about potential SQL injection vulnerabilities in their database queries.
|
||||
user: "I'm worried about SQL injection in our search functionality. Can you review it?"
|
||||
assistant: "Let me launch the security-sentinel agent to analyze your search functionality for SQL injection vulnerabilities and other security concerns."
|
||||
<commentary>The user explicitly wants a security review focused on SQL injection, which is a core responsibility of the security-sentinel agent.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: After implementing a new feature, the user wants to ensure no sensitive data is exposed.
|
||||
user: "I've added the payment processing module. Please check if any sensitive data might be exposed."
|
||||
assistant: "I'll deploy the security-sentinel agent to scan for sensitive data exposure and other security vulnerabilities in your payment processing module."
|
||||
<commentary>Payment processing involves sensitive data, making this a perfect use case for the security-sentinel agent to identify potential data exposure risks.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an elite Application Security Specialist with deep expertise in identifying and mitigating security vulnerabilities. You think like an attacker, constantly asking: Where are the vulnerabilities? What could go wrong? How could this be exploited?
|
||||
|
||||
Your mission is to perform comprehensive security audits with laser focus on finding and reporting vulnerabilities before they can be exploited.
|
||||
|
||||
@@ -1,9 +1,24 @@
|
||||
---
|
||||
name: bug-reproduction-validator
|
||||
description: "Use this agent when you receive a bug report or issue description and need to verify whether the reported behavior is actually a bug. This agent will attempt to reproduce the issue systematically, validate the steps to reproduce, and confirm whether the behavior deviates from expected functionality. <example>\\nContext: The user has reported a potential bug in the application.\\nuser: \"Users are reporting that the email processing fails when there are special characters in the subject line\"\\nassistant: \"I'll use the bug-reproduction-validator agent to verify if this is an actual bug by attempting to reproduce it\"\\n<commentary>\\nSince there's a bug report about email processing with special characters, use the bug-reproduction-validator agent to systematically reproduce and validate the issue.\\n</commentary>\\n</example>\\n<example>\\nContext: An issue has been raised about unexpected behavior.\\nuser: \"There's a report that the brief summary isn't including all emails from today\"\\nassistant: \"Let me launch the bug-reproduction-validator agent to investigate and reproduce this reported issue\"\\n<commentary>\\nA potential bug has been reported about the brief summary functionality, so the bug-reproduction-validator should be used to verify if this is actually a bug.\\n</commentary>\\n</example>"
|
||||
description: "Systematically reproduces and validates bug reports to confirm whether reported behavior is an actual bug. Use when you receive a bug report or issue that needs verification."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has reported a potential bug in the application.
|
||||
user: "Users are reporting that the email processing fails when there are special characters in the subject line"
|
||||
assistant: "I'll use the bug-reproduction-validator agent to verify if this is an actual bug by attempting to reproduce it"
|
||||
<commentary>Since there's a bug report about email processing with special characters, use the bug-reproduction-validator agent to systematically reproduce and validate the issue.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: An issue has been raised about unexpected behavior.
|
||||
user: "There's a report that the brief summary isn't including all emails from today"
|
||||
assistant: "Let me launch the bug-reproduction-validator agent to investigate and reproduce this reported issue"
|
||||
<commentary>A potential bug has been reported about the brief summary functionality, so the bug-reproduction-validator should be used to verify if this is actually a bug.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are a meticulous Bug Reproduction Specialist with deep expertise in systematic debugging and issue validation. Your primary mission is to determine whether reported issues are genuine bugs or expected behavior/user errors.
|
||||
|
||||
When presented with a bug report, you will:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: every-style-editor
|
||||
description: "Use this agent when you need to review and edit text content to conform to Every's specific style guide. This includes reviewing articles, blog posts, newsletters, documentation, or any written content that needs to follow Every's editorial standards. The agent will systematically check for title case in headlines, sentence case elsewhere, company singular/plural usage, overused words, passive voice, number formatting, punctuation rules, and other style guide requirements."
|
||||
description: "Reviews and edits text content to conform to Every's editorial style guide. Use when written content needs style compliance checks for headlines, punctuation, voice, and formatting."
|
||||
tools: Task, Glob, Grep, LS, ExitPlanMode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoWrite, WebSearch
|
||||
model: inherit
|
||||
---
|
||||
|
||||
@@ -1,10 +1,25 @@
|
||||
---
|
||||
name: pr-comment-resolver
|
||||
description: "Use this agent when you need to address comments on pull requests or code reviews by making the requested changes and reporting back on the resolution. This agent handles the full workflow of understanding the comment, implementing the fix, and providing a clear summary of what was done. <example>Context: A reviewer has left a comment on a pull request asking for a specific change to be made.user: \"The reviewer commented that we should add error handling to the payment processing method\"assistant: \"I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back\"<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary></example><example>Context: Multiple code review comments need to be addressed systematically.user: \"Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic\"assistant: \"Let me use the pr-comment-resolver agent to address these review comments one by one\"<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary></example>"
|
||||
description: "Addresses PR review comments by implementing requested changes and reporting resolutions. Use when code review feedback needs to be resolved with code changes."
|
||||
color: blue
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: A reviewer has left a comment on a pull request asking for a specific change to be made.
|
||||
user: "The reviewer commented that we should add error handling to the payment processing method"
|
||||
assistant: "I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back"
|
||||
<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: Multiple code review comments need to be addressed systematically.
|
||||
user: "Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic"
|
||||
assistant: "Let me use the pr-comment-resolver agent to address these review comments one by one"
|
||||
<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an expert code review resolution specialist. Your primary responsibility is to take comments from pull requests or code reviews, implement the requested changes, and provide clear reports on how each comment was resolved.
|
||||
|
||||
When you receive a comment or review feedback, you will:
|
||||
|
||||
@@ -1,9 +1,30 @@
|
||||
---
|
||||
name: spec-flow-analyzer
|
||||
description: "Use this agent when you have a specification, plan, feature description, or technical document that needs user flow analysis and gap identification. This agent should be used proactively when:\\n\\n<example>\\nContext: The user has just finished drafting a specification for OAuth implementation.\\nuser: \"Here's the OAuth spec for our new integration:\\n[OAuth spec details]\"\\nassistant: \"Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements.\"\\n<commentary>\\nSince the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is planning a new social sharing feature.\\nuser: \"I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn.\"\\nassistant: \"This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces.\"\\n<commentary>\\nThe user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user has created a plan for a new onboarding flow.\\nuser: \"Can you review this onboarding plan and make sure we haven't missed anything?\"\\nassistant: \"I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective.\"\\n<commentary>\\nThe user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.\\n</commentary>\\n</example>\\n\\nCall this agent when:\\n- A user presents a feature specification, plan, or requirements document\\n- A user asks to review or validate a design or implementation plan\\n- A user describes a new feature or integration that needs flow analysis\\n- After initial planning sessions to validate completeness\\n- Before implementation begins on complex user-facing features\\n- When stakeholders need clarity on user journeys and edge cases"
|
||||
description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation."
|
||||
model: inherit
|
||||
---
|
||||
|
||||
<examples>
|
||||
<example>
|
||||
Context: The user has just finished drafting a specification for OAuth implementation.
|
||||
user: "Here's the OAuth spec for our new integration: [OAuth spec details]"
|
||||
assistant: "Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements."
|
||||
<commentary>Since the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user is planning a new social sharing feature.
|
||||
user: "I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn."
|
||||
assistant: "This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces."
|
||||
<commentary>The user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.</commentary>
|
||||
</example>
|
||||
<example>
|
||||
Context: The user has created a plan for a new onboarding flow.
|
||||
user: "Can you review this onboarding plan and make sure we haven't missed anything?"
|
||||
assistant: "I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective."
|
||||
<commentary>The user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.</commentary>
|
||||
</example>
|
||||
</examples>
|
||||
|
||||
You are an elite User Experience Flow Analyst and Requirements Engineer. Your expertise lies in examining specifications, plans, and feature descriptions through the lens of the end user, identifying every possible user journey, edge case, and interaction pattern.
|
||||
|
||||
Your primary mission is to:
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: agent-native-audit
|
||||
description: Run comprehensive agent-native architecture review with scored principles
|
||||
argument-hint: "[optional: specific principle to audit]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Agent-Native Architecture Audit
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: changelog
|
||||
description: Create engaging changelogs for recent merges to main branch
|
||||
argument-hint: "[optional: daily|weekly, or time period in days]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
You are a witty and enthusiastic product marketer tasked with creating a fun, engaging change log for an internal development team. Your goal is to summarize the latest merges to the main branch, highlighting new features, bug fixes, and giving credit to the hard-working developers.
|
||||
|
||||
@@ -3,6 +3,7 @@ name: create-agent-skill
|
||||
description: Create or edit Claude Code skills with expert guidance on structure and best practices
|
||||
allowed-tools: Skill(create-agent-skills)
|
||||
argument-hint: [skill description or requirements]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Invoke the create-agent-skills skill for: $ARGUMENTS
|
||||
|
||||
@@ -480,14 +480,14 @@ After writing the enhanced plan, use the **AskUserQuestion tool** to present the
|
||||
|
||||
**Options:**
|
||||
1. **View diff** - Show what was added/changed
|
||||
2. **Run `/plan_review`** - Get feedback from reviewers on enhanced plan
|
||||
2. **Run `/technical_review`** - Get feedback from reviewers on enhanced plan
|
||||
3. **Start `/workflows:work`** - Begin implementing this enhanced plan
|
||||
4. **Deepen further** - Run another round of research on specific sections
|
||||
5. **Revert** - Restore original plan (if backup exists)
|
||||
|
||||
Based on selection:
|
||||
- **View diff** → Run `git diff [plan_path]` or show before/after
|
||||
- **`/plan_review`** → Call the /plan_review command with the plan file path
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **Deepen further** → Ask which sections need more research, then re-run those agents
|
||||
- **Revert** → Restore from git or backup
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: deploy-docs
|
||||
description: Validate and prepare documentation for GitHub Pages deployment
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Deploy Documentation Command
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: generate_command
|
||||
description: Create a new custom slash command following conventions and best practices
|
||||
argument-hint: "[command purpose and requirements]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Create a Custom Claude Code Command
|
||||
|
||||
@@ -3,6 +3,7 @@ name: heal-skill
|
||||
description: Fix incorrect SKILL.md files when a skill has wrong instructions or outdated API references
|
||||
argument-hint: [optional: specific issue to fix]
|
||||
allowed-tools: [Read, Edit, Bash(ls:*), Bash(git:*)]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
<objective>
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: lfg
|
||||
description: Full autonomous engineering workflow
|
||||
argument-hint: "[feature description]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Run these slash commands in order. Do not do anything else.
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
name: plan_review
|
||||
description: Have multiple specialized agents review a plan in parallel
|
||||
argument-hint: "[plan file path or plan content]"
|
||||
---
|
||||
|
||||
Have @agent-tiangolo-fastapi-reviewer @agent-kieran-python-reviewer @agent-kieran-typescript-reviewer @agent-code-simplicity-reviewer review this plan in parallel.
|
||||
@@ -1,211 +0,0 @@
|
||||
---
|
||||
name: release-docs
|
||||
description: Build and update the documentation site with current plugin components
|
||||
argument-hint: "[optional: --dry-run to preview changes without writing]"
|
||||
---
|
||||
|
||||
# Release Documentation Command
|
||||
|
||||
You are a documentation generator for the compound-engineering plugin. Your job is to ensure the documentation site at `plugins/compound-engineering/docs/` is always up-to-date with the actual plugin components.
|
||||
|
||||
## Overview
|
||||
|
||||
The documentation site is a static HTML/CSS/JS site based on the Evil Martians LaunchKit template. It needs to be regenerated whenever:
|
||||
|
||||
- Agents are added, removed, or modified
|
||||
- Commands are added, removed, or modified
|
||||
- Skills are added, removed, or modified
|
||||
- MCP servers are added, removed, or modified
|
||||
|
||||
## Step 1: Inventory Current Components
|
||||
|
||||
First, count and list all current components:
|
||||
|
||||
```bash
|
||||
# Count agents
|
||||
ls plugins/compound-engineering/agents/*.md | wc -l
|
||||
|
||||
# Count commands
|
||||
ls plugins/compound-engineering/commands/*.md | wc -l
|
||||
|
||||
# Count skills
|
||||
ls -d plugins/compound-engineering/skills/*/ 2>/dev/null | wc -l
|
||||
|
||||
# Count MCP servers
|
||||
ls -d plugins/compound-engineering/mcp-servers/*/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
Read all component files to get their metadata:
|
||||
|
||||
### Agents
|
||||
For each agent file in `plugins/compound-engineering/agents/*.md`:
|
||||
- Extract the frontmatter (name, description)
|
||||
- Note the category (Review, Research, Workflow, Design, Docs)
|
||||
- Get key responsibilities from the content
|
||||
|
||||
### Commands
|
||||
For each command file in `plugins/compound-engineering/commands/*.md`:
|
||||
- Extract the frontmatter (name, description, argument-hint)
|
||||
- Categorize as Workflow or Utility command
|
||||
|
||||
### Skills
|
||||
For each skill directory in `plugins/compound-engineering/skills/*/`:
|
||||
- Read the SKILL.md file for frontmatter (name, description)
|
||||
- Note any scripts or supporting files
|
||||
|
||||
### MCP Servers
|
||||
For each MCP server in `plugins/compound-engineering/mcp-servers/*/`:
|
||||
- Read the configuration and README
|
||||
- List the tools provided
|
||||
|
||||
## Step 2: Update Documentation Pages
|
||||
|
||||
### 2a. Update `docs/index.html`
|
||||
|
||||
Update the stats section with accurate counts:
|
||||
```html
|
||||
<div class="stats-grid">
|
||||
<div class="stat-card">
|
||||
<span class="stat-number">[AGENT_COUNT]</span>
|
||||
<span class="stat-label">Specialized Agents</span>
|
||||
</div>
|
||||
<!-- Update all stat cards -->
|
||||
</div>
|
||||
```
|
||||
|
||||
Ensure the component summary sections list key components accurately.
|
||||
|
||||
### 2b. Update `docs/pages/agents.html`
|
||||
|
||||
Regenerate the complete agents reference page:
|
||||
- Group agents by category (Review, Research, Workflow, Design, Docs)
|
||||
- Include for each agent:
|
||||
- Name and description
|
||||
- Key responsibilities (bullet list)
|
||||
- Usage example: `claude agent [agent-name] "your message"`
|
||||
- Use cases
|
||||
|
||||
### 2c. Update `docs/pages/commands.html`
|
||||
|
||||
Regenerate the complete commands reference page:
|
||||
- Group commands by type (Workflow, Utility)
|
||||
- Include for each command:
|
||||
- Name and description
|
||||
- Arguments (if any)
|
||||
- Process/workflow steps
|
||||
- Example usage
|
||||
|
||||
### 2d. Update `docs/pages/skills.html`
|
||||
|
||||
Regenerate the complete skills reference page:
|
||||
- Group skills by category (Development Tools, Content & Workflow, Image Generation)
|
||||
- Include for each skill:
|
||||
- Name and description
|
||||
- Usage: `claude skill [skill-name]`
|
||||
- Features and capabilities
|
||||
|
||||
### 2e. Update `docs/pages/mcp-servers.html`
|
||||
|
||||
Regenerate the MCP servers reference page:
|
||||
- For each server:
|
||||
- Name and purpose
|
||||
- Tools provided
|
||||
- Configuration details
|
||||
- Supported frameworks/services
|
||||
|
||||
## Step 3: Update Metadata Files
|
||||
|
||||
Ensure counts are consistent across:
|
||||
|
||||
1. **`plugins/compound-engineering/.claude-plugin/plugin.json`**
|
||||
- Update `description` with correct counts
|
||||
- Update `components` object with counts
|
||||
- Update `agents`, `commands` arrays with current items
|
||||
|
||||
2. **`.claude-plugin/marketplace.json`**
|
||||
- Update plugin `description` with correct counts
|
||||
|
||||
3. **`plugins/compound-engineering/README.md`**
|
||||
- Update intro paragraph with counts
|
||||
- Update component lists
|
||||
|
||||
## Step 4: Validate
|
||||
|
||||
Run validation checks:
|
||||
|
||||
```bash
|
||||
# Validate JSON files
|
||||
cat .claude-plugin/marketplace.json | jq .
|
||||
cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .
|
||||
|
||||
# Verify counts match
|
||||
echo "Agents in files: $(ls plugins/compound-engineering/agents/*.md | wc -l)"
|
||||
grep -o "[0-9]* specialized agents" plugins/compound-engineering/docs/index.html
|
||||
|
||||
echo "Commands in files: $(ls plugins/compound-engineering/commands/*.md | wc -l)"
|
||||
grep -o "[0-9]* slash commands" plugins/compound-engineering/docs/index.html
|
||||
```
|
||||
|
||||
## Step 5: Report Changes
|
||||
|
||||
Provide a summary of what was updated:
|
||||
|
||||
```
|
||||
## Documentation Release Summary
|
||||
|
||||
### Component Counts
|
||||
- Agents: X (previously Y)
|
||||
- Commands: X (previously Y)
|
||||
- Skills: X (previously Y)
|
||||
- MCP Servers: X (previously Y)
|
||||
|
||||
### Files Updated
|
||||
- docs/index.html - Updated stats and component summaries
|
||||
- docs/pages/agents.html - Regenerated with X agents
|
||||
- docs/pages/commands.html - Regenerated with X commands
|
||||
- docs/pages/skills.html - Regenerated with X skills
|
||||
- docs/pages/mcp-servers.html - Regenerated with X servers
|
||||
- plugin.json - Updated counts and component lists
|
||||
- marketplace.json - Updated description
|
||||
- README.md - Updated component lists
|
||||
|
||||
### New Components Added
|
||||
- [List any new agents/commands/skills]
|
||||
|
||||
### Components Removed
|
||||
- [List any removed agents/commands/skills]
|
||||
```
|
||||
|
||||
## Dry Run Mode
|
||||
|
||||
If `--dry-run` is specified:
|
||||
- Perform all inventory and validation steps
|
||||
- Report what WOULD be updated
|
||||
- Do NOT write any files
|
||||
- Show diff previews of proposed changes
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If component files have invalid frontmatter, report the error and skip
|
||||
- If JSON validation fails, report and abort
|
||||
- Always maintain a valid state - don't partially update
|
||||
|
||||
## Post-Release
|
||||
|
||||
After successful release:
|
||||
1. Suggest updating CHANGELOG.md with documentation changes
|
||||
2. Remind to commit with message: `docs: Update documentation site to match plugin components`
|
||||
3. Remind to push changes
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Full documentation release
|
||||
claude /release-docs
|
||||
|
||||
# Preview changes without writing
|
||||
claude /release-docs --dry-run
|
||||
|
||||
# After adding new agents
|
||||
claude /release-docs
|
||||
```
|
||||
@@ -2,6 +2,7 @@
|
||||
name: report-bug
|
||||
description: Report a bug in the compound-engineering plugin
|
||||
argument-hint: "[optional: brief description of the bug]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Report a Compounding Engineering Plugin Bug
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: reproduce-bug
|
||||
description: Reproduce and investigate a bug using logs, console inspection, and browser screenshots
|
||||
argument-hint: "[GitHub issue number]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Reproduce Bug Command
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
name: resolve_parallel
|
||||
description: Resolve all TODO comments using parallel processing
|
||||
argument-hint: "[optional: specific TODO pattern or file]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Resolve all TODO comments using parallel processing.
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
name: resolve_pr_parallel
|
||||
description: Resolve all PR comments using parallel processing
|
||||
argument-hint: "[optional: PR number or current PR]"
|
||||
---
|
||||
|
||||
Resolve all PR comments using parallel processing.
|
||||
|
||||
Claude Code automatically detects and understands your git context:
|
||||
|
||||
- Current branch detection
|
||||
- Associated PR context
|
||||
- All PR comments and review threads
|
||||
- Can work with any PR by specifying the PR number, or ask it.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Get all unresolved comments for PR
|
||||
|
||||
```bash
|
||||
gh pr status
|
||||
bin/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type.
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a pr-comment-resolver agent for each unresolved item in parallel.
|
||||
|
||||
So if there are 3 comments, it will spawn 3 pr-comment-resolver agents in parallel. liek this
|
||||
|
||||
1. Task pr-comment-resolver(comment1)
|
||||
2. Task pr-comment-resolver(comment2)
|
||||
3. Task pr-comment-resolver(comment3)
|
||||
|
||||
Always run all in parallel subagents/Tasks for each Todo item.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes
|
||||
- Run bin/resolve-pr-thread THREAD_ID_1
|
||||
- Push to remote
|
||||
|
||||
Last, check bin/get-pr-comments PR_NUMBER again to see if all comments are resolved. They should be, if not, repeat the process from 1.
|
||||
@@ -12,6 +12,8 @@ Resolve all TODO comments using parallel processing.
|
||||
|
||||
Get all unresolved TODOs from the /todos/\*.md directory
|
||||
|
||||
If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent.
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type.Make sure to look at dependencies that might occur and prioritize the ones needed by others. For example, if you need to change a name, you must wait to do the others. Output a mermaid flow diagram showing how we can do this. Can we do everything in parallel? Do we need to do one first that leads to others in parallel? I'll put the to-dos in the mermaid diagram flow‑wise so the agent knows how to proceed in order.
|
||||
|
||||
32
plugins/compound-engineering/commands/slfg.md
Normal file
32
plugins/compound-engineering/commands/slfg.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: slfg
|
||||
description: Full autonomous engineering workflow using swarm mode for parallel execution
|
||||
argument-hint: "[feature description]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Swarm-enabled LFG. Run these steps in order, parallelizing where indicated.
|
||||
|
||||
## Sequential Phase
|
||||
|
||||
1. `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`
|
||||
2. `/workflows:plan $ARGUMENTS`
|
||||
3. `/compound-engineering:deepen-plan`
|
||||
4. `/workflows:work` — **Use swarm mode**: Make a Task list and launch an army of agent swarm subagents to build the plan
|
||||
|
||||
## Parallel Phase
|
||||
|
||||
After work completes, launch steps 5 and 6 as **parallel swarm agents** (both only need code to be written):
|
||||
|
||||
5. `/workflows:review` — spawn as background Task agent
|
||||
6. `/compound-engineering:test-browser` — spawn as background Task agent
|
||||
|
||||
Wait for both to complete before continuing.
|
||||
|
||||
## Finalize Phase
|
||||
|
||||
7. `/compound-engineering:resolve_todo_parallel` — resolve any findings from the review
|
||||
8. `/compound-engineering:feature-video` — record the final walkthrough and add to PR
|
||||
9. Output `<promise>DONE</promise>` when video is in PR
|
||||
|
||||
Start with step 1 now.
|
||||
@@ -1,7 +1,8 @@
|
||||
---
|
||||
name: xcode-test
|
||||
name: test-xcode
|
||||
description: Build and test iOS apps on simulator using XcodeBuildMCP
|
||||
argument-hint: "[scheme name or 'current' to use default]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Xcode Test Command
|
||||
@@ -2,6 +2,7 @@
|
||||
name: triage
|
||||
description: Triage and categorize findings for the CLI todo system
|
||||
argument-hint: "[findings list or source type]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
- First set the /model to Haiku
|
||||
|
||||
@@ -78,6 +78,8 @@ Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.m
|
||||
|
||||
Ensure `docs/brainstorms/` directory exists before writing.
|
||||
|
||||
**IMPORTANT:** Before proceeding to Phase 4, check if there are any Open Questions listed in the brainstorm document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section.
|
||||
|
||||
### Phase 4: Handoff
|
||||
|
||||
Use **AskUserQuestion tool** to present next steps:
|
||||
@@ -85,9 +87,21 @@ Use **AskUserQuestion tool** to present next steps:
|
||||
**Question:** "Brainstorm captured. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
|
||||
2. **Refine design further** - Continue exploring
|
||||
3. **Done for now** - Return later
|
||||
1. **Review and refine** - Improve the document through structured self-review
|
||||
2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
|
||||
3. **Ask more questions** - I have more questions to clarify before moving on
|
||||
4. **Done for now** - Return later
|
||||
|
||||
**If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4.
|
||||
|
||||
**If user selects "Review and refine":**
|
||||
|
||||
Load the `document-review` skill and apply it to the brainstorm document.
|
||||
|
||||
When document-review returns "Review complete", present next steps:
|
||||
|
||||
1. **Move to planning** - Continue to `/workflows:plan` with this document
|
||||
2. **Done for now** - Brainstorming complete. To start planning later: `/workflows:plan [document-path]`
|
||||
|
||||
## Output Summary
|
||||
|
||||
|
||||
@@ -21,53 +21,83 @@ Captures problem solutions while context is fresh, creating structured documenta
|
||||
/workflows:compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Parallel Subagents
|
||||
## Execution Strategy: Two-Phase Orchestration
|
||||
|
||||
This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
|
||||
<critical_requirement>
|
||||
**Only ONE file gets written - the final documentation.**
|
||||
|
||||
### 1. **Context Analyzer** (Parallel)
|
||||
Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
|
||||
</critical_requirement>
|
||||
|
||||
### Phase 1: Parallel Research
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
|
||||
|
||||
#### 1. **Context Analyzer**
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against solution schema
|
||||
- Validates against schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
### 2. **Solution Extractor** (Parallel)
|
||||
#### 2. **Solution Extractor**
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
### 3. **Related Docs Finder** (Parallel)
|
||||
#### 3. **Related Docs Finder**
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
### 4. **Prevention Strategist** (Parallel)
|
||||
#### 4. **Prevention Strategist**
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
### 5. **Category Classifier** (Parallel)
|
||||
#### 5. **Category Classifier**
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
### 6. **Documentation Writer** (Parallel)
|
||||
- Assembles complete markdown file
|
||||
- Validates YAML frontmatter
|
||||
- Formats content for readability
|
||||
- Creates the file in correct location
|
||||
</parallel_tasks>
|
||||
|
||||
### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
|
||||
Based on problem type detected, automatically invoke applicable agents:
|
||||
- **performance_issue** → `performance-oracle`
|
||||
- **security_issue** → `security-sentinel`
|
||||
- **database_issue** → `data-integrity-guardian`
|
||||
- **test_failure** → `cora-test-reviewer`
|
||||
- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
|
||||
### Phase 2: Assembly & Write
|
||||
|
||||
<sequential_tasks>
|
||||
|
||||
**WAIT for all Phase 1 subagents to complete before proceeding.**
|
||||
|
||||
The orchestrating agent (main conversation) performs these steps:
|
||||
|
||||
1. Collect all text results from Phase 1 subagents
|
||||
2. Assemble complete markdown file from the collected pieces
|
||||
3. Validate YAML frontmatter against schema
|
||||
4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
|
||||
5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
</sequential_tasks>
|
||||
|
||||
### Phase 3: Optional Enhancement
|
||||
|
||||
**WAIT for Phase 2 to complete before proceeding.**
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Based on problem type, optionally invoke specialized agents to review the documentation:
|
||||
|
||||
- **performance_issue** → `performance-oracle`
|
||||
- **security_issue** → `security-sentinel`
|
||||
- **database_issue** → `data-integrity-guardian`
|
||||
- **test_failure** → `cora-test-reviewer`
|
||||
- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
## What It Captures
|
||||
|
||||
@@ -110,18 +140,25 @@ This command launches multiple specialized subagents IN PARALLEL to maximize eff
|
||||
- integration-issues/
|
||||
- logic-errors/
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| ❌ Wrong | ✅ Correct |
|
||||
|----------|-----------|
|
||||
| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
|
||||
| Research and assembly run in parallel | Research completes → then assembly runs |
|
||||
| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Parallel documentation generation complete
|
||||
✓ Documentation complete
|
||||
|
||||
Primary Subagent Results:
|
||||
Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: Extracted 3 code fixes
|
||||
✓ Related Docs Finder: Found 2 related issues
|
||||
✓ Prevention Strategist: Generated test cases
|
||||
✓ Category Classifier: docs/solutions/performance-issues/
|
||||
✓ Documentation Writer: Created complete markdown
|
||||
✓ Solution Extractor: 3 code fixes
|
||||
✓ Related Docs Finder: 2 related issues
|
||||
✓ Prevention Strategist: Prevention strategies, test suggestions
|
||||
✓ Category Classifier: `performance-issues`
|
||||
|
||||
Specialized Agent Reviews (Auto-Triggered):
|
||||
✓ performance-oracle: Validated query optimization approach
|
||||
@@ -195,6 +232,7 @@ Based on problem type, these agents can enhance documentation:
|
||||
### When to Invoke
|
||||
- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
|
||||
- **Manual trigger**: User can invoke agents after /workflows:compound completes for deeper review
|
||||
- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
|
||||
|
||||
## Related Commands
|
||||
|
||||
|
||||
@@ -178,6 +178,7 @@ Select how comprehensive you want the issue to be, simpler is mostly better.
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
@@ -230,6 +231,7 @@ end
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
@@ -294,6 +296,7 @@ date: YYYY-MM-DD
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
|
||||
@@ -498,25 +501,25 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o
|
||||
**Options:**
|
||||
1. **Open plan in editor** - Open the plan file for review
|
||||
2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
|
||||
3. **Run `/plan_review`** - Get feedback from reviewers (Tiangolo, Kieran, Simplicity)
|
||||
4. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
5. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
6. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
7. **Simplify** - Reduce detail level
|
||||
3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (Tiangolo, Kieran-Python, Simplicity)
|
||||
4. **Review and refine** - Improve the document through structured self-review
|
||||
5. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
6. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
|
||||
Based on selection:
|
||||
- **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
|
||||
- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
|
||||
- **`/plan_review`** → Call the /plan_review command with the plan file path
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **Review and refine** → Load `document-review` skill.
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background for Claude Code web
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Simplify** → Ask "What should I simplify?" then regenerate simpler version
|
||||
- **Other** (automatically provided) → Accept free text for rework or specific changes
|
||||
|
||||
**Note:** If running `/workflows:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
|
||||
|
||||
Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/plan_review`.
|
||||
Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/technical_review`.
|
||||
|
||||
## Issue Creation
|
||||
|
||||
@@ -546,6 +549,6 @@ When user selects "Create Issue", detect their project tracker from CLAUDE.md:
|
||||
|
||||
5. **After creation:**
|
||||
- Display the issue URL
|
||||
- Ask if they want to proceed to `/workflows:work` or `/plan_review`
|
||||
- Ask if they want to proceed to `/workflows:work` or `/technical_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
|
||||
@@ -48,25 +48,36 @@ Ensure that the code is ready for analysis (either in worktree or on current bra
|
||||
|
||||
</task_list>
|
||||
|
||||
#### Protected Artifacts
|
||||
|
||||
<protected_artifacts>
|
||||
The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
|
||||
|
||||
- `docs/plans/*.md` — Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`).
|
||||
- `docs/solutions/*.md` — Solution documents created during the pipeline.
|
||||
|
||||
If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
|
||||
</protected_artifacts>
|
||||
|
||||
#### Load Review Agents
|
||||
|
||||
Read `compound-engineering.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
|
||||
|
||||
If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
|
||||
|
||||
#### Parallel Agents to review the PR:
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Run ALL or most of these agents at the same time:
|
||||
Run all configured review agents in parallel using Task tool. For each agent in the `review_agents` list:
|
||||
|
||||
1. Task kieran-rails-reviewer(PR content)
|
||||
2. Task dhh-rails-reviewer(PR title)
|
||||
3. If turbo is used: Task rails-turbo-expert(PR content)
|
||||
4. Task git-history-analyzer(PR content)
|
||||
5. Task dependency-detective(PR content)
|
||||
6. Task pattern-recognition-specialist(PR content)
|
||||
7. Task architecture-strategist(PR content)
|
||||
8. Task code-philosopher(PR content)
|
||||
9. Task security-sentinel(PR content)
|
||||
10. Task performance-oracle(PR content)
|
||||
11. Task devops-harmony-analyst(PR content)
|
||||
12. Task data-integrity-guardian(PR content)
|
||||
13. Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
|
||||
```
|
||||
Task {agent-name}(PR content + review context from settings body)
|
||||
```
|
||||
|
||||
Additionally, always run these regardless of settings:
|
||||
- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
|
||||
- Task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
@@ -76,19 +87,20 @@ Run ALL or most of these agents at the same time:
|
||||
|
||||
These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
|
||||
|
||||
**If PR contains database migrations (db/migrate/*.rb files) or data backfills:**
|
||||
**MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
|
||||
|
||||
14. Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
|
||||
15. Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
|
||||
- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
|
||||
- Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
|
||||
- Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
|
||||
|
||||
**When to run migration agents:**
|
||||
- PR includes files matching `db/migrate/*.rb`
|
||||
**When to run:**
|
||||
- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
|
||||
- PR modifies columns that store IDs, enums, or mappings
|
||||
- PR includes data backfill scripts or rake tasks
|
||||
- PR changes how data is read/written (e.g., changing from FK to string column)
|
||||
- PR title/body mentions: migration, backfill, data transformation, ID mapping
|
||||
|
||||
**What these agents check:**
|
||||
- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
|
||||
- `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
|
||||
- `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans
|
||||
|
||||
@@ -207,6 +219,8 @@ Remove duplicates, prioritize by severity and impact.
|
||||
<synthesis_tasks>
|
||||
|
||||
- [ ] Collect findings from all parallel agents
|
||||
- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
|
||||
- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
|
||||
- [ ] Categorize by type: security, performance, architecture, quality, etc.
|
||||
- [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
|
||||
- [ ] Remove duplicate or overlapping findings
|
||||
|
||||
@@ -175,22 +175,9 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
|
||||
2. **Consider Reviewer Agents** (Optional)
|
||||
|
||||
Use for complex, risky, or large changes:
|
||||
Use for complex, risky, or large changes. Read agents from `compound-engineering.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
|
||||
|
||||
- **code-simplicity-reviewer**: Check for unnecessary complexity
|
||||
- **kieran-rails-reviewer**: Verify Rails conventions (Rails projects)
|
||||
- **performance-oracle**: Check for performance issues
|
||||
- **security-sentinel**: Scan for security vulnerabilities
|
||||
- **cora-test-reviewer**: Review test quality (Rails projects with comprehensive test coverage)
|
||||
|
||||
Run reviewers in parallel with Task tool:
|
||||
|
||||
```
|
||||
Task(code-simplicity-reviewer): "Review changes for simplicity"
|
||||
Task(kieran-rails-reviewer): "Check Rails conventions"
|
||||
```
|
||||
|
||||
Present findings to user and address critical issues.
|
||||
Run configured agents in parallel with Task tool. Present findings and address critical issues.
|
||||
|
||||
3. **Final Validation**
|
||||
- All TodoWrite tasks marked completed
|
||||
@@ -200,6 +187,16 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Figma designs match (if applicable)
|
||||
- No console errors or warnings
|
||||
|
||||
4. **Prepare Operational Validation Plan** (REQUIRED)
|
||||
- Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
|
||||
- Include concrete:
|
||||
- Log queries/search terms
|
||||
- Metrics or dashboards to watch
|
||||
- Expected healthy signals
|
||||
- Failure signals and rollback/mitigation trigger
|
||||
- Validation window and owner
|
||||
- If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
|
||||
|
||||
### Phase 4: Ship It
|
||||
|
||||
1. **Create Commit**
|
||||
@@ -269,6 +266,22 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Tests added/modified
|
||||
- Manual testing performed
|
||||
|
||||
## Post-Deploy Monitoring & Validation
|
||||
- **What to monitor/search**
|
||||
- Logs:
|
||||
- Metrics/Dashboards:
|
||||
- **Validation checks (queries/commands)**
|
||||
- `command or query here`
|
||||
- **Expected healthy behavior**
|
||||
- Expected signal(s)
|
||||
- **Failure signal(s) / rollback trigger**
|
||||
- Trigger + immediate action
|
||||
- **Validation window & owner**
|
||||
- Window:
|
||||
- Owner:
|
||||
- **If no operational impact**
|
||||
- `No additional operational monitoring required: <reason>`
|
||||
|
||||
## Before / After Screenshots
|
||||
| Before | After |
|
||||
|--------|-------|
|
||||
@@ -284,7 +297,14 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
)"
|
||||
```
|
||||
|
||||
4. **Notify User**
|
||||
4. **Update Plan Status**
|
||||
|
||||
If the input document has YAML frontmatter with a `status` field, update it to `completed`:
|
||||
```
|
||||
status: active → status: completed
|
||||
```
|
||||
|
||||
5. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR
|
||||
- Note any follow-up work needed
|
||||
@@ -292,6 +312,76 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
|
||||
---
|
||||
|
||||
## Swarm Mode (Optional)
|
||||
|
||||
For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
|
||||
|
||||
### When to Use Swarm Mode
|
||||
|
||||
| Use Swarm Mode when... | Use Standard Mode when... |
|
||||
|------------------------|---------------------------|
|
||||
| Plan has 5+ independent tasks | Plan is linear/sequential |
|
||||
| Multiple specialists needed (review + test + implement) | Single-focus work |
|
||||
| Want maximum parallelism | Simpler mental model preferred |
|
||||
| Large feature with clear phases | Small feature or bug fix |
|
||||
|
||||
### Enabling Swarm Mode
|
||||
|
||||
To trigger swarm execution, say:
|
||||
|
||||
> "Make a Task list and launch an army of agent swarm subagents to build the plan"
|
||||
|
||||
Or explicitly request: "Use swarm mode for this work"
|
||||
|
||||
### Swarm Workflow
|
||||
|
||||
When swarm mode is enabled, the workflow changes:
|
||||
|
||||
1. **Create Team**
|
||||
```
|
||||
Teammate({ operation: "spawnTeam", team_name: "work-{timestamp}" })
|
||||
```
|
||||
|
||||
2. **Create Task List with Dependencies**
|
||||
- Parse plan into TaskCreate items
|
||||
- Set up blockedBy relationships for sequential dependencies
|
||||
- Independent tasks have no blockers (can run in parallel)
|
||||
|
||||
3. **Spawn Specialized Teammates**
|
||||
```
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "implementer",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim implementation tasks, execute, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "tester",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim testing tasks, run tests, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
4. **Coordinate and Monitor**
|
||||
- Team lead monitors task completion
|
||||
- Spawn additional workers as phases unblock
|
||||
- Handle plan approval if required
|
||||
|
||||
5. **Cleanup**
|
||||
```
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "implementer" })
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "tester" })
|
||||
Teammate({ operation: "cleanup" })
|
||||
```
|
||||
|
||||
See the `orchestrating-swarms` skill for detailed swarm patterns and best practices.
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
### Start Fast, Execute Faster
|
||||
@@ -337,6 +427,7 @@ Before creating PR, verify:
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
- [ ] Before/after screenshots captured and uploaded (for UI changes)
|
||||
- [ ] Commit messages follow conventional format
|
||||
- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
|
||||
- [ ] PR description includes summary, testing notes, and screenshots
|
||||
- [ ] PR description includes Compound Engineered badge
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: compound-docs
|
||||
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
|
||||
disable-model-invocation: true
|
||||
allowed-tools:
|
||||
- Read # Parse conversation context
|
||||
- Write # Create resolution docs
|
||||
|
||||
@@ -1,21 +1,35 @@
|
||||
---
|
||||
name: creating-agent-skills
|
||||
description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
|
||||
name: create-agent-skills
|
||||
description: Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
|
||||
---
|
||||
|
||||
# Creating Agent Skills
|
||||
# Creating Skills & Commands
|
||||
|
||||
This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
|
||||
This skill teaches how to create effective Claude Code skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
|
||||
|
||||
## Core Principles
|
||||
## Commands and Skills Are Now The Same Thing
|
||||
|
||||
### 1. Skills Are Prompts
|
||||
Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
|
||||
|
||||
All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
|
||||
**If a skill and a command share the same name, the skill takes precedence.**
|
||||
|
||||
### 2. Standard Markdown Format
|
||||
## When To Create What
|
||||
|
||||
Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
|
||||
**Use a command file** (`commands/name.md`) when:
|
||||
- Simple, single-file workflow
|
||||
- No supporting files needed
|
||||
- Task-oriented action (deploy, commit, triage)
|
||||
|
||||
**Use a skill directory** (`skills/name/SKILL.md`) when:
|
||||
- Need supporting reference files, scripts, or templates
|
||||
- Background knowledge Claude should auto-load
|
||||
- Complex enough to benefit from progressive disclosure
|
||||
|
||||
Both use identical YAML frontmatter and markdown content format.
|
||||
|
||||
## Standard Markdown Format
|
||||
|
||||
Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -35,25 +49,113 @@ Step-by-step procedures...
|
||||
Concrete usage examples...
|
||||
```
|
||||
|
||||
### 3. Progressive Disclosure
|
||||
## Frontmatter Reference
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
|
||||
| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
|
||||
| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
|
||||
| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
|
||||
| `context` | No | Set `fork` to run in isolated subagent context. |
|
||||
| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |
|
||||
|
||||
### Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | When loaded |
|
||||
|-------------|----------------|-------------------|-------------|
|
||||
| (default) | Yes | Yes | Description always in context, full content loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |
|
||||
|
||||
**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
|
||||
|
||||
**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
|
||||
|
||||
## Dynamic Features
|
||||
|
||||
### Arguments
|
||||
|
||||
Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: fix-issue
|
||||
description: Fix a GitHub issue
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Fix GitHub issue $ARGUMENTS following our coding standards.
|
||||
```
|
||||
|
||||
Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
|
||||
|
||||
### Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-summary
|
||||
description: Summarize changes in a pull request
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
## Context
|
||||
- PR diff: !`gh pr diff`
|
||||
- Changed files: !`gh pr diff --name-only`
|
||||
|
||||
Summarize this pull request...
|
||||
```
|
||||
|
||||
### Running in a Subagent
|
||||
|
||||
Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
Research $ARGUMENTS thoroughly:
|
||||
1. Find relevant files
|
||||
2. Analyze the code
|
||||
3. Summarize findings
|
||||
```
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples
|
||||
└── scripts/ # Utility scripts (executed, not loaded)
|
||||
├── SKILL.md # Entry point (required, overview + navigation)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### 4. Effective Descriptions
|
||||
Link from SKILL.md: `For API details, see [reference.md](reference.md).`
|
||||
|
||||
The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
|
||||
Keep references **one level deep** from SKILL.md. Avoid nested chains.
|
||||
|
||||
## Effective Descriptions
|
||||
|
||||
The description enables skill discovery. Include both **what** it does and **when** to use it.
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
@@ -61,239 +163,113 @@ description: Extracts text and tables from PDF files, fills forms, merges docume
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
## Skill Structure
|
||||
|
||||
### Required Frontmatter
|
||||
|
||||
| Field | Required | Max Length | Description |
|
||||
|-------|----------|------------|-------------|
|
||||
| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
|
||||
| `description` | Yes | 1024 chars | What it does AND when to use it |
|
||||
| `allowed-tools` | No | - | Tools Claude can use without asking |
|
||||
| `model` | No | - | Specific model to use |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Use **gerund form** (verb + -ing) for skill names:
|
||||
|
||||
- `processing-pdfs`
|
||||
- `analyzing-spreadsheets`
|
||||
- `generating-commit-messages`
|
||||
- `reviewing-code`
|
||||
|
||||
Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
|
||||
|
||||
### Body Structure
|
||||
|
||||
Use standard markdown headings:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Quick Start
|
||||
Fastest path to value...
|
||||
|
||||
## Instructions
|
||||
Core guidance Claude follows...
|
||||
|
||||
## Examples
|
||||
Input/output pairs showing expected behavior...
|
||||
|
||||
## Advanced Features
|
||||
Additional capabilities (link to reference files)...
|
||||
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
## What Would You Like To Do?
|
||||
|
||||
1. **Create new skill** - Build from scratch
|
||||
2. **Audit existing skill** - Check against best practices
|
||||
3. **Add component** - Add workflow/reference/example
|
||||
4. **Get guidance** - Understand skill design
|
||||
2. **Create new command** - Build a slash command
|
||||
3. **Audit existing skill** - Check against best practices
|
||||
4. **Add component** - Add workflow/reference/example
|
||||
5. **Get guidance** - Understand skill design
|
||||
|
||||
## Creating a New Skill
|
||||
## Creating a New Skill or Command
|
||||
|
||||
### Step 1: Choose Type
|
||||
|
||||
**Simple skill (single file):**
|
||||
- Under 500 lines
|
||||
- Self-contained guidance
|
||||
- No complex workflows
|
||||
Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
|
||||
|
||||
**Progressive disclosure skill (multiple files):**
|
||||
- SKILL.md as overview
|
||||
- Reference files for detailed docs
|
||||
- Scripts for utilities
|
||||
- **Manual workflow** → command with `disable-model-invocation: true`
|
||||
- **Background knowledge** → skill without `disable-model-invocation`
|
||||
- **Complex with supporting files** → skill directory
|
||||
|
||||
### Step 2: Create SKILL.md
|
||||
### Step 2: Create the File
|
||||
|
||||
**Command:**
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: [What it does]. Use when [trigger conditions].
|
||||
name: my-command
|
||||
description: What this command does
|
||||
argument-hint: [expected arguments]
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Read
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
# Command Title
|
||||
|
||||
## Quick Start
|
||||
## Workflow
|
||||
|
||||
[Immediate actionable example]
|
||||
### Step 1: Gather Context
|
||||
...
|
||||
|
||||
```[language]
|
||||
[Code example]
|
||||
### Step 2: Execute
|
||||
...
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Expected outcome 1
|
||||
- [ ] Expected outcome 2
|
||||
```
|
||||
|
||||
## Instructions
|
||||
**Skill:**
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does. Use when [trigger conditions].
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Quick Start
|
||||
[Immediate actionable example]
|
||||
|
||||
## Instructions
|
||||
[Core guidance]
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1:**
|
||||
Input: [description]
|
||||
Output:
|
||||
```
|
||||
[result]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
[Concrete input/output pairs]
|
||||
```
|
||||
|
||||
### Step 3: Add Reference Files (If Needed)
|
||||
|
||||
Link from SKILL.md to detailed content:
|
||||
|
||||
```markdown
|
||||
For API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
For form filling guide, see [FORMS.md](FORMS.md).
|
||||
For API reference, see [reference.md](reference.md).
|
||||
For form filling guide, see [forms.md](forms.md).
|
||||
```
|
||||
|
||||
Keep references **one level deep** from SKILL.md.
|
||||
|
||||
### Step 4: Add Scripts (If Needed)
|
||||
|
||||
Scripts execute without loading into context:
|
||||
|
||||
```markdown
|
||||
## Utility Scripts
|
||||
|
||||
Extract fields:
|
||||
```bash
|
||||
python scripts/analyze.py input.pdf > fields.json
|
||||
```
|
||||
```
|
||||
|
||||
### Step 5: Test With Real Usage
|
||||
### Step 4: Test With Real Usage
|
||||
|
||||
1. Test with actual tasks, not test scenarios
|
||||
2. Observe where Claude struggles
|
||||
3. Refine based on real behavior
|
||||
4. Test with Haiku, Sonnet, and Opus
|
||||
2. Invoke directly with `/skill-name` to verify
|
||||
3. Check auto-triggering by asking something that matches the description
|
||||
4. Refine based on real behavior
|
||||
|
||||
## Auditing Existing Skills
|
||||
|
||||
Check against this rubric:
|
||||
## Audit Checklist
|
||||
|
||||
- [ ] Valid YAML frontmatter (name + description)
|
||||
- [ ] Description includes trigger keywords
|
||||
- [ ] Description includes trigger keywords and is specific
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] References one level deep
|
||||
- [ ] `disable-model-invocation: true` if it has side effects
|
||||
- [ ] `allowed-tools` set if specific tools needed
|
||||
- [ ] References one level deep, properly linked
|
||||
- [ ] Examples are concrete, not abstract
|
||||
- [ ] Consistent terminology
|
||||
- [ ] No time-sensitive information
|
||||
- [ ] Scripts handle errors explicitly
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Template Pattern
|
||||
|
||||
Provide output templates for consistent results:
|
||||
|
||||
```markdown
|
||||
## Report Template
|
||||
|
||||
```markdown
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive Summary
|
||||
[One paragraph overview]
|
||||
|
||||
## Key Findings
|
||||
- Finding 1
|
||||
- Finding 2
|
||||
|
||||
## Recommendations
|
||||
1. [Action item]
|
||||
2. [Action item]
|
||||
```
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
For complex multi-step tasks:
|
||||
|
||||
```markdown
|
||||
## Migration Workflow
|
||||
|
||||
Copy this checklist:
|
||||
|
||||
```
|
||||
- [ ] Step 1: Backup database
|
||||
- [ ] Step 2: Run migration script
|
||||
- [ ] Step 3: Validate output
|
||||
- [ ] Step 4: Update configuration
|
||||
```
|
||||
|
||||
**Step 1: Backup database**
|
||||
Run: `./scripts/backup.sh`
|
||||
...
|
||||
```
|
||||
|
||||
### Conditional Pattern
|
||||
|
||||
Guide through decision points:
|
||||
|
||||
```markdown
|
||||
## Choose Your Approach
|
||||
|
||||
**Creating new content?** Follow "Creation workflow" below.
|
||||
**Editing existing?** Follow "Editing workflow" below.
|
||||
```
|
||||
- [ ] Tested with real usage
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
- **XML tags in body** - Use markdown headings instead
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Too many options** - Provide a default with escape hatch
|
||||
- **Windows paths** - Always use forward slashes
|
||||
- **Punting to Claude** - Scripts should handle errors
|
||||
- **Time-sensitive info** - Use "old patterns" section instead
|
||||
- **Punting to Claude** - Scripts should handle errors explicitly
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed guidance, see:
|
||||
|
||||
- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
|
||||
- [official-spec.md](references/official-spec.md) - Official skill specification
|
||||
- [best-practices.md](references/best-practices.md) - Skill authoring best practices
|
||||
|
||||
## Success Criteria
|
||||
## Sources
|
||||
|
||||
A well-structured skill:
|
||||
- Has valid YAML frontmatter with descriptive name and description
|
||||
- Uses standard markdown headings (not XML tags)
|
||||
- Keeps SKILL.md under 500 lines
|
||||
- Links to reference files for detailed content
|
||||
- Includes concrete examples with input/output pairs
|
||||
- Has been tested with real usage
|
||||
|
||||
Sources:
|
||||
- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
|
||||
- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
|
||||
- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
|
||||
- [GitHub - anthropics/skills](https://github.com/anthropics/skills)
|
||||
|
||||
@@ -1,36 +1,56 @@
|
||||
# Anthropic Official Skill Specification
|
||||
# Official Skill Specification (2026)
|
||||
|
||||
Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
|
||||
|
||||
## Commands and Skills Are Merged
|
||||
|
||||
Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
|
||||
|
||||
If a skill and a command share the same name, the skill takes precedence.
|
||||
|
||||
## SKILL.md File Structure
|
||||
|
||||
Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
|
||||
|
||||
### Basic Format
|
||||
Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: Brief description of what this Skill does and when to use it
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
Provide clear, step-by-step guidance for Claude.
|
||||
Clear, step-by-step guidance.
|
||||
|
||||
## Examples
|
||||
Show concrete examples of using this Skill.
|
||||
Concrete examples of using this skill.
|
||||
```
|
||||
|
||||
## Required Frontmatter Fields
|
||||
## Complete Frontmatter Reference
|
||||
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
|
||||
| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
|
||||
| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
|
||||
| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
|
||||
| `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
|
||||
| `description` | Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
|
||||
| `disable-model-invocation` | No | Set `true` to prevent Claude from auto-loading. Use for manual workflows. Default: `false` |
|
||||
| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true` |
|
||||
| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | No | Model to use: `haiku`, `sonnet`, or `opus` |
|
||||
| `context` | No | Set `fork` to run in isolated subagent context |
|
||||
| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name |
|
||||
| `hooks` | No | Hooks scoped to this skill's lifecycle |
|
||||
|
||||
## Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
|
||||
|-------------|----------------|-------------------|--------------------------|
|
||||
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
|
||||
|
||||
## Skill Locations & Priority
|
||||
|
||||
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
|
||||
|
||||
| Type | Path | Applies to |
|
||||
|------|------|-----------|
|
||||
| **Enterprise** | See managed settings | All users in organization |
|
||||
| **Personal** | `~/.claude/skills/` | You, across all projects |
|
||||
| **Project** | `.claude/skills/` | Anyone working in repository |
|
||||
| **Plugin** | Bundled with plugins | Anyone with plugin installed |
|
||||
| Enterprise | See managed settings | All users in organization |
|
||||
| Personal | `~/.claude/skills/<name>/SKILL.md` | You, across all projects |
|
||||
| Project | `.claude/skills/<name>/SKILL.md` | Anyone working in repository |
|
||||
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |
|
||||
|
||||
Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
|
||||
|
||||
## How Skills Work
|
||||
|
||||
1. **Discovery**: Claude loads only name and description at startup
|
||||
2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
|
||||
3. **Execution**: Claude follows the Skill's instructions and loads referenced files
|
||||
1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
|
||||
2. **Activation**: When your request matches a skill's description, Claude loads the full content
|
||||
3. **Execution**: Claude follows the skill's instructions
|
||||
|
||||
**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
|
||||
## String Substitutions
|
||||
|
||||
## Progressive Disclosure Pattern
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `$ARGUMENTS` | All arguments passed when invoking |
|
||||
| `$ARGUMENTS[N]` | Specific argument by 0-based index |
|
||||
| `$N` | Shorthand for `$ARGUMENTS[N]` |
|
||||
| `${CLAUDE_SESSION_ID}` | Current session ID |
|
||||
|
||||
Keep `SKILL.md` under 500 lines by linking to supporting files:
|
||||
## Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
- Current branch: !`git branch --show-current`
|
||||
- PR diff: !`gh pr diff`
|
||||
```
|
||||
|
||||
Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (required - overview and navigation)
|
||||
├── reference.md (detailed API docs - loaded when needed)
|
||||
├── examples.md (usage examples - loaded when needed)
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py (utility script - executed, not loaded)
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### Example SKILL.md with References
|
||||
|
||||
Keep SKILL.md under 500 lines. Link to supporting files:
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
|
||||
allowed-tools: Read, Bash(python:*)
|
||||
---
|
||||
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
|
||||
Extract text:
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("doc.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
For API details, see [reference.md](reference.md).
|
||||
```
|
||||
|
||||
For form filling, see [FORMS.md](FORMS.md).
|
||||
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
## Running in a Subagent
|
||||
|
||||
## Requirements
|
||||
|
||||
Packages must be installed:
|
||||
```bash
|
||||
pip install pypdf pdfplumber
|
||||
```
|
||||
```
|
||||
|
||||
## Restricting Tool Access
|
||||
Add `context: fork` to run in isolation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: reading-files-safely
|
||||
description: Read files without making changes. Use when you need read-only file access.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Read-only Skills that shouldn't modify files
|
||||
- Limited scope for specific tasks
|
||||
- Security-sensitive workflows
|
||||
|
||||
## Writing Effective Descriptions
|
||||
|
||||
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
|
||||
|
||||
**Always write in third person.** The description is injected into the system prompt.
|
||||
|
||||
- **Good:** "Processes Excel files and generates reports"
|
||||
- **Avoid:** "I can help you process Excel files"
|
||||
- **Avoid:** "You can use this to process Excel files"
|
||||
|
||||
**Be specific and include key terms:**
|
||||
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Avoid vague descriptions:**
|
||||
|
||||
```yaml
|
||||
description: Helps with documents # Too vague!
|
||||
```
|
||||
|
||||
## Complete Example: Commit Message Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: generating-commit-messages
|
||||
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
# Generating Commit Messages
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Run `git diff --staged` to see changes
|
||||
2. I'll suggest a commit message with:
|
||||
- Summary under 50 characters
|
||||
- Detailed description
|
||||
- Affected components
|
||||
|
||||
## Best practices
|
||||
|
||||
- Use present tense
|
||||
- Explain what and why, not how
|
||||
Research $ARGUMENTS thoroughly...
|
||||
```
|
||||
|
||||
## Complete Example: Code Explanation Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: explaining-code
|
||||
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
|
||||
---
|
||||
|
||||
# Explaining Code
|
||||
|
||||
When explaining code, always include:
|
||||
|
||||
1. **Start with an analogy**: Compare the code to something from everyday life
|
||||
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
|
||||
3. **Walk through the code**: Explain step-by-step what happens
|
||||
4. **Highlight a gotcha**: What's a common misconception?
|
||||
|
||||
Keep explanations conversational. For complex concepts, use multiple analogies.
|
||||
```
|
||||
The skill content becomes the subagent's prompt. It won't have access to conversation history.
|
||||
|
||||
## Distribution
|
||||
|
||||
- **Project Skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin with Skill folders
|
||||
- **Project skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin
|
||||
- **Enterprise**: Deploy organization-wide through managed settings
|
||||
|
||||
@@ -1,372 +1,152 @@
|
||||
<overview>
|
||||
Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
|
||||
</overview>
|
||||
# Skill Structure Reference
|
||||
|
||||
<xml_structure_requirements>
|
||||
<critical_rule>
|
||||
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
|
||||
</critical_rule>
|
||||
Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
|
||||
|
||||
<required_tags>
|
||||
Every skill MUST have these three tags:
|
||||
## Body Format
|
||||
|
||||
- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
|
||||
- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
|
||||
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
|
||||
</required_tags>
|
||||
Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
|
||||
|
||||
<conditional_tags>
|
||||
Add based on skill complexity and domain requirements:
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
- **`<context>`** - Background/situational information
|
||||
- **`<workflow>` or `<process>`** - Step-by-step procedures
|
||||
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
|
||||
- **`<validation>`** - How to verify outputs
|
||||
- **`<examples>`** - Multi-shot learning
|
||||
- **`<anti_patterns>`** - Common mistakes to avoid
|
||||
- **`<security_checklist>`** - Non-negotiable security patterns
|
||||
- **`<testing>`** - Testing workflows
|
||||
- **`<common_patterns>`** - Code examples and recipes
|
||||
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
|
||||
# Skill Name
|
||||
|
||||
See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
|
||||
</conditional_tags>
|
||||
## Quick Start
|
||||
Immediate actionable guidance...
|
||||
|
||||
<tag_selection_intelligence>
|
||||
**Simple skills** (single domain, straightforward):
|
||||
- Required tags only
|
||||
- Example: Text extraction, file format conversion
|
||||
## Instructions
|
||||
Step-by-step procedures...
|
||||
|
||||
**Medium skills** (multiple patterns, some complexity):
|
||||
- Required tags + workflow/examples as needed
|
||||
- Example: Document processing with steps, API integration
|
||||
## Examples
|
||||
Concrete usage examples...
|
||||
|
||||
**Complex skills** (multiple domains, security, APIs):
|
||||
- Required tags + conditional tags as appropriate
|
||||
- Example: Payment processing, authentication systems, multi-step workflows
|
||||
</tag_selection_intelligence>
|
||||
|
||||
<xml_nesting>
|
||||
Properly nest XML tags for hierarchical content:
|
||||
|
||||
```xml
|
||||
<examples>
|
||||
<example number="1">
|
||||
<input>User input</input>
|
||||
<output>Expected output</output>
|
||||
</example>
|
||||
</examples>
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
Always close tags:
|
||||
```xml
|
||||
<objective>
|
||||
Content here
|
||||
</objective>
|
||||
```
|
||||
</xml_nesting>
|
||||
## Recommended Sections
|
||||
|
||||
<tag_naming_conventions>
|
||||
Use descriptive, semantic names:
|
||||
- `<workflow>` not `<steps>`
|
||||
- `<success_criteria>` not `<done>`
|
||||
- `<anti_patterns>` not `<dont_do>`
|
||||
Every skill should have:
|
||||
|
||||
Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
|
||||
</tag_naming_conventions>
|
||||
</xml_structure_requirements>
|
||||
- **Quick Start** - Immediate, actionable guidance (minimal working example)
|
||||
- **Instructions** - Core step-by-step guidance
|
||||
- **Success Criteria** - How to know it worked
|
||||
|
||||
Add based on complexity:
|
||||
|
||||
- **Context** - Background/situational information
|
||||
- **Workflow** - Multi-step procedures
|
||||
- **Examples** - Concrete input/output pairs
|
||||
- **Advanced Features** - Deep-dive topics (link to reference files)
|
||||
- **Anti-Patterns** - Common mistakes to avoid
|
||||
- **Guidelines** - Rules and constraints
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
### Required/Recommended Fields
|
||||
|
||||
<yaml_requirements>
|
||||
<required_fields>
|
||||
```yaml
|
||||
---
|
||||
name: skill-name-here
|
||||
description: What it does and when to use it (third person, specific triggers)
|
||||
description: What it does and when to use it (specific triggers included)
|
||||
---
|
||||
```
|
||||
</required_fields>
|
||||
|
||||
<name_field>
|
||||
**Validation rules**:
|
||||
### Name Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 64 characters
|
||||
- Lowercase letters, numbers, hyphens only
|
||||
- No XML tags
|
||||
- Must match directory name
|
||||
- No reserved words: "anthropic", "claude"
|
||||
- Must match directory name exactly
|
||||
|
||||
**Examples**:
|
||||
- ✅ `process-pdfs`
|
||||
- ✅ `manage-facebook-ads`
|
||||
- ✅ `setup-stripe-payments`
|
||||
- ❌ `PDF_Processor` (uppercase)
|
||||
- ❌ `helper` (vague)
|
||||
- ❌ `claude-helper` (reserved word)
|
||||
</name_field>
|
||||
**Examples:**
|
||||
- `triage-prs`
|
||||
- `deploy-production`
|
||||
- `review-code`
|
||||
- `setup-stripe-payments`
|
||||
|
||||
<description_field>
|
||||
**Validation rules**:
|
||||
- Non-empty, maximum 1024 characters
|
||||
- No XML tags
|
||||
- Third person (never first or second person)
|
||||
**Avoid:** `helper`, `utils`, `tools`, generic names
|
||||
|
||||
### Description Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 1024 characters
|
||||
- Include what it does AND when to use it
|
||||
- Third person voice
|
||||
|
||||
**Critical rule**: Always write in third person.
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ❌ "You can use this to process Excel files"
|
||||
|
||||
**Structure**: Include both capabilities and triggers.
|
||||
|
||||
**Effective examples**:
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
|
||||
```
|
||||
|
||||
**Avoid**:
|
||||
**Bad:**
|
||||
```yaml
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Processes data
|
||||
### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `argument-hint` | Usage hints. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
|
||||
| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
|
||||
| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | `haiku`, `sonnet`, or `opus` |
|
||||
| `context` | `fork` for isolated subagent execution |
|
||||
| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Use descriptive names that indicate purpose:
|
||||
|
||||
| Pattern | Examples |
|
||||
|---------|----------|
|
||||
| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
|
||||
| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
|
||||
| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required, overview + navigation)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
</description_field>
|
||||
</yaml_requirements>
|
||||
|
||||
<naming_conventions>
|
||||
Use **verb-noun convention** for skill names:
|
||||
|
||||
<pattern name="create">
|
||||
Building/authoring tools
|
||||
|
||||
Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
|
||||
</pattern>
|
||||
|
||||
<pattern name="manage">
|
||||
Managing external services or resources
|
||||
|
||||
Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
|
||||
</pattern>
|
||||
|
||||
<pattern name="setup">
|
||||
Configuration/integration tasks
|
||||
|
||||
Examples: `setup-stripe-payments`, `setup-meta-tracking`
|
||||
</pattern>
|
||||
|
||||
<pattern name="generate">
|
||||
Generation tasks
|
||||
|
||||
Examples: `generate-ai-images`
|
||||
</pattern>
|
||||
|
||||
<avoid_patterns>
|
||||
- Vague: `helper`, `utils`, `tools`
|
||||
- Generic: `documents`, `data`, `files`
|
||||
- Reserved words: `anthropic-helper`, `claude-tools`
|
||||
- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
|
||||
</avoid_patterns>
|
||||
</naming_conventions>
|
||||
|
||||
<progressive_disclosure>
|
||||
<principle>
|
||||
SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
|
||||
</principle>
|
||||
|
||||
<practical_guidance>
|
||||
- Keep SKILL.md body under 500 lines
|
||||
- Split content into separate files when approaching this limit
|
||||
**Rules:**
|
||||
- Keep references one level deep from SKILL.md
|
||||
- Add table of contents to reference files over 100 lines
|
||||
</practical_guidance>
|
||||
- Use forward slashes in paths: `scripts/helper.py`
|
||||
- Name files descriptively: `form_validation_rules.md` not `doc2.md`
|
||||
|
||||
<pattern name="high_level_guide">
|
||||
Quick start in SKILL.md, details in reference files:
|
||||
## Validation Checklist
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
---
|
||||
Before finalizing:
|
||||
|
||||
<objective>
|
||||
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
|
||||
</objective>
|
||||
- [ ] YAML frontmatter valid (name matches directory, description specific)
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] Has Quick Start, Instructions, and Success Criteria sections
|
||||
- [ ] `disable-model-invocation: true` if skill has side effects
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] Reference files linked properly from SKILL.md
|
||||
- [ ] File paths use forward slashes
|
||||
- [ ] Tested with real usage
|
||||
|
||||
<quick_start>
|
||||
Extract text with pdfplumber:
|
||||
## Anti-Patterns
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
```
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
**Form filling**: See [forms.md](forms.md)
|
||||
**API reference**: See [reference.md](reference.md)
|
||||
</advanced_features>
|
||||
```
|
||||
|
||||
Claude loads forms.md or reference.md only when needed.
|
||||
</pattern>
|
||||
|
||||
<pattern name="domain_organization">
|
||||
For skills with multiple domains, organize by domain to avoid loading irrelevant context:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (overview and navigation)
|
||||
└── reference/
|
||||
├── finance.md (revenue, billing metrics)
|
||||
├── sales.md (opportunities, pipeline)
|
||||
├── product.md (API usage, features)
|
||||
└── marketing.md (campaigns, attribution)
|
||||
```
|
||||
|
||||
When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
|
||||
</pattern>
|
||||
|
||||
<pattern name="conditional_details">
|
||||
Show basic content in SKILL.md, link to advanced in reference files:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
Process DOCX files with creation and editing capabilities.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
<creating_documents>
|
||||
Use docx-js for new documents. See [docx-js.md](docx-js.md).
|
||||
</creating_documents>
|
||||
|
||||
<editing_documents>
|
||||
For simple edits, modify XML directly.
|
||||
|
||||
**For tracked changes**: See [redlining.md](redlining.md)
|
||||
**For OOXML details**: See [ooxml.md](ooxml.md)
|
||||
</editing_documents>
|
||||
</quick_start>
|
||||
```
|
||||
|
||||
Claude reads redlining.md or ooxml.md only when the user needs those features.
|
||||
</pattern>
|
||||
|
||||
<critical_rules>
|
||||
**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
|
||||
|
||||
**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
|
||||
|
||||
**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
|
||||
</critical_rules>
|
||||
</progressive_disclosure>
|
||||
|
||||
<file_organization>
|
||||
<filesystem_navigation>
|
||||
Claude navigates your skill directory using bash commands:
|
||||
|
||||
- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
|
||||
- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
|
||||
- Organize by domain: `reference/finance.md`, `reference/sales.md`
|
||||
</filesystem_navigation>
|
||||
|
||||
<directory_structure>
|
||||
Typical skill structure:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (main entry point, pure XML structure)
|
||||
├── references/ (optional, for progressive disclosure)
|
||||
│ ├── guide-1.md (pure XML structure)
|
||||
│ ├── guide-2.md (pure XML structure)
|
||||
│ └── examples.md (pure XML structure)
|
||||
└── scripts/ (optional, for utility scripts)
|
||||
├── validate.py
|
||||
└── process.py
|
||||
```
|
||||
</directory_structure>
|
||||
</file_organization>
|
||||
|
||||
<anti_patterns>
|
||||
<pitfall name="markdown_headings_in_body">
|
||||
❌ Do NOT use markdown headings in skill body:
|
||||
|
||||
```markdown
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
Extract text...
|
||||
|
||||
## Advanced features
|
||||
Form filling...
|
||||
```
|
||||
|
||||
✅ Use pure XML structure:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
PDF processing with text extraction, form filling, and merging.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
Extract text...
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
Form filling...
|
||||
</advanced_features>
|
||||
```
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="vague_descriptions">
|
||||
- ❌ "Helps with documents"
|
||||
- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="inconsistent_pov">
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="wrong_naming_convention">
|
||||
- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
|
||||
- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
|
||||
- ❌ Directory: `stripe-integration`, Name: `stripe`
|
||||
- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="deeply_nested_references">
|
||||
Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="windows_paths">
|
||||
Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="missing_required_tags">
|
||||
Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
|
||||
</pitfall>
|
||||
</anti_patterns>
|
||||
|
||||
<validation_checklist>
|
||||
Before finalizing a skill, verify:
|
||||
|
||||
- ✅ YAML frontmatter valid (name matches directory, description in third person)
|
||||
- ✅ No markdown headings in body (pure XML structure)
|
||||
- ✅ Required tags present: objective, quick_start, success_criteria
|
||||
- ✅ Conditional tags appropriate for complexity level
|
||||
- ✅ All XML tags properly closed
|
||||
- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
|
||||
- ✅ Reference files use pure XML structure
|
||||
- ✅ File paths use forward slashes
|
||||
- ✅ Descriptive file names
|
||||
</validation_checklist>
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Inconsistent naming** - Directory name must match `name` field
|
||||
- **Windows paths** - Always use forward slashes
|
||||
|
||||
87
plugins/compound-engineering/skills/document-review/SKILL.md
Normal file
87
plugins/compound-engineering/skills/document-review/SKILL.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: document-review
|
||||
description: This skill should be used to refine brainstorm or plan documents before proceeding to the next workflow step. It applies when a brainstorm or plan document exists and the user wants to improve it.
|
||||
---
|
||||
|
||||
# Document Review
|
||||
|
||||
Improve brainstorm or plan documents through structured review.
|
||||
|
||||
## Step 1: Get the Document
|
||||
|
||||
**If a document path is provided:** Read it, then proceed to Step 2.
|
||||
|
||||
**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.
|
||||
|
||||
## Step 2: Assess
|
||||
|
||||
Read through the document and ask:
|
||||
|
||||
- What is unclear?
|
||||
- What is unnecessary?
|
||||
- What decision is being avoided?
|
||||
- What assumptions are unstated?
|
||||
- Where could scope accidentally expand?
|
||||
|
||||
These questions surface issues. Don't fix yet—just note what you find.
|
||||
|
||||
## Step 3: Evaluate
|
||||
|
||||
Score the document against these criteria:
|
||||
|
||||
| Criterion | What to Check |
|
||||
|-----------|---------------|
|
||||
| **Clarity** | Problem statement is clear, no vague language ("probably," "consider," "try to") |
|
||||
| **Completeness** | Required sections present, constraints stated, open questions flagged |
|
||||
| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |
|
||||
| **YAGNI** | No hypothetical features, simplest approach chosen |
|
||||
|
||||
If invoked within a workflow (after `/workflows:brainstorm` or `/workflows:plan`), also check:
|
||||
- **User intent fidelity** — Document reflects what was discussed, assumptions validated
|
||||
|
||||
## Step 4: Identify the Critical Improvement
|
||||
|
||||
Among everything found in Steps 2-3, does one issue stand out? If something would significantly improve the document's quality, this is the "must address" item. Highlight it prominently.
|
||||
|
||||
## Step 5: Make Changes
|
||||
|
||||
Present your findings, then:
|
||||
|
||||
1. **Auto-fix** minor issues (vague language, formatting) without asking
|
||||
2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning)
|
||||
3. **Update** the document inline—no separate files, no metadata sections
|
||||
|
||||
### Simplification Guidance
|
||||
|
||||
Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
|
||||
|
||||
**Simplify when:**
|
||||
- Content serves hypothetical future needs, not current ones
|
||||
- Sections repeat information already covered elsewhere
|
||||
- Detail exceeds what's needed to take the next step
|
||||
- Abstractions or structure add overhead without clarity
|
||||
|
||||
**Don't simplify:**
|
||||
- Constraints or edge cases that affect implementation
|
||||
- Rationale that explains why alternatives were rejected
|
||||
- Open questions that need resolution
|
||||
|
||||
## Step 6: Offer Next Action
|
||||
|
||||
After changes are complete, ask:
|
||||
|
||||
1. **Refine again** - Another review pass
|
||||
2. **Review complete** - Document is ready
|
||||
|
||||
### Iteration Guidance
|
||||
|
||||
After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it.
|
||||
|
||||
Return control to the caller (workflow or user) after selection.
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
- Do not rewrite the entire document
|
||||
- Do not add new sections or requirements the user didn't discuss
|
||||
- Do not over-engineer or add complexity
|
||||
- Do not create separate review files or add metadata sections
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
name: file-todos
|
||||
description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# File-Based Todo Tracking Skill
|
||||
|
||||
@@ -91,14 +91,6 @@ create_worktree() {
|
||||
echo -e "${BLUE}Creating worktree: $branch_name${NC}"
|
||||
echo " From: $from_branch"
|
||||
echo " Path: $worktree_path"
|
||||
echo ""
|
||||
echo "Proceed? (y/n)"
|
||||
read -r response
|
||||
|
||||
if [[ "$response" != "y" ]]; then
|
||||
echo -e "${YELLOW}Cancelled${NC}"
|
||||
return
|
||||
fi
|
||||
|
||||
# Update main branch
|
||||
echo -e "${BLUE}Updating $from_branch...${NC}"
|
||||
@@ -134,7 +126,7 @@ list_worktrees() {
|
||||
|
||||
local count=0
|
||||
for worktree_path in "$WORKTREE_DIR"/*; do
|
||||
if [[ -d "$worktree_path" && -d "$worktree_path/.git" ]]; then
|
||||
if [[ -d "$worktree_path" && -e "$worktree_path/.git" ]]; then
|
||||
count=$((count + 1))
|
||||
local worktree_name=$(basename "$worktree_path")
|
||||
local branch=$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
|
||||
@@ -231,7 +223,7 @@ cleanup_worktrees() {
|
||||
local to_remove=()
|
||||
|
||||
for worktree_path in "$WORKTREE_DIR"/*; do
|
||||
if [[ -d "$worktree_path" && -d "$worktree_path/.git" ]]; then
|
||||
if [[ -d "$worktree_path" && -e "$worktree_path/.git" ]]; then
|
||||
local worktree_name=$(basename "$worktree_path")
|
||||
|
||||
# Skip if current worktree
|
||||
|
||||
1718
plugins/compound-engineering/skills/orchestrating-swarms/SKILL.md
Normal file
1718
plugins/compound-engineering/skills/orchestrating-swarms/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: resolve_pr_parallel
|
||||
description: Resolve all PR comments using parallel processing. Use when addressing PR review feedback, resolving review threads, or batch-fixing PR comments.
|
||||
argument-hint: "[optional: PR number or current PR]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Bash(git *), Read
|
||||
---
|
||||
|
||||
# Resolve PR Comments in Parallel
|
||||
|
||||
Resolve all unresolved PR review comments by spawning parallel agents for each thread.
|
||||
|
||||
## Context Detection
|
||||
|
||||
Claude Code automatically detects git context:
|
||||
- Current branch and associated PR
|
||||
- All PR comments and review threads
|
||||
- Works with any PR by specifying the number
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Fetch unresolved review threads using the GraphQL script:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
This returns only **unresolved, non-outdated** threads with file paths, line numbers, and comment bodies.
|
||||
|
||||
If the script fails, fall back to:
|
||||
```bash
|
||||
gh pr view PR_NUMBER --json reviews,comments
|
||||
gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments
|
||||
```
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a TodoWrite list of all unresolved items grouped by type:
|
||||
- Code changes requested
|
||||
- Questions to answer
|
||||
- Style/convention fixes
|
||||
- Test additions needed
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a `pr-comment-resolver` agent for each unresolved item in parallel.
|
||||
|
||||
If there are 3 comments, spawn 3 agents:
|
||||
|
||||
1. Task pr-comment-resolver(comment1)
|
||||
2. Task pr-comment-resolver(comment2)
|
||||
3. Task pr-comment-resolver(comment3)
|
||||
|
||||
Always run all in parallel subagents/Tasks for each Todo item.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes with a clear message referencing the PR feedback
|
||||
- Resolve each thread programmatically:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/resolve-pr-thread THREAD_ID
|
||||
```
|
||||
|
||||
- Push to remote
|
||||
|
||||
### 5. Verify
|
||||
|
||||
Re-fetch comments to confirm all threads are resolved:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
|
||||
```
|
||||
|
||||
Should return an empty array `[]`. If threads remain, repeat from step 1.
|
||||
|
||||
## Scripts
|
||||
|
||||
- [scripts/get-pr-comments](scripts/get-pr-comments) - GraphQL query for unresolved review threads
|
||||
- [scripts/resolve-pr-thread](scripts/resolve-pr-thread) - GraphQL mutation to resolve a thread by ID
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- All unresolved review threads addressed
|
||||
- Changes committed and pushed
|
||||
- Threads resolved via GraphQL (marked as resolved on GitHub)
|
||||
- Empty result from get-pr-comments on verify
|
||||
@@ -0,0 +1,68 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
if [ $# -lt 1 ]; then
|
||||
echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
|
||||
echo "Example: get-pr-comments 123"
|
||||
echo "Example: get-pr-comments 123 EveryInc/cora"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
PR_NUMBER=$1
|
||||
|
||||
if [ -n "$2" ]; then
|
||||
OWNER=$(echo "$2" | cut -d/ -f1)
|
||||
REPO=$(echo "$2" | cut -d/ -f2)
|
||||
else
|
||||
OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
|
||||
REPO=$(gh repo view --json name -q .name 2>/dev/null)
|
||||
fi
|
||||
|
||||
if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
|
||||
echo "Error: Could not detect repository. Pass OWNER/REPO as second argument."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
|
||||
query FetchUnresolvedComments($owner: String!, $repo: String!, $pr: Int!) {
|
||||
repository(owner: $owner, name: $repo) {
|
||||
pullRequest(number: $pr) {
|
||||
title
|
||||
url
|
||||
reviewThreads(first: 100) {
|
||||
totalCount
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
isResolved
|
||||
isOutdated
|
||||
isCollapsed
|
||||
path
|
||||
line
|
||||
startLine
|
||||
diffSide
|
||||
comments(first: 100) {
|
||||
totalCount
|
||||
nodes {
|
||||
id
|
||||
author {
|
||||
login
|
||||
}
|
||||
body
|
||||
createdAt
|
||||
updatedAt
|
||||
url
|
||||
outdated
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}' | jq '.data.repository.pullRequest.reviewThreads.edges | map(select(.node.isResolved == false and .node.isOutdated == false))'
|
||||
@@ -0,0 +1,23 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: resolve-pr-thread THREAD_ID"
|
||||
echo "Example: resolve-pr-thread PRRT_kwDOABC123"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
THREAD_ID=$1
|
||||
|
||||
gh api graphql -f threadId="$THREAD_ID" -f query='
|
||||
mutation ResolveReviewThread($threadId: ID!) {
|
||||
resolveReviewThread(input: {threadId: $threadId}) {
|
||||
thread {
|
||||
id
|
||||
isResolved
|
||||
path
|
||||
line
|
||||
}
|
||||
}
|
||||
}'
|
||||
168
plugins/compound-engineering/skills/setup/SKILL.md
Normal file
168
plugins/compound-engineering/skills/setup/SKILL.md
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
name: setup
|
||||
description: Configure which review agents run for your project. Auto-detects stack and writes compound-engineering.local.md.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Compound Engineering Setup
|
||||
|
||||
Interactive setup for `compound-engineering.local.md` — configures which agents run during `/workflows:review` and `/workflows:work`.
|
||||
|
||||
## Step 1: Check Existing Config
|
||||
|
||||
Read `compound-engineering.local.md` in the project root. If it exists, display current settings summary and use AskUserQuestion:
|
||||
|
||||
```
|
||||
question: "Settings file already exists. What would you like to do?"
|
||||
header: "Config"
|
||||
options:
|
||||
- label: "Reconfigure"
|
||||
description: "Run the interactive setup again from scratch"
|
||||
- label: "View current"
|
||||
description: "Show the file contents, then stop"
|
||||
- label: "Cancel"
|
||||
description: "Keep current settings"
|
||||
```
|
||||
|
||||
If "View current": read and display the file, then stop.
|
||||
If "Cancel": stop.
|
||||
|
||||
## Step 2: Detect and Ask
|
||||
|
||||
Auto-detect the project stack:
|
||||
|
||||
```bash
|
||||
test -f Gemfile && test -f config/routes.rb && echo "rails" || \
|
||||
test -f Gemfile && echo "ruby" || \
|
||||
test -f tsconfig.json && echo "typescript" || \
|
||||
test -f package.json && echo "javascript" || \
|
||||
test -f pyproject.toml && echo "python" || \
|
||||
test -f requirements.txt && echo "python" || \
|
||||
echo "general"
|
||||
```
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
```
|
||||
question: "Detected {type} project. How would you like to configure?"
|
||||
header: "Setup"
|
||||
options:
|
||||
- label: "Auto-configure (Recommended)"
|
||||
description: "Use smart defaults for {type}. Done in one click."
|
||||
- label: "Customize"
|
||||
description: "Choose stack, focus areas, and review depth."
|
||||
```
|
||||
|
||||
### If Auto-configure → Skip to Step 4 with defaults:
|
||||
|
||||
- **Rails:** `[kieran-rails-reviewer, dhh-rails-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle]`
|
||||
- **Python:** `[kieran-python-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle]`
|
||||
- **TypeScript:** `[kieran-typescript-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle]`
|
||||
- **General:** `[code-simplicity-reviewer, security-sentinel, performance-oracle, architecture-strategist]`
|
||||
|
||||
### If Customize → Step 3
|
||||
|
||||
## Step 3: Customize (3 questions)
|
||||
|
||||
**a. Stack** — confirm or override:
|
||||
|
||||
```
|
||||
question: "Which stack should we optimize for?"
|
||||
header: "Stack"
|
||||
options:
|
||||
- label: "{detected_type} (Recommended)"
|
||||
description: "Auto-detected from project files"
|
||||
- label: "Rails"
|
||||
description: "Ruby on Rails — adds DHH-style and Rails-specific reviewers"
|
||||
- label: "Python"
|
||||
description: "Python — adds Pythonic pattern reviewer"
|
||||
- label: "TypeScript"
|
||||
description: "TypeScript — adds type safety reviewer"
|
||||
```
|
||||
|
||||
Only show options that differ from the detected type.
|
||||
|
||||
**b. Focus areas** — multiSelect:
|
||||
|
||||
```
|
||||
question: "Which review areas matter most?"
|
||||
header: "Focus"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "Security"
|
||||
description: "Vulnerability scanning, auth, input validation (security-sentinel)"
|
||||
- label: "Performance"
|
||||
description: "N+1 queries, memory leaks, complexity (performance-oracle)"
|
||||
- label: "Architecture"
|
||||
description: "Design patterns, SOLID, separation of concerns (architecture-strategist)"
|
||||
- label: "Code simplicity"
|
||||
description: "Over-engineering, YAGNI violations (code-simplicity-reviewer)"
|
||||
```
|
||||
|
||||
**c. Depth:**
|
||||
|
||||
```
|
||||
question: "How thorough should reviews be?"
|
||||
header: "Depth"
|
||||
options:
|
||||
- label: "Thorough (Recommended)"
|
||||
description: "Stack reviewers + all selected focus agents."
|
||||
- label: "Fast"
|
||||
description: "Stack reviewers + code simplicity only. Less context, quicker."
|
||||
- label: "Comprehensive"
|
||||
description: "All above + git history, data integrity, agent-native checks."
|
||||
```
|
||||
|
||||
## Step 4: Build Agent List and Write File
|
||||
|
||||
**Stack-specific agents:**
|
||||
- Rails → `kieran-rails-reviewer, dhh-rails-reviewer`
|
||||
- Python → `kieran-python-reviewer`
|
||||
- TypeScript → `kieran-typescript-reviewer`
|
||||
- General → (none)
|
||||
|
||||
**Focus area agents:**
|
||||
- Security → `security-sentinel`
|
||||
- Performance → `performance-oracle`
|
||||
- Architecture → `architecture-strategist`
|
||||
- Code simplicity → `code-simplicity-reviewer`
|
||||
|
||||
**Depth:**
|
||||
- Thorough: stack + selected focus areas
|
||||
- Fast: stack + `code-simplicity-reviewer` only
|
||||
- Comprehensive: all above + `git-history-analyzer, data-integrity-guardian, agent-native-reviewer`
|
||||
|
||||
**Plan review agents:** stack-specific reviewer + `code-simplicity-reviewer`.
|
||||
|
||||
Write `compound-engineering.local.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
review_agents: [{computed agent list}]
|
||||
plan_review_agents: [{computed plan agent list}]
|
||||
---
|
||||
|
||||
# Review Context
|
||||
|
||||
Add project-specific review instructions here.
|
||||
These notes are passed to all review agents during /workflows:review and /workflows:work.
|
||||
|
||||
Examples:
|
||||
- "We use Turbo Frames heavily — check for frame-busting issues"
|
||||
- "Our API is public — extra scrutiny on input validation"
|
||||
- "Performance-critical: we serve 10k req/s on this endpoint"
|
||||
```
|
||||
|
||||
## Step 5: Confirm
|
||||
|
||||
```
|
||||
Saved to compound-engineering.local.md
|
||||
|
||||
Stack: {type}
|
||||
Review depth: {depth}
|
||||
Agents: {count} configured
|
||||
{agent list, one per line}
|
||||
|
||||
Tip: Edit the "Review Context" section to add project-specific instructions.
|
||||
Re-run this setup anytime to reconfigure.
|
||||
```
|
||||
@@ -2,6 +2,7 @@
|
||||
name: skill-creator
|
||||
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
|
||||
license: Complete terms in LICENSE.txt
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
Reference in New Issue
Block a user