spec-workflow-orchestrator

Spec Workflow Orchestrator

Table of Contents

1. Purpose
2. When to Use
3. Orchestration Workflow
   • Planning Phase
   • Progress Tracking During Workflow
4. Agent Roles
5. Quality Gates
   • Planning Gate (85% Threshold)
   • Feedback Loop Process
   • Iteration Limit Enforcement
6. File Organization
7. Best Practices
   • Project Coordination Principles
   • Process Improvement Guidelines
   • Success Factors
   • Planning Workflow Optimization
   • Common Planning Pitfalls
   • Success Factors
8. Examples
   • Template: Web Application Planning
   • 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": [