An agent-friendly development workflow for Claude Code. Decomposes large changes into small, focused tasks that fit comfortably within a context window, then orchestrates those tasks to complete bigger chunks of work. Three commands, specialized review agents, and structured issue tracking.
Three commands:
/plan <description>— Collaboratively design, review, and refine an approach, then decompose it into issues with dependencies/work <id>— Implement, review, and open a PR — all from one command/merge— Process open PRs: merge when CI passes, rebase when behind, file issues for failures
Automated pre-PR review: Three specialized reviewers (correctness, tests, architecture) run in parallel before every PR is created.
Structured issue tracking: Uses beads (bd) for dependency-aware issue tracking that auto-syncs to git.
- Copy
.claude/andAGENTS.mdinto your project - Replace
CLAUDE.mdwith your project-specific version (see the template in this repo) - Install beads (see installation instructions)
- Start working:
/plan "Add user authentication"then/work <epic-id>
you> /plan "Add rate limiting to the API"
The planner explores your codebase, discusses tradeoffs with you, then creates an epic with subtasks — each scoped to a single implementation session, with dependencies between them.
you> /work bd-42
The coordinator creates a feature branch and worktree, implements tasks via test-first development (spawning implementer subagents), runs three parallel code reviews, then opens a PR.
you> /merge
Run in a dedicated window. Scans open PRs, merges what's ready (choosing squash vs merge based on commit quality), rebases what's behind, and files issues for CI failures.
| Skill | Role |
|---|---|
| coordinator | Entry point for /work. Triages, sets up worktrees, delegates to implementers, runs reviews, creates PRs. |
| implementer | Test-first development. Writes failing tests, implements, verifies, audits coverage. Never manages issues. |
| planner | Entry point for /plan. Explores codebase, discusses with user, files structured issues. |
| merge-queue | Entry point for /merge. Merges, rebases, handles CI failures. |
| reviewer-correctness | Reviews for bugs, security issues, error handling gaps. |
| reviewer-tests | Reviews test quality — meaningful coverage, not just line count. |
| reviewer-architecture | Reviews for duplication, pattern divergence, structural issues. |
| reviewer-plan | Validates filed issues against codebase before implementation. |
| playwright-debugging | Guide for writing and debugging Playwright E2E tests. |
| Command | Action |
|---|---|
/work <id> |
Invoke coordinator |
/plan <desc> |
Invoke planner |
/merge |
Invoke merge queue |
/epic <id> |
Redirects to /work |
/gh-issue <num> |
Work on a GitHub issue end-to-end |
Uses beads for all task tracking:
- Dependency-aware (tracks blockers between issues)
- Git-friendly (auto-syncs to
.beads/issues.jsonl) - Agent-optimized (JSON output, ready work detection)
See AGENTS.md for the full beads workflow documentation.
- Enables the beads MCP plugin
- Auto-permissions for
bdandgitcommands - SessionStart hook loads
AGENTS.mdinto every conversation
The skills reference a Quality Gates table in your project's CLAUDE.md. Define what commands to run for each area of your codebase. See the CLAUDE.md template in this repo.
Create new skills in .claude/skills/<name>/SKILL.md with a YAML frontmatter header. Reference them from commands in .claude/commands/.
- Claude Code CLI
- beads (see installation instructions)
ghCLI (authenticated)- Git
MIT