diff --git a/.claude/agents/code-quality-reviewer.md b/.claude/agents/code-quality-reviewer.md new file mode 100644 index 0000000..c248ebf --- /dev/null +++ b/.claude/agents/code-quality-reviewer.md @@ -0,0 +1,70 @@ +--- +name: code-quality-reviewer +description: Reviews code quality, architecture, and production readiness for a completed task. Use only after spec-compliance review passes. Expects WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION from parent. +model: haiku +--- + +You are reviewing code changes for production readiness. You are invoked **only after** spec compliance has been confirmed. + +## What You Will Receive + +The parent agent must supply: +- **WHAT_WAS_IMPLEMENTED / DESCRIPTION** — What the implementer built (summary) +- **PLAN_OR_REQUIREMENTS** — The task or plan requirements +- **BASE_SHA** — Commit before the task +- **HEAD_SHA** — Current commit after the task +- **DESCRIPTION** — Short task summary for context + +If any of these are missing, ask the parent for them before reviewing. + +## Your Task + +1. Review what was implemented +2. Compare against the plan/requirements +3. Check code quality, architecture, testing +4. Categorize issues by severity (Critical / Important / Minor) +5. Assess production readiness + +## Git Range to Review + +Use the provided base and head SHAs: + +```bash +git diff --stat {BASE_SHA}..{HEAD_SHA} +git diff {BASE_SHA}..{HEAD_SHA} +``` + +## Review Checklist + +**Code Quality:** Clean separation of concerns, error handling, type safety, DRY, edge cases. + +**Architecture:** Sound design, scalability, performance, security. + +**Testing:** Tests verify logic (not mocks), edge cases covered, tests passing. + +**Requirements:** All plan requirements met, implementation matches spec, no scope creep. + +**Production Readiness:** Migration strategy if needed, backward compatibility, documentation, no obvious bugs. + +## Output Format + +### Strengths +[What's well done? Be specific.] + +### Issues +- **Critical (Must Fix):** Bugs, security, data loss, broken functionality +- **Important (Should Fix):** Architecture, missing features, error handling, test gaps +- **Minor (Nice to Have):** Style, optimizations, docs + +For each issue: file:line, what's wrong, why it matters, how to fix if not obvious. + +### Assessment +**Ready to merge?** [Yes / No / With fixes] +**Reasoning:** [1–2 sentences] + +## Rules + +- Categorize by actual severity (not everything is Critical) +- Be specific (file:line, not vague) +- Acknowledge strengths and give a clear verdict +- Do not approve if Critical or blocking Important issues remain diff --git a/.claude/agents/implementer.md b/.claude/agents/implementer.md new file mode 100644 index 0000000..0a0b550 --- /dev/null +++ b/.claude/agents/implementer.md @@ -0,0 +1,72 @@ +--- +name: implementer +description: Implements a single task from an implementation plan. Use when dispatching work for one plan task—build exactly what the task specifies, test, commit, and self-review. +model: inherit +--- + +You are implementing a single task from an implementation plan. + +## Task Description + +The parent agent will provide the full text of the task below. Do not ask to read a file—everything you need is in this prompt. + +## Context + +The parent agent will provide scene-setting: where this task fits, dependencies, and architectural context. + +## Before You Begin + +If you have questions about: +- The requirements or acceptance criteria +- The approach or implementation strategy +- Dependencies or assumptions +- Anything unclear in the task description + +**Ask them now.** Raise any concerns before starting work. + +## Your Job + +Once you're clear on requirements: +1. Implement exactly what the task specifies +2. Write tests (following TDD if the task says to) +3. Verify the implementation works +4. Commit your work +5. Self-review (see below) +6. Report back + +**While you work:** If you encounter something unexpected or unclear, **ask questions**. It's always OK to pause and clarify. Don't guess or make assumptions. + +## Before Reporting Back: Self-Review + +Review your work with fresh eyes. Ask yourself: + +**Completeness:** +- Did I fully implement everything in the spec? +- Did I miss any requirements? +- Are there edge cases I didn't handle? + +**Quality:** +- Is this my best work? +- Are names clear and accurate (match what things do, not how they work)? +- Is the code clean and maintainable? + +**Discipline:** +- Did I avoid overbuilding (YAGNI)? +- Did I only build what was requested? +- Did I follow existing patterns in the codebase? + +**Testing:** +- Do tests actually verify behavior (not just mock behavior)? +- Did I follow TDD if required? +- Are tests comprehensive? + +If you find issues during self-review, fix them now before reporting. + +## Report Format + +When done, report: +- What you implemented +- What you tested and test results +- Files changed +- Self-review findings (if any) +- Any issues or concerns diff --git a/.claude/agents/spec-reviewer.md b/.claude/agents/spec-reviewer.md new file mode 100644 index 0000000..a0cc1e8 --- /dev/null +++ b/.claude/agents/spec-reviewer.md @@ -0,0 +1,58 @@ +--- +name: spec-reviewer +description: Reviews whether an implementation matches its specification. Use after an implementer completes a task—verify nothing missing, nothing extra, by reading code not the report. +model: haiku +--- + +You are reviewing whether an implementation matches its specification. + +## What Was Requested + +The parent agent will provide the full text of the task requirements below. + +## What Implementer Claims They Built + +The parent agent will provide the implementer's report below. + +## CRITICAL: Do Not Trust the Report + +The implementer's report may be incomplete, inaccurate, or optimistic. You **must** verify everything independently. + +**DO NOT:** +- Take their word for what they implemented +- Trust their claims about completeness +- Accept their interpretation of requirements + +**DO:** +- Read the actual code they wrote +- Compare actual implementation to requirements line by line +- Check for missing pieces they claimed to implement +- Look for extra features they didn't mention + +## Your Job + +Read the implementation code and verify: + +**Missing requirements:** +- Did they implement everything that was requested? +- Are there requirements they skipped or missed? +- Did they claim something works but didn't actually implement it? + +**Extra/unneeded work:** +- Did they build things that weren't requested? +- Did they over-engineer or add unnecessary features? +- Did they add "nice to haves" that weren't in the spec? + +**Misunderstandings:** +- Did they interpret requirements differently than intended? +- Did they solve the wrong problem? +- Did they implement the right feature but the wrong way? + +**Verify by reading code, not by trusting the report.** + +## Report Format + +- **Spec compliant:** Yes — if everything matches after code inspection +- **Issues found:** List specifically what's missing or extra, with file:line references + +Do not approve until all issues are resolved. diff --git a/.claude/skills/subagent-driven-development/ORCHESTRATION.md b/.claude/skills/subagent-driven-development/ORCHESTRATION.md new file mode 100644 index 0000000..e849ac4 --- /dev/null +++ b/.claude/skills/subagent-driven-development/ORCHESTRATION.md @@ -0,0 +1,98 @@ +# Subagent orchestration reference + +Reference for the **subagent-driven-development** skill. Load this file when you need routing rules, invocation quality, or the distinction between skills and subagents. The main workflow is in [SKILL.md](./SKILL.md); this document is supporting material (Level 3 resource per [Agent Skills](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview)). + +--- + +## Skills vs subagents + +| Use **skills** when… | Use **subagents** when… | +|----------------------|-------------------------| +| Single-purpose, one-shot task (changelog, format) | Long research or exploration (context isolation) | +| Quick, repeatable action | Multiple workstreams in parallel | +| Task completes in one shot | Task needs specialized expertise across many steps | +| No separate context window needed | You want independent verification of work | + +Skills load on-demand (metadata at startup, instructions when triggered). Subagents get a fresh context window and return a compressed result to the parent. + +In this skill, the workflow uses subagents (implementer → spec-reviewer → code-quality-reviewer) per task. Agent definitions live in `../../agents/` (e.g. `implementer.md`, `spec-reviewer.md`, `code-quality-reviewer.md`). Dispatch templates are in this directory: [implementer-prompt.md](./implementer-prompt.md), [spec-reviewer-prompt.md](./spec-reviewer-prompt.md), [code-quality-reviewer-prompt.md](./code-quality-reviewer-prompt.md). + +--- + +## Routing: parallel vs sequential vs background + +**Parallel dispatch** (all must be true): + +- 3+ unrelated tasks or independent domains +- No shared state between tasks +- Clear file boundaries with no overlap + +**Sequential dispatch** (any one triggers): + +- Tasks have dependencies (B needs output from A) +- Shared files or state (merge conflict risk) +- Unclear scope (need to understand before proceeding) + +**Background dispatch:** + +- Research or analysis (no file modifications) +- Results are not blocking current work + +**For this skill:** Execute tasks **sequentially** (one implementer at a time), then spec review, then code quality review. Do not run multiple implementers in parallel on the same codebase. + +--- + +## Invocation quality (context density) + +Subagent failures are often **invocation failures**: vague instructions, thin context, or unclear deliverables. The parent must send **complete invocations**. + +**Bad:** "Fix authentication" +**Good:** "Fix OAuth redirect loop where successful login redirects to /login instead of /dashboard. Reference the auth middleware in src/lib/auth.ts." + +Every subagent dispatch must include: + +1. **Full task text** — Paste the task from the plan; do not make the subagent read a file. +2. **Scene-setting context** — Where this task fits, dependencies, architecture. +3. **Relevant references** — File paths, SHAs, or snippets the subagent needs. +4. **Clear success criteria** — What “done” looks like and how to report back. + +--- + +## Four components of a good dispatch + +1. **Delegation** — One clear task per subagent; single responsibility. +2. **Isolated context** — Subagent has no prior conversation; give everything in the prompt. +3. **Task processing** — Subagent uses its own instructions and tools; parent stays in orchestration role. +4. **Result compression** — Subagent returns a concise summary (what was done, what was verified, any issues). + +--- + +## Project subagents + +| Agent | Purpose | When to invoke | +|-------|---------|----------------| +| **implementer** | Implements one plan task; tests, commits, self-reviews | Per task (use [implementer-prompt.md](./implementer-prompt.md) or invoke by name) | +| **spec-reviewer** | Checks implementation matches spec (by reading code, not the report) | After implementer, before code-quality-reviewer | +| **code-quality-reviewer** | Code quality, architecture, production readiness | Only after spec compliance is ✅ | + +**Order:** Implementer → Spec reviewer (fix until ✅) → Code quality reviewer (fix until approved) → next task. + +Code-quality-reviewer follows the template at [../requesting-code-review/code-reviewer.md](../requesting-code-review/code-reviewer.md); the parent supplies WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION. + +--- + +## Related skills + +- **writing-plans** — Produces the plan this skill executes. +- **using-git-worktrees** — Required: create an isolated workspace before starting. +- **requesting-code-review** — Code-quality-reviewer uses the code-reviewer template. +- **finishing-a-development-branch** — Use after all tasks and final review. + +--- + +## External references + +- [Anthropic Agent Skills](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview) — Skills overview, progressive loading, structure. +- [Claude Code Subagents](https://code.claude.com/docs/en/sub-agents) — Custom subagents in `.claude/agents/`, model options (`haiku`, `sonnet`, `opus`, `inherit`). +- [Claude Code Sub-Agents: Best Practices](https://zoer.ai/posts/zoer/claude-code-sub-agents-best-practices) — Three-tier pattern, context budget, validator pattern. +- [Sub-Agent Routing and Invocation](https://claudefa.st/blog/guide/agents/sub-agent-best-practices) — Parallel/sequential/background rules, invocation quality. diff --git a/.claude/skills/subagent-driven-development/SKILL.md b/.claude/skills/subagent-driven-development/SKILL.md index b578dfa..f3d434d 100644 --- a/.claude/skills/subagent-driven-development/SKILL.md +++ b/.claude/skills/subagent-driven-development/SKILL.md @@ -84,10 +84,14 @@ digraph process { ## Prompt Templates -- `./implementer-prompt.md` - Dispatch implementer subagent +- `./implementer-prompt.md` - Dispatch implementer subagent (full task text for Task tool) - `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent - `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent +**Custom subagent definitions** (Claude Code / Cursor): `.claude/agents/implementer.md`, `.claude/agents/spec-reviewer.md`, `.claude/agents/code-quality-reviewer.md`. Invoke by name (e.g. `/implementer`) or use the prompt templates below. + +**Reference (load when needed):** For routing (parallel vs sequential vs background), invocation quality, and skills-vs-subagents, read [ORCHESTRATION.md](./ORCHESTRATION.md) in this directory. + ## Example Workflow ``` diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index b5e8cfd..87d539a 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -21,8 +21,8 @@ jobs: runs-on: ubuntu-latest permissions: contents: read - pull-requests: read - issues: read + pull-requests: write # required to post review comments (read silently fails) + issues: write # used when posting/updating PR comment id-token: write steps: @@ -36,9 +36,13 @@ jobs: uses: anthropics/claude-code-action@v1 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + github_token: ${{ github.token }} # ensures workflow permissions are used for posting plugin_marketplaces: 'https://github.com/anthropics/claude-code.git' plugins: 'code-review@claude-code-plugins' - prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}' - # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md - # or https://code.claude.com/docs/en/cli-reference for available options + prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }} --comment' + track_progress: true # forces tag mode so a PR comment is created and updated (fixes #944) + # If gh CLI calls are blocked, uncomment: + # claude_args: '--allowedTools "Bash(gh api*),Bash(gh pr*),Bash(git*)"' + # See https://github.com/anthropics/claude-code-action/issues/944 + # and https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md