Add orchestration system (v3.3.0) #61
Conversation
WalkthroughThis PR introduces a comprehensive orchestration system that automatically delegates tasks to 20 specialized agents. It includes a generator script that creates agent specifications from skill files, a registry for agent discovery, updated session initialization to inject orchestration context, and extensive specialist agent documentation with integrated workflow guidance. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant SessionStart as session-start hook
participant Orchestrator as Orchestration Agent
participant Registry as Agent Registry
participant Specialist as Specialist Agent
participant Result as Report & Context
User->>SessionStart: Start session
SessionStart->>SessionStart: Load orchestrator instructions<br/>Load agent registry<br/>Load CLAUDE.md<br/>Load using-superpowers skill
SessionStart->>Orchestrator: Inject combined context
User->>Orchestrator: Request (with task description)
Orchestrator->>Registry: Semantic match skill?
Registry-->>Orchestrator: Match result + specialist info
alt Skill Match Found
Orchestrator->>Specialist: Dispatch task<br/>(with skill content)
Specialist->>Specialist: Execute skill workflow<br/>(verify checklist,<br/>follow steps,<br/>gather evidence)
Specialist-->>Result: Structured report<br/>(Summary, Recommendations,<br/>Blockers, Context)
Result-->>Orchestrator: Report received
Orchestrator->>Orchestrator: Process report<br/>(handle feedback,<br/>check for loops)
Orchestrator-->>User: Result + guidance
else No Skill Match
Orchestrator->>Orchestrator: Direct handling or<br/>user guidance
Orchestrator-->>User: Response
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes The changes span multiple dimensions: 20+ specialist agent documentation files following consistent patterns (moderate review per file), a generator script with logic for parsing, templating, and JSON registry construction (requires careful logic review), modifications to the critical session-start hook affecting control flow and context injection (high impact), orchestrator instructions with complex delegation and loop-prevention rules (dense logic), and multiple interconnected infrastructure files. While many specialist agents share a template structure, each requires verification for appropriateness and correctness. The heterogeneity of change types (code, scripts, documentation, data) and the scope across core infrastructure increase review complexity despite repetitive patterns in specialist files. Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 25
🧹 Nitpick comments (4)
docs/plans/2025-10-23-orchestration-system-design.md (1)
303-303: Consider using proper heading instead of emphasis.Line 303 uses emphasis (
**...**) where a structured heading might be clearer:## Token Usage (Per Task).The current emphasis markup is acceptable but converting to a heading would improve document structure:
-### Token Usage (Session Start) ... -### Token Usage (Per Task) +### Token Usage (Session Start) ... +### Token Usage (Per Task)(Note: The structure may already use headings; verify the markdown rendering.)
agents/receiving-code-review-specialist.md (1)
141-141: Verify signal phrase intent.Line 141 references "Strange things are afoot at the Circle K" as a signal for discomfort pushing back. While evocative, this pop-culture reference may reduce clarity for users unfamiliar with it. Consider a more explicit phrase like "I'm uncomfortable with this feedback but have technical concerns" for clarity.
agents/systematic-debugging-specialist.md (2)
89-119: Add language specification to fenced code blocks.Lines 89-119 contain a multi-layer system debugging example in a code block without a language identifier. Add
```bashto enable syntax highlighting and follow markdown best practices.- ``` + ```bash For EACH component boundary: - Log what data enters component - Log what data exits component
30-34: Add language specification to fenced code block.Line 30 introduces an "Iron Law" in a code block without language specification. Consider either removing the code fence (since it's plain text) or adding
```textif you want the fence for visual emphasis.-## The Iron Law - -``` -NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST -``` +## The Iron Law + +```text +NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST +```
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (31)
.claude-plugin/plugin.json(1 hunks)README.md(1 hunks)RELEASE-NOTES.md(1 hunks)agents/brainstorming-specialist.md(1 hunks)agents/condition-based-waiting-specialist.md(1 hunks)agents/defense-in-depth-specialist.md(1 hunks)agents/dispatching-parallel-agents-specialist.md(1 hunks)agents/executing-plans-specialist.md(1 hunks)agents/finishing-a-development-branch-specialist.md(1 hunks)agents/receiving-code-review-specialist.md(1 hunks)agents/requesting-code-review-specialist.md(1 hunks)agents/root-cause-tracing-specialist.md(1 hunks)agents/sharing-skills-specialist.md(1 hunks)agents/subagent-driven-development-specialist.md(1 hunks)agents/systematic-debugging-specialist.md(1 hunks)agents/test-driven-development-specialist.md(1 hunks)agents/testing-anti-patterns-specialist.md(1 hunks)agents/testing-skills-with-subagents-specialist.md(1 hunks)agents/using-git-worktrees-specialist.md(1 hunks)agents/using-superpowers-specialist.md(1 hunks)agents/verification-before-completion-specialist.md(1 hunks)agents/writing-plans-specialist.md(1 hunks)agents/writing-skills-specialist.md(1 hunks)docs/plans/2025-10-23-orchestration-system-design.md(1 hunks)docs/plans/2025-10-23-orchestration-system.md(1 hunks)hooks/session-start.sh(1 hunks)lib/agent-registry.json(1 hunks)lib/generate-specialists.sh(1 hunks)lib/orchestrator-instructions.md(1 hunks)templates/project-claude-md.template(1 hunks)templates/specialist-agent.template(1 hunks)
🧰 Additional context used
🪛 LanguageTool
lib/orchestrator-instructions.md
[style] ~36-~36: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...→ Answer directly - File reads → Handle directly - Quick commands → Handle directly - **...
(ADVERB_REPETITION_PREMIUM)
[style] ~37-~37: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...ndle directly - Quick commands → Handle directly - **IF task requires >2 tool calls → Wa...
(ADVERB_REPETITION_PREMIUM)
agents/subagent-driven-development-specialist.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...ity gates model: sonnet --- # Subagent Driven Development Specialist You are a...
(QB_NEW_EN_HYPHEN)
agents/systematic-debugging-specialist.md
[style] ~55-~55: ‘in a hurry’ might be wordy. Consider a shorter alternative.
Context: ...ple bugs have root causes too) - You're in a hurry (rushing guarantees rework) - Manager w...
(EN_WORDINESS_PREMIUM_IN_A_HURRY)
agents/writing-skills-specialist.md
[grammar] ~297-~297: Ensure spelling is correct
Context: ...ists - Labels without semantic meaning (step1, helper2) See @graphviz-conventions.do...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~382-~382: ‘under stress’ might be wordy. Consider a shorter alternative.
Context: ...s? - Pressure scenarios: Do they comply under stress? - Multiple pressures combined: time + ...
(EN_WORDINESS_PREMIUM_UNDER_STRESS)
[style] ~554-~554: To elevate your writing, try using a synonym here.
Context: ...e"]; ``` Why bad: Can't copy-paste, hard to read ### ❌ Generic Labels helper1, ...
(HARD_TO)
agents/testing-anti-patterns-specialist.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...ncies model: sonnet --- # Testing Anti Patterns Specialist You are a specialis...
(QB_NEW_EN_HYPHEN)
agents/testing-skills-with-subagents-specialist.md
[grammar] ~342-~342: Ensure spelling is correct
Context: ...ed flags list - [ ] Updated description ith violation symptoms - [ ] Re-tested - ag...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
agents/condition-based-waiting-specialist.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ... guesses model: sonnet --- # Condition Based Waiting Specialist You are a spec...
(QB_NEW_EN_HYPHEN)
[grammar] ~44-~44: Ensure spelling is correct
Context: ...ass sometimes, fail under load) - Tests timeout when run in parallel - Waiting for asyn...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
agents/test-driven-development-specialist.md
[grammar] ~7-~7: Use a hyphen to join words.
Context: ...failure first model: sonnet --- # Test Driven Development Specialist You are a...
(QB_NEW_EN_HYPHEN)
[grammar] ~266-~266: Use a hyphen to join words.
Context: ...ests after ≠ TDD. You get coverage, lose proof tests work. ## Common Rationaliza...
(QB_NEW_EN_HYPHEN)
[style] ~279-~279: To elevate your writing, try using a synonym here.
Context: ...clear" | Listen to test. Hard to test = hard to use. | | "TDD will slow me down" | T...
(HARD_TO)
🪛 markdownlint-cli2 (0.18.1)
agents/verification-before-completion-specialist.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
38-38: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
91-91: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
97-97: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
103-103: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
109-109: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
115-115: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/requesting-code-review-specialist.md
52-52: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/using-git-worktrees-specialist.md
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
150-150: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
170-170: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
174-174: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
178-178: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
182-182: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
188-188: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/plans/2025-10-23-orchestration-system-design.md
86-86: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
303-303: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
327-327: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
334-334: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
342-342: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
353-353: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
RELEASE-NOTES.md
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
lib/orchestrator-instructions.md
7-7: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
45-45: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
57-57: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
67-67: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
85-85: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
130-130: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
agents/subagent-driven-development-specialist.md
53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
76-76: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
97-97: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
123-123: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/dispatching-parallel-agents-specialist.md
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/systematic-debugging-specialist.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
89-89: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/brainstorming-specialist.md
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
63-63: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
102-102: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
114-114: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
146-146: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
165-165: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
191-191: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
197-197: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
203-203: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
209-209: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/root-cause-tracing-specialist.md
52-52: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/testing-anti-patterns-specialist.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
68-68: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
119-119: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
168-168: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
227-227: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
246-246: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
258-258: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/writing-plans-specialist.md
76-76: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
81-81: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
88-88: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
93-93: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
99-99: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/testing-skills-with-subagents-specialist.md
214-214: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
agents/test-driven-development-specialist.md
40-40: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
65-65: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
129-129: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
175-175: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
179-179: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
183-183: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
187-187: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
README.md
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
63-63: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/plans/2025-10-23-orchestration-system.md
18-18: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
76-76: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
81-81: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
95-95: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
126-126: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
131-131: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
136-136: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
150-150: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
226-226: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
231-231: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
239-239: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
254-254: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
259-259: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
264-264: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
269-269: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
274-274: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
288-288: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
342-342: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
352-352: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
363-363: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
440-440: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
445-445: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
459-459: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
505-505: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
510-510: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
524-524: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
529-529: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
632-632: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
637-637: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
645-645: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
659-659: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
664-664: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
726-726: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
747-747: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
752-752: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
815-815: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
836-836: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
841-841: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
845-845: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
850-850: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
864-864: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
881-881: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
886-886: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
891-891: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
896-896: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
901-901: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
913-913: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
918-918: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
922-922: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
936-936: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🪛 Shellcheck (0.11.0)
lib/generate-specialists.sh
[warning] 47-47: skill_content appears unused. Verify use (or export if used externally).
(SC2034)
🔇 Additional comments (18)
.claude-plugin/plugin.json (1)
4-4: LGTM — Version bump is appropriate.The version bump to 3.3.0 correctly reflects the addition of the orchestration system feature set.
templates/project-claude-md.template (1)
1-40: Good template structure — clear guidance for projects.The template provides clear sections for project customization while correctly noting that orchestration instructions load automatically. The balance between guidance and autonomy is well-struck.
templates/specialist-agent.template (1)
1-51: LGTM — Well-designed template for agent generation.The template structure is clean, with clear placeholders that integrate well with the generator script. Reporting requirements and critical rules are appropriately standardized across all specialists.
agents/finishing-a-development-branch-specialist.md (1)
1-246: Well-structured specialist guide with clear workflow and safeguards.This finishing-a-development-branch specialist guide is comprehensive and well-organized. The step-by-step process, quick reference table, and "Red Flags" section provide excellent guidance for branch completion. Integration points with other skills are clearly documented.
agents/sharing-skills-specialist.md (1)
1-240: Well-documented skill-sharing workflow with practical guidance.The sharing-skills specialist guide is comprehensive and clear. The prerequisites, step-by-step workflow, complete example, and troubleshooting section provide excellent practical guidance. The enforcement of single-skill PRs (lines 193–202) is a good quality gate.
hooks/session-start.sh (4)
35-87: Context assembly is well-structured with proper conditional guards.The COMBINED_CONTEXT construction properly checks for non-empty variables before appending, maintains consistent formatting with section markers, and follows a logical order (skill enforcement → orchestration → registry → project instructions).
89-96: JSON output structure is correctly formed with proper quoting.The jq invocation safely passes COMBINED_CONTEXT using --arg to avoid shell escaping issues, and returns the expected hookSpecificOutput.additionalContext structure. Output formatting looks correct.
3-3: Simplified error handling withset -eis appropriate.The addition of
set -ewill cause the script to exit immediately on any command failure, which is a reasonable approach for this initialization hook. This is better than the previous implicit behavior.
1-12: PLUGIN_DIR path resolution is correct and works as intended.Verification confirms that the relative path logic on line 5 correctly computes the plugin root directory from the hooks/session-start.sh location. The BASH_SOURCE[0] approach reliably handles script invocation regardless of current working directory or symbolic links, and all referenced files (lib/orchestrator-instructions.md, lib/agent-registry.json) are accessible from the computed path.
agents/executing-plans-specialist.md (1)
1-123: Specialist structure and content look solid.The executing-plans specialist is well-organized with clear phases, specific guardrails, and actionable instructions. Reporting requirements and critical rules follow the expected pattern.
agents/receiving-code-review-specialist.md (1)
1-247: Content and structure are comprehensive and well-reasoned.The skill execution content is clear with good examples, explicit forbidden responses, and practical guidance. Reporting requirements are consistent with the specialist pattern.
agents/systematic-debugging-specialist.md (1)
1-341: Systematic debugging skill is well-structured with clear methodology.The four-phase framework is thorough, actionable, and includes excellent supporting content (red flags, rationalizations, quick reference). The integration with other skills (root-cause-tracing, test-driven-development as REQUIRED SUB-SKILLs) is clearly documented. Content is sound and comprehensive.
agents/using-superpowers-specialist.md (1)
1-125: Using-superpowers specialist is clear and directive.The skill usage requirements are explicit, the mandatory workflows are well-justified, and reporting requirements are consistent with other specialists. Structure and content are appropriate.
agents/writing-skills-specialist.md (2)
297-299: Verify external reference to graphviz conventions.Line 299 references
@graphviz-conventions.dot, which appears to be an external file reference. Verify that:
- This file exists in the repository, or
- This is documentation (not a force-load), in which case remove the
@syntax to prevent loading overheadAs noted in the CSO guidelines (line 271),
@syntax force-loads files immediately and should be avoided.
1-666: Writing-skills specialist is comprehensive and well-reasoned.The TDD-adapted framework for skill creation is detailed and thorough. Coverage of testing strategies, anti-patterns, bulletproofing techniques, and the complete RED-GREEN-REFACTOR cycle is excellent. Reporting requirements and critical rules are consistent with other specialists.
docs/plans/2025-10-23-orchestration-system.md (2)
226-237: Verify specialist count in generator logic.Task 3 (lines 226-237) includes verification steps that expect "20" specialists:
Run: ls agents/*-specialist.md | wc -l Expected: 20 (or number of skills)However, the agent registry (lib/agent-registry.json) contains 21 entries. Confirm whether:
- The plan should expect 21 specialists (not 20), or
- The registry is incorrect and should contain 20
This discrepancy should be resolved before deployment to avoid confusion.
1-973: Implementation plan is detailed and well-structured.The 12-task breakdown provides clear step-by-step guidance with concrete verification steps for each phase. Task descriptions are specific, expected outputs are measurable, and the final success criteria are comprehensive. The plan appropriately guides through generator creation, registry building, hook updates, and documentation.
lib/agent-registry.json (1)
1-141: Agent registry is well-formed and comprehensive.The JSON registry contains 20 specialist entries with consistent structure (name, description, agent_file, skill_name). Each entry's description is specific and informative. File paths follow a predictable pattern. The registry is valid JSON and ready for use by the orchestration system.
| ## Quick Reference | ||
|
|
||
| | Phase | Key Activities | Tool Usage | Output | | ||
| |-------|---------------|------------|--------| | ||
| | **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria | | ||
| | **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs | | ||
| | **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation | | ||
| | **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ | | ||
| | **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment | | ||
| | **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown | | ||
|
|
||
| ## The Process | ||
|
|
||
| Copy this checklist to track progress: | ||
|
|
||
| ``` | ||
| Brainstorming Progress: | ||
| - [ ] Phase 1: Understanding (purpose, constraints, criteria gathered) | ||
| - [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated) | ||
| - [ ] Phase 3: Design Presentation (design validated in sections) | ||
| - [ ] Phase 4: Design Documentation (design written to docs/plans/) | ||
| - [ ] Phase 5: Worktree Setup (if implementing) | ||
| - [ ] Phase 6: Planning Handoff (if implementing) | ||
| ``` | ||
|
|
||
| ### Phase 1: Understanding | ||
| - Check current project state in working directory | ||
| - Ask ONE question at a time to refine the idea | ||
| - **Use AskUserQuestion tool** when you have multiple choice options | ||
| - Gather: Purpose, constraints, success criteria | ||
|
|
||
| **Example using AskUserQuestion:** | ||
| ``` | ||
| Question: "Where should the authentication data be stored?" | ||
| Options: | ||
| - "Session storage" (clears on tab close, more secure) | ||
| - "Local storage" (persists across sessions, more convenient) | ||
| - "Cookies" (works with SSR, compatible with older approach) | ||
| ``` | ||
|
|
||
| ### Phase 2: Exploration | ||
| - Propose 2-3 different approaches | ||
| - For each: Core architecture, trade-offs, complexity assessment | ||
| - **Use AskUserQuestion tool** to present approaches as structured choices | ||
| - Ask your human partner which approach resonates | ||
|
|
||
| **Example using AskUserQuestion:** | ||
| ``` | ||
| Question: "Which architectural approach should we use?" | ||
| Options: | ||
| - "Event-driven with message queue" (scalable, complex setup, eventual consistency) | ||
| - "Direct API calls with retry logic" (simple, synchronous, easier to debug) | ||
| - "Hybrid with background jobs" (balanced, moderate complexity, best of both) | ||
| ``` | ||
|
|
||
| ### Phase 3: Design Presentation | ||
| - Present in 200-300 word sections | ||
| - Cover: Architecture, components, data flow, error handling, testing | ||
| - Ask after each section: "Does this look right so far?" (open-ended) | ||
| - Use open-ended questions here to allow freeform feedback | ||
|
|
||
| ### Phase 4: Design Documentation | ||
| After design is validated, write it to a permanent document: | ||
| - **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic) | ||
| - **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality | ||
| - **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation | ||
| - Commit the design document to git before proceeding | ||
|
|
||
| ### Phase 5: Worktree Setup (for implementation) | ||
| When design is approved and implementation will follow: | ||
| - Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace." | ||
| - **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees | ||
| - Follow that skill's process for directory selection, safety verification, and setup | ||
| - Return here when worktree ready | ||
|
|
||
| ### Phase 6: Planning Handoff | ||
| Ask: "Ready to create the implementation plan?" | ||
|
|
||
| When your human partner confirms (any affirmative response): | ||
| - Announce: "I'm using the writing-plans skill to create the implementation plan." | ||
| - **REQUIRED SUB-SKILL:** Use superpowers:writing-plans | ||
| - Create detailed plan in the worktree | ||
|
|
||
| ## Question Patterns | ||
|
|
||
| ### When to Use AskUserQuestion Tool | ||
|
|
||
| **Use AskUserQuestion for:** | ||
| - Phase 1: Clarifying questions with 2-4 clear options | ||
| - Phase 2: Architectural approach selection (2-3 alternatives) | ||
| - Any decision with distinct, mutually exclusive choices | ||
| - When options have clear trade-offs to explain | ||
|
|
||
| **Benefits:** | ||
| - Structured presentation of options with descriptions | ||
| - Clear trade-off visibility for partner | ||
| - Forces explicit choice (prevents vague "maybe both" responses) | ||
|
|
||
| ### When to Use Open-Ended Questions | ||
|
|
||
| **Use open-ended questions for:** | ||
| - Phase 3: Design validation ("Does this look right so far?") | ||
| - When you need detailed feedback or explanation | ||
| - When partner should describe their own requirements | ||
| - When structured options would limit creative input | ||
|
|
||
| **Example decision flow:** | ||
| - "What authentication method?" → Use AskUserQuestion (2-4 options) | ||
| - "Does this design handle your use case?" → Open-ended (validation) | ||
|
|
||
| ## When to Revisit Earlier Phases | ||
|
|
||
| ```dot | ||
| digraph revisit_phases { | ||
| rankdir=LR; | ||
| "New constraint revealed?" [shape=diamond]; | ||
| "Partner questions approach?" [shape=diamond]; | ||
| "Requirements unclear?" [shape=diamond]; | ||
| "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"]; | ||
| "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"]; | ||
| "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"]; | ||
| "New constraint revealed?" -> "Return to Phase 1" [label="yes"]; | ||
| "New constraint revealed?" -> "Partner questions approach?" [label="no"]; | ||
| "Partner questions approach?" -> "Return to Phase 2" [label="yes"]; | ||
| "Partner questions approach?" -> "Requirements unclear?" [label="no"]; | ||
| "Requirements unclear?" -> "Return to Phase 1" [label="yes"]; | ||
| "Requirements unclear?" -> "Continue forward" [label="no"]; | ||
| } | ||
| ``` | ||
|
|
||
| **You can and should go backward when:** | ||
| - Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1 | ||
| - Validation shows fundamental gap in requirements → Return to Phase 1 | ||
| - Partner questions approach during Phase 3 → Return to Phase 2 | ||
| - Something doesn't make sense → Go back and clarify | ||
|
|
||
| **Don't force forward linearly** when going backward would give better results. | ||
|
|
||
| ## Key Principles | ||
|
|
||
| | Principle | Application | | ||
| |-----------|-------------| | ||
| | **One question at a time** | Phase 1: Single question per message, use AskUserQuestion for choices | | ||
| | **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs | | ||
| | **YAGNI ruthlessly** | Remove unnecessary features from all designs | | ||
| | **Explore alternatives** | Always propose 2-3 approaches before settling | | ||
| | **Incremental validation** | Present design in sections, validate each | | ||
| | **Flexible progression** | Go backward when needed - flexibility > rigidity | | ||
| | **Announce usage** | State skill usage at start of session | | ||
|
|
||
| ## Reporting Requirements | ||
|
|
||
| After completing your work, provide a structured report with these sections: | ||
|
|
||
| ### 1. Summary | ||
| - What task you completed | ||
| - Which skill steps you followed | ||
| - Key actions taken (files modified, commands run, decisions made) | ||
| - Final status: ✅ Success | ⚠️ Partial | ❌ Blocked | ||
|
|
||
| ### 2. Recommendations | ||
| - Suggested next skills to invoke (if workflow should continue) | ||
| - Alternative approaches if current path is blocked | ||
| - Improvements or optimizations identified | ||
|
|
||
| ### 3. Blockers & Questions | ||
| - Any issues preventing completion | ||
| - Decisions requiring user input | ||
| - Clarifications needed from orchestrator | ||
|
|
||
| ### 4. Context for Orchestrator | ||
| - Any state/context the orchestrator should preserve | ||
| - Files to watch for changes | ||
| - Artifacts created that other specialists might need | ||
|
|
||
| --- | ||
|
|
||
| ## Critical Rules | ||
|
|
||
| - **Execute the skill exactly as written** - no shortcuts, no "I remember this" | ||
| - **If skill has checklist** - you must complete every item |
There was a problem hiding this comment.
Add language specifiers to multiple fenced code blocks.
Static analysis flagged 10+ fenced code blocks without language identifiers. Review and add appropriate language specifiers (e.g., ```markdown, ```plaintext, ```dot) to all code fence regions.
Notable examples:
- Lines 43–51: Checklist (use
```markdown) - Lines 60–66: Pseudocode example (use
```plaintextor```text) - Lines 140–156: Graphviz digraph (use
```dot)
Apply language specifiers consistently across all fenced blocks in this file.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
63-63: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
102-102: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
114-114: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
146-146: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
165-165: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
191-191: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
197-197: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
203-203: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
209-209: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In agents/brainstorming-specialist.md around lines 28 to 209 there are 10+
fenced code blocks missing language specifiers; add appropriate language
identifiers to every fenced block (e.g., ```markdown for the checklist at
~43-51, ```plaintext or ```text for the pseudocode at ~60-66, and ```dot for the
Graphviz digraph at ~140-156) and scan the rest of the section to consistently
label each fenced region with the correct language so syntax highlighting and
static analysis warnings are resolved.
| --- | ||
| name: condition-based-waiting-specialist | ||
| description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses | ||
| model: sonnet | ||
| --- | ||
|
|
||
| # Condition Based Waiting Specialist |
There was a problem hiding this comment.
Fix title hyphenation and ensure code blocks have language specifiers.
Line 7 should hyphenate compound adjectives. Additionally, several fenced code blocks (lines 78–97) lack language identifiers.
- # Condition Based Waiting Specialist
+ # Condition-Based Waiting SpecialistFor code blocks, add language identifiers:
- async function waitFor<T>(
+ ```typescript
+ async function waitFor<T>(🧰 Tools
🪛 LanguageTool
[grammar] ~7-~7: Use a hyphen to join words.
Context: ... guesses model: sonnet --- # Condition Based Waiting Specialist You are a spec...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In agents/condition-based-waiting-specialist.md around lines 1 to 7, fix the
title by hyphenating the compound adjective to "Condition-Based Waiting
Specialist", and between lines 78 and 97 add language identifiers to any fenced
code blocks (e.g., change opening ``` to ```typescript) so code blocks are
properly highlighted; also scan the file for other fenced blocks and add the
appropriate language specifier where missing.
| **Dispatch:** | ||
| ``` | ||
| Agent 1 → Fix agent-tool-abort.test.ts | ||
| Agent 2 → Fix batch-completion-behavior.test.ts | ||
| Agent 3 → Fix tool-approval-race-conditions.test.ts | ||
| ``` |
There was a problem hiding this comment.
Add language specifier to fenced code block.
Line 155 code block lacks a language identifier. For pseudocode or plain text output, use ```plaintext or ```text.
- ```
+ ```plaintext
Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts
- ```
+ ```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In agents/dispatching-parallel-agents-specialist.md around lines 154 to 159, the
fenced code block opening backticks lack a language specifier; update the
opening fence to include a plain text language (e.g., change ``` to ```plaintext
or ```text) so the block becomes a labeled fenced code block and leave the
closing fence unchanged.
| - `{WHAT_WAS_IMPLEMENTED}` - What you just built | ||
| - `{PLAN_OR_REQUIREMENTS}` - What it should do | ||
| - `{BASE_SHA}` - Starting commit | ||
| - `{HEAD_SHA}` - Ending commit |
There was a problem hiding this comment.
Add language specification to fenced code block.
Line 52 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.
Apply this diff to fix:
-```
+```bash
BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
52-52: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In agents/requesting-code-review-specialist.md around line 52, the fenced code
block lacks a language specifier which triggers MD040; update the opening fence
to include the language by changing the triple backticks to "```bash" so the
block becomes a bash code fence (keep the existing closing ```).
| ## The Tracing Process | ||
|
|
||
| ### 1. Observe the Symptom | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language identifier to code block.
Line 52 has a fenced code block without a language tag. Add bash or appropriate language identifier.
-```
+```
Error: git init failed in /Users/jesse/project/packages/core
> Committable suggestion skipped: line range outside the PR's diff.
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
52-52: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In agents/root-cause-tracing-specialist.md around line 52, the fenced code block
lacks a language identifier; replace the opening triple backticks with a
language-tagged fence (e.g., ```bash) so the block reads as a bash snippet and
ensures proper syntax highlighting for the error message.
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
|
|
||
| ## Critical Rule: Mandatory Delegation | ||
|
|
||
| **IF A SKILL EXISTS FOR THIS TASK → YOU MUST DELEGATE TO THE SPECIALIST** |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language identifiers to code blocks and fix emphasis-as-heading markup.
Multiple fenced code blocks are missing language tags (lines 45, 57, 67), and section emphasis markers should be proper headings (lines 7, 85, 130).
Fix emphasis-as-heading patterns:
-**IF A SKILL EXISTS FOR THIS TASK → YOU MUST DELEGATE TO THE SPECIALIST**
+### IF A SKILL EXISTS FOR THIS TASK → YOU MUST DELEGATE TO THE SPECIALISTAnd for code blocks:
-```
+```
User: "Create authentication feature"
→ Call brainstorming-specialist (design)
→ Receive design reportApply language tags to all fenced code blocks at lines 45, 57, 67 (and any others without language specification).
Also applies to: 45-45, 57-57, 67-67, 85-85, 130-130
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
7-7: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
|
|
||
| 1. **You make a request** → Main Claude (orchestrator) receives it | ||
| 2. **Orchestrator checks registry** → Matches your request to appropriate specialist agent | ||
| 3. **Specialist executes skill** → Expert agent applies the relevant skill systematically |
There was a problem hiding this comment.
Add language specification to fenced code block.
Line 54 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.
Apply this diff:
-```
+```bash
/superpowers:brainstorm
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In README.md around line 54 there is a fenced code block missing a language
identifier which triggers MD040; update the opening fence to include the bash
language spec by changing the opening ``` to ```bash so the block becomes
```bash followed by the existing content (/superpowers:brainstorm) and keep the
closing ``` unchanged.
| - **Context preservation:** Orchestrator stays focused on workflow management, specialists handle execution details | ||
| - **Systematic skill application:** Every specialist follows proven skill methodology exactly | ||
| - **Performance:** Only relevant skills load (not all 20 skills per session) | ||
| - **Reliability:** Clear delegation rules prevent ad-hoc "I'll do it myself" shortcuts |
There was a problem hiding this comment.
Add language specification to fenced code block.
Line 63 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.
Apply this diff:
-```
+```markdown
## Custom Orchestration Rules
- Skip brainstorming for minor bug fixes under 10 lines
- Always use test-driven-development for API endpoints
- Require code review before merging features
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
63-63: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In README.md around line 63, the fenced code block lacks a language identifier
which triggers MD040; update the opening fence to include the language spec
"markdown" (i.e., change the opening triple backticks to ```markdown) and ensure
the block is properly closed with a matching triple backticks so the block is
correctly recognized by the linter.
|
|
||
| ### Project-Specific Configuration | ||
|
|
||
| Projects can customize orchestration via `CLAUDE.md`: |
There was a problem hiding this comment.
Add language specification to fenced code block.
Line 80 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.
Apply this diff:
-```
+```bash
./lib/generate-specialists.sh
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In README.md around line 80, the fenced code block lacks a language identifier
causing MD040; change the closing/opening fence to include the language by
replacing the triple backticks with a fenced block labelled "bash" (i.e., use
```bash before the code and ``` after) so the block becomes a bash code fence
containing ./lib/generate-specialists.sh.
| - `templates/project-claude-md.template` - Default project CLAUDE.md | ||
| - `agents/*-specialist.md` - 20 specialist agent definitions (auto-generated) | ||
|
|
||
| ### Breaking Changes |
There was a problem hiding this comment.
Add language specification to fenced code block.
Lines 28 shows a fenced code block (lines 54-58) without a language identifier. This triggers markdown linting warning MD040.
Apply this diff to fix:
-```
+```bash
./lib/generate-specialists.sh
git add agents/*-specialist.md lib/agent-registry.json
git commit -m "Regenerate specialists"
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
RELEASE-NOTES.md around lines 28 to 28: the fenced code block starting at that
location (covering the commands shown on lines ~54-58) is missing a language
identifier which triggers MD040; update the opening fence to include the
language (bash) so the block starts with ```bash (leave the closing fence as
```), i.e. modify the opening fence line only to add "bash" per the supplied
diff.
|
Hi. This looks like a pretty different tool than the one I built. I'd encourage you to create your own claude code plugin with its own name and release it :) |
2 participants
Summary
This PR implements the orchestration system that transforms superpowers into a delegating orchestrator that routes tasks to specialist agents, each expert in one skill.
Key Changes:
skills/*/SKILL.mdArchitecture
Components Added:
lib/generate-specialists.sh) - Builds specialist agents from skillslib/agent-registry.json) - 20 specialist metadata entries (auto-generated)lib/orchestrator-instructions.md) - Core delegation rulesagents/*-specialist.md) - 20 pre-generated agentsSessionStart Hook Updated:
How It Works
Files Changed
New Files:
lib/generate-specialists.sh- Generator scriptlib/agent-registry.json- Specialist registry (auto-generated)lib/orchestrator-instructions.md- Orchestration rulestemplates/specialist-agent.template- Agent templatetemplates/project-claude-md.template- Default project CLAUDE.mdagents/*-specialist.md- 20 specialist agents (auto-generated)docs/plans/2025-10-23-orchestration-system-design.md- Design docdocs/plans/2025-10-23-orchestration-system.md- Implementation planModified Files:
hooks/session-start.sh- Updated to inject orchestration contextREADME.md- Added Orchestration Mode sectionRELEASE-NOTES.md- Added v3.3.0 release notes.claude-plugin/plugin.json- Version bumped to 3.3.0Performance
Backward Compatibility
Testing
Manual testing completed:
Design Document
See
docs/plans/2025-10-23-orchestration-system-design.mdfor complete design rationale and architecture.Commits
All commits follow implementation plan in
docs/plans/2025-10-23-orchestration-system.md:Summary by CodeRabbit
Release Notes
New Features
Documentation
Chores