Built-in Development Orchestrator: multi-agent workflow with spec → design → implement → review → test pipeline

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The Problem

When using Claude Code for non-trivial feature development, the default single-agent approach has significant gaps:

1. No structured quality gates. There's no built-in mechanism to ensure requirements are fully understood before design starts, or that design is approved before implementation begins. Developers jump straight to coding, often misunderstanding the request.

1. No systematic review process. Code review happens ad-hoc — if at all. There's no separation between functional correctness, security, standards compliance, and cost/performance review. Issues slip through.

1. No parallel execution model for implementation. Complex features that could be broken into 3-4 independent tasks are implemented sequentially, wasting time.

1. No feedback loops with iteration caps. When review or test issues are found, there's no structured fix → re-review cycle. Developers either over-iterate or give up.

1. No smoke test gate. Unit tests with mocks pass, but runtime integration issues (wrong types from config, missing imports, bad env var handling) aren't caught until production.

I built a full orchestration system for a personal project using .claude/agents/ that solves all of these problems. It consists of 11 specialized agents coordinated by a central orchestrator that drives a 7-phase development lifecycle. After months of real-world use across hundreds of commits and dozens of PRs, the pattern has proven extremely effective — but it took significant effort to set up, and most Claude Code users will never build something like this.

What I Built (Proof of Concept)

My orchestration system defines these specialist agents:

| Phase | Agent | Role |
|-------|-------|------|
| 0. Requirements | Spec Analyst | Validates feature requests are complete; asks clarifying questions; produces READY/NEEDS_CLARIFICATION verdict |
| 1. Design | Designer | Produces design specs from clarified requirements; searches codebase for existing patterns |
| 2. Planning | Planner | Breaks design into parallelizable task groups with dependency ordering |
| 3. Implementation | Developer (multiple) | Implements tasks — multiple developers run in parallel per task group |
| 3.5. Smoke Test | Developer | Mandatory runtime validation before review (catches what mocked unit tests miss) |
| 4. Review | 4 Reviewers (functional, security, standards, cost) | Parallel specialized review with fix → verify → re-review loops (capped at 3 iterations) |
| 5. Testing | Tester | Writes and runs tests with fix cycles |
| 6. Docs | Developer | Updates architecture docs, decision records, lessons learned |
| 7. Post-mortem | Skills Analyst | Extracts reusable patterns from the session into skill files |

Key design decisions that emerged from real usage:

• Mandatory user checkpoints between every phase — the orchestrator never proceeds without explicit approval
• The orchestrator is a coordinator, not an implementer — it NEVER writes code itself, only delegates
• Fix verification rules — TODO comments and try/except wrappers are rejected as fixes for BLOCK findings
• Parallel execution via multiple Agent calls in the same response
• Feedback loops capped at 3 iterations to prevent infinite fix cycles
• Smoke test gate between implementation and review catches runtime issues that mocked unit tests miss

Proposed Solution

Proposed Solution

Add a built-in /orchestrate command (or similar) to Claude Code that ships a pre-configured multi-agent development pipeline out of the box. This would be a first-class feature, not something every user needs to build from scratch.

What it would look like

claude /orchestrate "Add a caching layer to the API endpoint"

This would automatically:

1. Clarify requirements — analyze the request, ask targeted questions if ambiguous, confirm understanding
2. Design — produce a design spec that references existing codebase patterns
3. Plan — break the design into parallelizable task groups
4. Implement — spawn multiple developer agents in parallel for independent tasks
5. Smoke test — run the code to catch runtime issues before review
6. Review — run specialized reviewers (functional, security, standards) in parallel with fix loops
7. Test — write and run tests with automated fix cycles
8. Document — update relevant docs

Each phase would pause for user approval before proceeding (configurable — advanced users could auto-approve certain phases).

Why this should be built-in, not user-configured

1. Consistency — Every Claude Code user would benefit from a proven development workflow. Right now, quality depends entirely on how well each individual prompts Claude. A built-in orchestrator establishes a baseline.

1. Quality gates — The review loops, smoke tests, and fix verification rules I developed through trial and error (e.g., rejecting TODO comments as fixes, capping feedback loops at 3 iterations, verifying config type safety) encode hard-won lessons that most users will never discover on their own.

1. Accessibility — Setting up 11 custom agents with carefully tuned prompts, tool permissions, and coordination logic took me weeks of iteration. Most developers won't do this. A built-in orchestrator democratizes the workflow.

