Spec Orchestrator

Coordinates the full lifecycle of specification development: writing, multi-agent review, revision, and approval. Simulates diverse team perspectives during review and iterates until the spec is approved or escalated to the user.

Arguments

• topic-or-spec (positional): A topic to write a spec for, or path to existing spec
• --skip-review: Write spec without review cycle (just invoke spec-writer)
• --reviewers=<p1,p2>: Use only specific personas (comma-separated names)
• --max-iterations=<n>: Override max revision cycles
• --require-approval: Always require human approval (never auto-approve)

Configuration

Check for .claude/spec-workflow/config.yaml:

review:
  maxIterations: 3              # Cycles before escalating to human
  autoApproveThreshold: 0.8     # Consensus for auto-approval (0.0-1.0)
  selection:
    strategy: "auto"            # "auto" | "all" | "explicit"
    minimum: 2                  # Minimum reviewers
    maximum: 4                  # Maximum reviewers

Philosophy Injection

If .claude/spec-workflow/philosophy/review-criteria.md exists, inject it into all reviewer prompts to guide their focus.

Custom Personas

Custom personas are loaded from two sources (user personas have priority):

1. User personas: .claude/spec-workflow/personas/ in the project directory
2. Built-in personas: resources/spec-workflow/personas/ bundled with feature-marker

For each .md file in these directories:

• Parse frontmatter for name, triggers, and applies_to
• Make available as a reviewer persona

Priority: user personas always override built-in personas with the same name.

Auto-trigger by domain

After classifying the spec (type, risk, scope), scan the feature topic, title, and context.md keywords against each persona's triggers list (case-insensitive):

Feature context keywords: [firestore, collection, query, trainer, student]
Firebase Cost Reviewer triggers: [firestore, collection, query, listener]
  → 3/4 keywords matched → AUTO-ACTIVATE this persona

API Security Reviewer triggers: [api, route, endpoint, auth, token]
  → 0/5 matched → not activated for this feature

Activation threshold: ≥2 trigger keywords matched → activate persona.

When auto-activating personas, announce them:

🎭 Auto-activated personas based on feature context:
  • Firebase Cost Reviewer (matched: firestore, collection, query)
  • Performance Reviewer (matched: list, pagination)

Persona file format

---
name: Firebase Cost Reviewer
triggers: [firestore, firebase, collection, query, realtime, listener, snapshot]
applies_to: [large-feature, infrastructure, api-change]
---

You review specs for Firebase cost implications.

