Spec Workflow Orchestrator

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)

1. [Agent Roles](#agent-roles)
2. [Quality Gates](#quality-gates)

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

1. [File Organization](#file-organization)
2. [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)

1. [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
.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_INPUT (additional requirements if refinement mode, empty string otherwise)

---

Step 1.6: Placeholder Substitution

Before spawning agents, substitute placeholders in prompt templates with actual values:

Required Substitutions:

• {project-slug} → Actual project slug (e.g., "task-tracker-pwa" or "task-tracker-pwa-v2")
• [PROJECT_NAME] → User-friendly project name extracted from original request (e.g., "Task Tracker PWA")
• [ADDITIONAL_REQUIREMENTS_FROM_USER] → (Refinement mode only) User's new requirements from conversation
• [CHANGES_FROM_REQUIREMENTS] → (Refinement mode only) Summary of requirement changes for architect

How to Extract Values:

1. PROJECT_NAME: Parse from original user request

• Example: "Build a task tracker PWA" → PROJECT_NAME = "Task Tracker PWA"
• Example: "Plan an e-commerce catalog" → PROJECT_NAME = "E-Commerce Catalog"

1. USER_INPUT for Refinement (saved in state file):

# Retrieve from state file
USER_INPUT=$(.claude/utils/workflow_state.sh get "user_input")

If empty (user just said "refine specs"), use generic guidance:

USER_INPUT="Review all sections for completeness, update metrics to be measurable, enhance clarity"

1. Perform substitution before spawning each agent:

# Pseudocode for substitution
prompt_template = "Analyze requirements for [PROJECT_NAME]..."
actual_prompt = prompt_template
actual_prompt = actual_prompt.replace("{project-slug}", PROJECT_SLUG)
actual_prompt = actual_prompt.replace("[PROJECT_NAME]", PROJECT_NAME)
actual_prompt = actual_prompt.replace("[ADDITIONAL_REQUIREMENTS_FROM_USER]", USER_INPUT)

Example Substitution:

Before:

prompt: "Refine requirements for [PROJECT_NAME].
IMPORTANT: Read existing file at docs/projects/{project-slug}/planning/requirements.md first.
4. Enhance based on new user input: [ADDITIONAL_REQUIREMENTS_FROM_USER]"

After (for task-tracker-pwa, user wants "add offline support"):

prompt: "Refine requirements for Task Tracker PWA.
IMPORTANT: Read existing file at docs/projects/task-tracker-pwa/planning/requirements.md first.
4. Enhance based on new user input: Add offline support with service workers and local storage"

---

Step 2: Spawn spec-analyst Agent (Requirements Gathering and Analysis)

Use Task tool to spawn requirements analysis agent to perform Phase 1 Activity 1:

IMPORTANT: Apply placeholder substitution from Step 1.6 before spawning.

For Fresh Planning Mode:

subagent_type: "spec-analyst"
description: "Analyze requirements for {PROJECT_NAME}"
prompt: "Analyze requirements for {PROJECT_NAME}. Generate comprehensive requirements.md with:
- Executive Summary (project goals and scope)
- Functional Requirements (prioritized with IDs: FR1, FR2, etc.)
- Non-Functional Requirements (performance, security, scalability with metrics)
- User Stories with Acceptance Criteria (measurable criteria for each story)
- Stakeholder Analysis (identify all stakeholder groups and their needs)
- Assumptions and Constraints (technical, business, timeline)
- Success Metrics (how to measure project success)

Save to: docs/projects/{project-slug}/planning/requirements.md"

For Refinement Mode:

subagent_type: "spec-analyst"
description: "Refine requirements for {PROJECT_NAME}"
prompt: "Refine requirements for {PROJECT_NAME}.

IMPORTANT: Read existing file at docs/projects/{project-slug}/planning/requirements.md first.

Your task:
1. Analyze existing requirements document
2. Identify gaps, weak sections, or outdated content
3. Preserve well-written sections (don't rewrite what's already good)
4. Enhance based on new user input: {USER_INPUT}
5. Add missing sections or details
6. Update metrics to be more measurable
7. Ensure acceptance criteria are concrete and testable

Maintain document structure but improve quality and completeness.

Save updated version to: docs/projects/{project-slug}/planning/requirements.md"

Note: Replace {USER_INPUT} with actual value from state file or generic guidance.

Wait for completion → Read output: docs/projects/{project-slug}/planning/requirements.md

Expected Output: Comprehensive requirements document (typically 800-1,500 lines)

---

Step 3: Spawn spec-architect Agent (System Architecture Design)

Use Task tool to spawn architecture design agent to perform Phase 1 Activity 2:

For Fresh Planning Mode:

subagent_type: "spec-architect"
description: "Design system architecture for {PROJECT_NAME}"
prompt: "Design system architecture for {PROJECT_NAME} based on requirements at docs/projects/{project-slug}/planning/requirements.md.

Generate:
1. architecture.md with:
   - Executive Summary
   - Technology Stack (with justification for each choice)
   - System Components (with interaction diagrams and relationships)
   - Interface Specifications (APIs, CLIs, SDKs, data contracts as appropriate)
   - Security Considerations (relevant security requirements and design patterns)
   - Performance & Scalability (optimization strategies and scaling approach)
   - Deployment Architecture (hosting, distribution, installation approach)

2. ADRs with Architecture Decision Records for key decisions:
   - ADR format: Status, Context, Decision, Rationale, Consequences, Alternatives
   - Create separate ADR for each major architectural decision
   - Examples: technology choices, data storage strategy, communication patterns, security model

Save to: docs/projects/{project-slug}/planning/architecture.md, docs/projects/{project-slug}/adrs/*.md"

For Refinement Mode:

subagent_type: "spec-architect"
description: "Refine system architecture for {PROJECT_NAME}"
prompt: "Refine system architecture for {PROJECT_NAME}.

IMPORTANT: Read existing files first:
- docs/projects/{project-slug}/planning/architecture.md
- docs/projects/{project-slug}/adrs/*.md
- Updated requirements at docs/projects/{project-slug}/planning/requirements.md

Your task:
1. Review existing architecture and ADRs
2. Identify architectural gaps or areas needing improvement
3. Check if technology stack decisions still make sense
4. Enhance based on new/refined requirements: {USER_INPUT}
5. Add missing architectural components or considerations
6. Update existing ADRs if decisions have changed (mark old as 'Superseded', create new ADRs)
7. Preserve well-designed sections

Maintain consistency with existing ADRs but improve where needed.

Save to: docs/projects/{project-slug}/planning/architecture.md, docs/projects/{project-slug}/adrs/*.md"

Note: Use same {USER_INPUT} value from analyst step.

Wait for completion → Read outputs: docs/projects/{project-slug}/planning/architecture.md, docs/projects/{project-slug}/adrs/*.md

Expected Output: Architecture document (600-1,000 lines) + 3-5 ADRs (150-250 lines each)

---

Step 4: Spawn spec-planner Agent (Task Breakdown and Risk Assessment)

Use Task tool to spawn implementation planning agent to perform Phase 1 Activities 3 & 4:

For Fresh Planning Mode:

subagent_type: "spec-planner"
description: "Create implementation plan for {PROJECT_NAME}"
prompt: "Create implementation plan for {PROJECT_NAME} based on:
- Requirements: docs/projects/{project-slug}/planning/requirements.md
- Architecture: docs/projects/{project-slug}/planning/architecture.md

Generate tasks.md with:
1. Overview (total tasks, estimated effort, critical path, parallel streams)
2. Task Breakdown by Phase:
   - Each task with: ID, complexity, effort estimate, dependencies, description
   - Acceptance criteria for each task (concrete, measurable)
   - Tasks should be atomic and implementable (1-8 hours each)
3. Risk Assessment:
   - Technical risks with severity, probability, impact
   - Mitigation strategies for each risk
4. Testing Strategy:
   - Unit test coverage targets
   - Integration test scenarios
   - End-to-end test requirements

Save to: docs/projects/{project-slug}/planning/tasks.md"

**For Refinement Mo

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahmedibrahim085
• Source: ahmedibrahim085/Claude-Multi-Agent-Research-System-Skill
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.