spec-workflow-orchestrator

Spec Workflow Orchestrator

Table of Contents

1. [Purpose](#purpose)
2. [When to Use](#when-to-use)
3. [Orchestration Workflow](#orchestration-workflow)
4. [Planning Phase](#planning-phase-spec-analyst--spec-architect--spec-planner)
5. [Progress Tracking During Workflow](#progress-tracking-during-workflow)
6. [Agent Roles](#agent-roles)
7. [Quality Gates](#quality-gates)
8. [Planning Gate (85% Threshold)](#planning-gate-85-threshold)
9. [Feedback Loop Process](#feedback-loop-process)
10. [Iteration Limit Enforcement](#iteration-limit-enforcement)
11. [File Organization](#file-organization)
12. [Best Practices](#best-practices)
13. [Project Coordination Principles](#project-coordination-principles-battle-tested)
14. [Process Improvement Guidelines](#process-improvement-guidelines-battle-tested)
15. [Success Factors](#success-factors-battle-tested)
16. [Planning Workflow Optimization](#planning-workflow-optimization)
17. [Common Planning Pitfalls](#common-planning-pitfalls-and-how-to-avoid)
18. [Success Factors](#success-factors)
19. [Examples](#examples)
20. [Template: Web Application Planning](#template-web-application-planning-one-example-domain)
21. [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
.claude/utils/workflow_state.sh set "{project-slug}" "refinement" "$USER_INPUT"

1. Set WORKFLOW_MODE = "refinement"
2. Proceed to Step 2 with refinement mode prompts

If USER_CHOICE = "Archive + fresh start":

1. Run archive utility:

# Archive existing specs with timestamp
.claude/utils/archive_project.sh "{project-slug}"

# This script:
# - Creates .archive/{timestamp}/ directory
# - Copies planning/ and adrs/ to archive
# - Verifies integrity
# - Deletes originals
# - Creates fresh planning/ and adrs/ directories
# - Returns exit code 0 on success, 1 on failure

1. Check exit code and handle errors:

if [ $? -eq 0 ]; then
  echo "Archive successful, proceeding with fresh planning"
else
  echo "Archive failed, aborting workflow"
  exit 1
fi

1. Save state as fresh mode:

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

1. Set WORKFLOW_MODE = "fresh"
2. Proceed to Step 2 with fresh planning mode prompts

If USER_CHOICE = "Create new version":

1. Detect next available version:

# Run version detection utility
NEW_SLUG=$(.claude/utils/detect_next_version.sh "{project-slug}")

# This returns: "{project-slug}-v2" or "{project-slug}-v3" etc.
# Exit code 0 on success, 1 if version limit reached (v99)

1. Handle version detection result:

if [ $? -eq 0 ]; then
  echo "Next version: $NEW_SLUG"
  PROJECT_SLUG="$NEW_SLUG"
else
  echo "ERROR: Version limit reached (v2-v99 all exist)"
  echo "Consider using 'Archive + fresh start' instead"
  exit 1
fi

1. Create new versioned directory:

mkdir -p "docs/projects/$PROJECT_SLUG/planning"
mkdir -p "docs/projects/$PROJECT_SLUG/adrs"

1. Save state with new slug:

.claude/utils/workflow_state.sh set "$PROJECT_SLUG" "fresh" ""

1. Update PROJECT_SLUG variable to new version slug
2. Set WORKFLOW_MODE = "fresh"
3. Proceed to Step 2 with fresh planning mode prompts

If USER_CHOICE = "Cancel":

1. Clear any partial state:

.claude/utils/workflow_state.sh clear

1. Inform user:

Workflow cancelled. No changes made to existing project specs.

1. Exit workflow gracefully (return to user)

Output:

• PROJECT_SLUG (final slug, may be versioned)
• WORKFLOW_MODE ("fresh" or "refinement")
• `USER_INPU