1. Parallel execution — The orchestrator spawns multiple developer and reviewer agents simultaneously, which dramatically speeds up complex features. This pattern (multiple Agent calls in one response) is powerful but non-obvious.

Configuration surface

The orchestrator could be customizable via .claude/orchestrator.yml or similar:

• Which review types to enable (functional, security, standards, cost)
• Auto-approve phases vs. checkpoint phases
• Max feedback loop iterations (default: 3)
• Whether to run post-mortem skills analysis
• Custom reviewer focus areas per project

Reference Implementation

I have a working implementation in a private repo with 11 agent definitions (orchestrator, spec-analyst, designer, planner, developer, 4 reviewers, tester, and skills-analyst) — happy to share access with Anthropic team members and collaborate on adapting this into a generic, project-agnostic built-in feature.

Alternative Solutions

Current workaround: I manually built 11 agent definitions in .claude/agents/ (orchestrator, spec-analyst, designer, planner, developer, 4 reviewers, tester, skills-analyst) with carefully tuned prompts and coordination logic. This works well but took weeks to iterate on and isn't something most users would set up.

Other approaches I considered:

• Single long prompt — Tried putting the entire workflow in CLAUDE.md instructions. Too unwieldy; Claude loses track of which phase it's in and starts implementing before design is approved.
• Manual phase-by-phase prompting — Works but is tedious. You end up re-explaining context at each step. The orchestrator agent solves this by carrying context across phases.
• External tools (Cursor, Aider, etc.) — Other AI coding tools don't have Claude Code's Agent tool for spawning parallel sub-agents, which is the key enabler for this pattern.

The .claude/agents/ system in Claude Code already provides the building blocks — the missing piece is a pre-built, battle-tested orchestration workflow that ships out of the box.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

Scenario: Adding a new module to a complex Python backend that requires a new data processor, service layer, API endpoints, config, and CI/CD integration.

1. I run claude /orchestrate "Add a new data ingestion module with validation and retry logic"
2. The spec analyst first asks: "Does this apply to all data sources or a subset? What validation rules? Should failures retry or dead-letter?" — catching ambiguities before any code is written.
3. The designer searches my codebase, finds an existing ingestion module as the closest pattern, and produces a spec that follows the same architecture.
4. The planner breaks it into 4 parallel tasks: (A) data processor module, (B) service layer, (C) config/env setup, (D) CI workflow — with Group B depending on Group A.
5. 4 developer agents run in parallel for Group A tasks, then Group B tasks execute after.
6. A smoke test catches that a config value loaded from an env var is a string instead of a float — something unit tests with mocks would never find.
7. 3 reviewers (functional, security, standards) run in parallel, flag 2 issues. A developer agent fixes them. Re-review passes.
8. The tester writes 12 unit tests, all pass.
9. Total time: ~15 minutes of wall clock for a feature that would take hours of manual back-and-forth.

Without the orchestrator, I'd need to manually prompt each phase, re-explain context each time, remember to run reviews, hope I don't forget the smoke test, and manually coordinate parallel work. The orchestrator handles all of this automatically with quality gates at every step.

Additional Context

Reference implementation: I have a working implementation in a private repo with 11 agent definitions — happy to share access with Anthropic team members on request.

Agent definitions in my implementation:

• orchestrator.md — Central coordinator (~700 lines of battle-tested orchestration logic)
• spec-analyst.md — Requirements validation
• designer.md — Design spec generation
• planner.md — Task breakdown with parallel grouping
• developer.md — Implementation agent
• reviewer-functional.md, reviewer-security.md, reviewer-standards.md, reviewer-cost.md — Specialized reviewers
• tester.md — Test writing and execution
• skills-analyst.md — Post-mortem pattern extraction

Production usage: Hundreds of commits and 70+ PRs driven through this orchestration system over several months of active development.

Similar concepts in other ecosystems: GitHub's Squad (coordinated agents in repos), Composio's agent-orchestrator, Microsoft's agent-framework — but none are built into the AI coding tool itself, which is the key differentiator Claude Code could offer.

I'm happy to collaborate with the Anthropic team on generalizing this into a project-agnostic built-in feature. The core orchestration patterns (phase gates, parallel delegation, review loops, smoke tests) are universal — only the specialist prompts need project-specific customization.