### Your perspective
[description of the persona's focus and values]

### What you look for
[specific things this persona checks]

### When to pass
"[LGTM phrase for this persona]"

Otherwise, use built-in personas from resources/spec-workflow/personas/.

Modes

1. Full loop: Write spec → review → revise → re-review until approved
2. Review only: Review an existing spec and provide feedback

Flow

Input (idea or spec)
     │
     ▼
┌─────────────────────┐
│ B: Is spec written? │
└─────────────────────┘
     │
     ├─No──► Invoke spec-writer (autonomous mode)
     │              │
     │              ▼
     └─Yes─► C: Does spec need agent review?
                   │
                   ├─No (trivial)──► Human review
                   │
                   └─Yes──► Parallel agent review
                                  │
                                  ▼
                           D: Evaluate feedback
                                  │
                   ┌──────────────┼──────────────┐
                   ▼              ▼              ▼
               Approved      Iterate         Escalate
                   │              │              │
                   ▼              │              ▼
                 EXIT             │        Human review
                                  │              │
                                  └──────────────┘

State

Track across iterations:

{
  iteration: 0,
  maxIterations: 3,           // From config or argument
  status: "drafting" | "awaiting-review" | "in-review" | "approved",
  spec: null,
  reviewPath: "agent" | "human" | null,
  originalRequest: string,
  history: [{ iteration, feedback, reviewer }],
  escalationCount: 0
}

Coordinator Decisions

B: Is spec written?

• No → Invoke spec-writer with { mode: "autonomous", request: originalRequest }
• Yes → Evaluate if agent review needed (C)

C: Does spec need agent review?

Classify the spec first, then:

D: Does feedback need iteration?

Evaluate feedback and return one of:

Approved → Exit

• No "must address" items, OR
• All reviewers LGTM, OR
• Consensus meets autoApproveThreshold

Iterate → Back to spec-writer

• Has "must address" items that can be addressed
• Under maxIterations

Escalate → Human Review

• Max iterations reached
• Reviewers fundamentally disagree
• Spec writer disputes feedback
• Feedback requires judgment beyond spec scope

Classification

Analyze the spec and determine:

Type (select one):

• bug-fix — Fixing incorrect behavior
• small-feature — Additive, limited scope
• large-feature — Significant new capability
• refactor — Restructuring without behavior change
• infrastructure — Build, deploy, observability
• api-change — Public interface modifications

Risk (select one):

• low — Easily reversible, limited blast radius
• medium — Some complexity, moderate impact
• high — Hard to undo, broad impact, security-sensitive

Scope — Based on surface area and complexity:

Complexity signals: new abstractions, data model changes, state management, concurrency, new dependencies.

Agent Review

When the spec needs agent review, invoke reviewer personas in parallel.

Select Reviewers

Based on classification, determine review depth:

Standard review — select based on type:

Deep review — all available reviewers

If --reviewers argument provided, use only those personas.

Execute in Parallel

Reviewers are independent—run as parallel sub-agents using the Task tool:

FOR EACH reviewer IN selectedReviewers:
  SPAWN_SUBAGENT(
    prompt: [Persona prompt] + [Review criteria philosophy] + [Spec content],
    description: "{reviewer.name} reviewing spec"
  )

AWAIT_ALL(tasks)
RETURN SYNTHESIZE(results)

Reviewer Prompt Template

[Persona prompt from personas file]

---

## Review Criteria

[Content from philosophy/review-criteria.md if present]

---

## Spec to Review

**Classification**: {type} | {risk} risk | {scope} scope

{spec content}

---

Provide your review. If you have no substantive feedback, respond only with:
"No concerns from a {perspective} perspective—LGTM."

Synthesize Feedback

After all reviews, produce:

## Review Summary

[2-3 sentence overview]

### Must Address
- [Issue] — raised by [Reviewer]

### Should Consider
- [Suggestion] — raised by [Reviewer]

### Minor/Optional
- [Item] — raised by [Reviewer]

### Points of Disagreement
- [Topic]: [Reviewer A] says X, [Reviewer B] says Y

Human Review

Standard Review

For simple specs that don't need agent review:

## Spec Ready for Review

[spec content]

---

Please review. When done, provide:
1. Any issues that must be addressed (blocking)
2. Suggestions to consider (non-blocking)
3. Your verdict: **approve** or **request changes**

Escalation Review

When escalated from agent review:

## Spec Escalated for Human Review

### Escalation Reason
[max-iterations | reviewer-disagreement | spec-writer-dispute | requires-judgment]

[Details]

### Iteration History
[Summary of each round]

---

### Current Spec
[spec content]

---

Please provide direction:
1. **Approve** if acceptable
2. **Feedback** for another iteration
3. **Redirect** if approach is fundamentally wrong

Spec Writer Integration

This skill invokes spec-writer directly. See references/spec-writer-integration.md for the contract.

Autonomous draft: { mode: "autonomous", request: string }

Revision: { mode: "revision", currentSpec: string, feedback: object, iteration: number }

Output

Approved Spec

## Spec Approved

**Review path**: Agent | Human | Mixed
**Review depth**: Light | Standard | Deep
**Iterations**: N

---

[Final spec content]

---

## Review Discussion

### Key Feedback Addressed
[Issues raised and how resolved, with reviewer attribution]

### Tradeoffs Considered
[Alternatives discussed, why rejected]

### Dissenting Perspectives
[Concerns acknowledged but not fully addressed]

---

### Review History
[What changed each iteration]

### Escalations
[If any, what was escalated and how resolved]

Configuration Options

Built-in Personas

When no custom personas are configured, use:

• Pragmatic Architect — System design, integration, maintainability
• Paranoid Engineer — Failure modes, edge cases, security
• Operator — Observability, deployment, incident response
• Simplifier — YAGNI, minimal scope, clarity
• User Advocate — DX/UX, documentation, mental models
• Product Strategist — Customer value, success metrics, opportunity cost

See references/personas.md for full prompts.

Error Handling

Spec writer fails: Retry once with clarified prompt. If still failing, escalate to human.

Reviewer fails: Skip and continue with others. Note in synthesis.

All reviewers fail: Escalate to human review.