feat(agents): add new agents for task implementation and review process

[chinkan]

• Introduced implementer agent for executing tasks from implementation plans, including self-review and testing.
• Added spec-reviewer agent to verify that implementations match specifications, emphasizing independent code inspection.
• Created code-quality-reviewer agent to assess code quality, architecture, and production readiness after spec compliance.
• Developed ORCHESTRATION.md for subagent workflow guidance and routing rules, detailing sequential and parallel task execution.
• Updated SKILL.md to include references to new agent definitions and prompt templates.

[github-actions]

Claude finished @chinkan's task in 1m 51s —— View job

---

Code Review — feat(agents): add new agents for task implementation and review process

• Gather context and read changed files
• Review agent definitions
• Review ORCHESTRATION.md and SKILL.md
• Review workflow changes
• Post final feedback

---

Summary

This PR adds a three-tier subagent review pipeline (implementer → spec-reviewer → code-quality-reviewer) and the supporting orchestration documentation, plus workflow fixes. The design is solid and the instructions are well-written. A few observations below.

---

Agent Definitions (.claude/agents/)

implementer.md — Well structured. The before/during/self-review loop is clear. model: inherit is the right choice so the orchestrator controls model selection at dispatch time.

spec-reviewer.md — model: haiku is a reasonable cost trade-off, but worth noting: Haiku may miss subtle mismatches in complex implementations. If reviewers frequently miss issues, consider bumping to sonnet.

code-quality-reviewer.md — Minor inconsistency in the required inputs list. The frontmatter description (line 4) lists WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION, but the body (line 12) groups them as WHAT_WAS_IMPLEMENTED / DESCRIPTION. These overlap and could confuse a parent agent building the invocation. Consider clarifying whether WHAT_WAS_IMPLEMENTED and DESCRIPTION are the same field or distinct. Fix this →

---

ORCHESTRATION.md

Good routing table (parallel / sequential / background) and the invocation quality examples ("Fix authentication" vs the good alternative) are genuinely useful.

One concern: Line 97 references .cursor/agents/ in a note about Cursor Subagents — this project uses Claude Code (.claude/agents/), not Cursor. This could be misleading if an agent reads this file expecting .cursor/agents/ to be relevant. Fix this →

Line 80 references ../requesting-code-review/code-reviewer.md — confirmed this file exists at .claude/skills/requesting-code-review/code-reviewer.md. No issue.

---

SKILL.md

The dot graph diagrams are a creative way to document the workflow, though they won't render in GitHub Markdown — they're readable by the agent when loaded. That tradeoff is fine here.

The Red Flags section is particularly well done — actionable and specific. The "never" list prevents the most common subagent pitfalls.

Minor: In the "Integration" section (lines 237–244), the superpowers: prefix convention (e.g., superpowers:using-git-worktrees) needs to be consistent with how the orchestrating agent actually invokes skills. If the skill system uses a different invocation pattern, these references could silently fail. Worth verifying the prefix is correct for this environment.

---

Workflow Changes (.github/workflows/claude-code-review.yml)

The permission additions (pull-requests: write, issues: write) and github_token parameter are necessary and correct for the PR comment workflow. track_progress: true correctly addresses issue #944.

No concerns here.

---

Overall Assessment

Ready to merge. The pipeline design is sound, instructions are clear, and the prompt templates (implementer-prompt.md, spec-reviewer-prompt.md, code-quality-reviewer-prompt.md) are already in the repo. The inconsistency in code-quality-reviewer.md inputs and the stale Cursor reference in ORCHESTRATION.md are minor and don't block the PR.

[github-actions]

Claude finished @chinkan's task in 1m 28s —— View job

---

Code Review — feat(agents): add new agents for task implementation and review process

• Read changed files
• Review agent definitions
• Review ORCHESTRATION.md and SKILL.md
• Review workflow changes
• Post final feedback

---

Summary

This PR introduces a three-tier subagent review pipeline (implementer → spec-reviewer → code-quality-reviewer) with supporting orchestration documentation, plus workflow permission fixes. The pipeline design is well-thought-out and the instructions are clear. Two of the issues flagged in the previous review have already been addressed in follow-up commits (da2039f removes the Cursor reference, 8f539eb fixes workflow permissions). One minor ambiguity remains.

---

Agent Definitions (.claude/agents/)

implementer.md — Well-structured. The before/during/self-review loop enforces quality discipline. model: inherit is correct — lets the orchestrator control model selection at dispatch time. The emphasis on asking questions before starting (not after) is good practice.

spec-reviewer.md — model: haiku is a reasonable cost trade-off. The "Do Not Trust the Report" section is the standout feature here — the explicit prohibition on accepting the implementer's claims without reading code is exactly the right mindset for an independent verifier.

code-quality-reviewer.md — One remaining ambiguity: the What You Will Receive section lists WHAT_WAS_IMPLEMENTED / DESCRIPTION on line 12, but then lists DESCRIPTION again as a separate bullet on line 16. Cross-referencing with code-quality-reviewer-prompt.md, these are clearly distinct fields (WHAT_WAS_IMPLEMENTED = implementer's report of what was built; DESCRIPTION = original task summary). The / notation on line 12 makes them look interchangeable. Fix this →

---

ORCHESTRATION.md

The Cursor reference previously flagged in line 97 has been removed (commit da2039f). The file is now clean. The routing table (parallel / sequential / background), invocation quality examples, and project subagent table are all well-written.

The reference on line 80 to ../requesting-code-review/code-reviewer.md is consistent with how code-quality-reviewer-prompt.md invokes it (requesting-code-review/code-reviewer.md). No issues.

---

SKILL.md

The dot graph diagrams are a creative way to document workflow — readable by the agent even if they don't render in GitHub Markdown. The Red Flags / "Never" section is particularly strong: concrete, actionable, and covers the most common subagent pitfalls.

The superpowers: prefix convention in the Integration section (lines 237–244) is consistent with how this project's skill system works per CLAUDE.md, so no concern there.

---

Workflow (.github/workflows/claude-code-review.yml)

The permission additions (pull-requests: write, issues: write), explicit github_token parameter, and track_progress: true are all correct and necessary. No concerns.

---

Overall Assessment

Ready to merge. The pipeline design is solid, the agent instructions are specific and well-motivated, and the two previously flagged issues (Cursor reference, workflow permissions) have already been resolved. The remaining WHAT_WAS_IMPLEMENTED / DESCRIPTION grouping in code-quality-reviewer.md is a minor clarity issue that doesn't block merging.