/spec-workflow-orchestrator

name: spec-workflow-orchestrator
description: Orchestrate comprehensive planning phase from ideation to development-ready specifications using 3 specialized agents (Full workflow documentation at docs/workflows/planning-workflow.md)
allowed-tools: Task, Read, Glob, TodoWrite, Write, Edit
version: 1.0.0

Spec Workflow Orchestrator

Table of Contents

1. [Purpose](#purpose) 2. [When to Use](#when-to-use) 3. [Orchestration Workflow](#orchestration-workflow)

• [Planning Phase](#planning-phase-spec-analyst--spec-architect--spec-planner)
• [Progress Tracking During Workflow](#progress-tracking-during-workflow)

4. [Agent Roles](#agent-roles) 5. [Quality Gates](#quality-gates)

• [Planning Gate (85% Threshold)](#planning-gate-85-threshold)
• [Feedback Loop Process](#feedback-loop-process)
• [Iteration Limit Enforcement](#iteration-limit-enforcement)

6. [File Organization](#file-organization) 7. [Best Practices](#best-practices)

• [Project Coordination Principles](#project-coordination-principles-battle-tested)
• [Process Improvement Guidelines](#process-improvement-guidelines-battle-tested)
• [Success Factors](#success-factors-battle-tested)
• [Planning Workflow Optimization](#planning-workflow-optimization)
• [Common Planning Pitfalls](#common-planning-pitfalls-and-how-to-avoid)
• [Success Factors](#success-factors)

8. [Examples](#examples)

• [Template: Web Application Planning](#template-web-application-planning-one-example-domain)
• [Example Walkthrough: Task Management Application](#example-walkthrough-task-management-application)

---

Purpose

Transform ideas into development-ready specifications through: 1. Comprehensive planning with requirement analysis and architecture design 2. Quality-gated iterative refinement of specifications 3. Complete handoff documentation for development teams 4. Orchestration across planning phase with 4 specialized agents

When to Use

Auto-invoke when user requests:

• **Planning**: "Plan [application]", "Design [system]", "Spec out [feature]", "Create requirements for [service]"
• **Architecture**: "Architecture for [project]", "Technical design for [application]", "Design specifications"
• **Requirements**: "Requirements for [project]", "Analyze requirements", "User stories for [feature]"
• **Pre-Development**: "Ready for development", "Spec-based planning", "Development specifications"

Do NOT invoke for:

• Actual code implementation (this skill stops at planning)
• Quick prototypes or experiments
• Single-file scripts
• Tasks that need immediate coding

Orchestration Workflow

Planning Phase (spec-analyst → spec-architect → spec-planner)

**Scope**: Complete planning and analysis phase (ideation → development-ready specifications)

**Key Activities** (from battle-tested Phase 1):

• Requirements gathering and analysis
• System architecture design
• Task breakdown and estimation
• Risk assessment and mitigation planning

**Quality Gates**:

• Requirements completeness and clarity (>85%)
• Architecture feasibility validation
• Task breakdown granularity check
• Risk mitigation coverage

The orchestrator manages sequential execution of three specialized agents with quality gate validation.

---

**Step 1: Query Analysis**

Parse user's planning request and validate suitability:

• Identify project scope, constraints, and stakeholders
• Confirm request is suitable for planning workflow (not immediate coding)
• Determine if sufficient information provided (or elicit more details)
• Output: Planning scope definition ready for spec-analyst

---

**Step 1.5: Project Naming & Existing Project Detection**

**Part A: Determine Project Slug**

Determine project directory name for organizing deliverables:

• Derive project slug from user request (e.g., "Session Log Viewer" → "session-log-viewer")
• Or ask user: "What should we call this project? (for organizing planning files)"

**Example Project Slugs**:

• "Build a task manager" → `task-manager`
• "Session log viewer web app" → `session-log-viewer`
• "E-commerce product catalog" → `ecommerce-product-catalog`

**Part B: Check for Existing Project**

**Step B1: Check if project exists**

Use Bash tool to check if project directory exists:

if [ -d "docs/projects/{project-slug}" ]; then
  echo "existing"
else
  echo "new"
fi

**If NEW PROJECT** (no directory exists):

# Create fresh directory structure
mkdir -p "docs/projects/{project-slug}/planning"
mkdir -p "docs/projects/{project-slug}/adrs"
echo "Fresh directories created"

Then use workflow_state.sh to save state:

.claude/utils/workflow_state.sh set "{project-slug}" "fresh" ""

Proceed to Step 2 with fresh planning mode.

---

**If EXISTING PROJECT** (directory exists):

**Step B2: Ask user for choice**

Use AskUserQuestion tool to ask:

{
  "questions": [{
    "question": "Project '{project-slug}' already has planning specifications. How would you like to proceed?",
    "header": "Refine Specs",
    "multiSelect": false,
    "options": [
      {
        "label": "Refine existing specs",
        "description": "Agents will read current files and improve them iteratively"
      },
      {
        "label": "Archive + fresh start",
        "description": "Move existing specs to .archive/{timestamp}/ and create new specs from scratch"
      },
      {
        "label": "Create new version",
        "description": "Create {project-slug}-v2/ directory for new planning iteration"
      },
      {
        "label": "Cancel",
        "description": "Stop the workflow without making changes"
      }
    ]
  }]
}

**Step B3: Handle user choice**

Store user's answer from AskUserQuestion response in variable `USER_CHOICE`.

**If USER_CHOICE = "Refine existing specs"**:

1. Save state as refinement mode:

# Capture user's additional requirements from conversation context
USER_INPUT="[Extract new requirements from user's latest messages]"

# Save to state file
.c