Claude Sub-Agent Spec Workflow System

A comprehensive AI-driven development workflow system built on Claude Code's Sub-Agents feature. This system transforms project ideas into production-ready code through specialized AI agents working in coordinated phases.

Table of Contents

• Overview
• System Architecture
• Installation
• Quick Start
• Slash Command Usage
• How It Works
• Agent Reference
• Usage Examples
• Quality Gates
• Best Practices
• Advanced Usage
• Troubleshooting

Overview

The Spec Workflow System leverages Claude Code's Sub-Agents capability to create a multi-agent development pipeline. Each agent is a specialized expert that handles specific aspects of the software development lifecycle, from requirements analysis to final validation.

Key Features

• Automated Workflow: Complete development pipeline from idea to production code
• Specialized Expertise: Each agent focuses on their domain of expertise
• Quality Gates: Automated checkpoints ensure quality standards
• Flexible Integration: Works with existing specialized agents
• Comprehensive Documentation: Every phase produces detailed artifacts

Benefits

• 10x faster development from concept to code
• Consistent quality through automated validation
• Comprehensive documentation generated automatically
• Reduced errors through systematic processes
• Better collaboration through clear workflows

System Architecture

graph TD
    A[Project Idea] --> B[spec-orchestrator]
    B --> C[Planning Phase]
    C --> D[spec-analyst<br/>Requirements]
    D --> E[spec-architect<br/>System Design]
    E --> F[spec-planner<br/>Task Breakdown]
    
    F --> G{Quality Gate 1}
    G -->|Pass| H[Development Phase]
    G -->|Fail| D
    
    H --> I[spec-developer<br/>Implementation]
    I --> J[spec-tester<br/>Testing]
    
    J --> K{Quality Gate 2}
    K -->|Pass| L[Validation Phase]
    K -->|Fail| I
    
    L --> M[spec-reviewer<br/>Code Review]
    M --> N[spec-validator<br/>Final Check]
    
    N --> O{Quality Gate 3}
    O -->|Pass| P[Production Ready]
    O -->|Fail| Q[Feedback Loop]
    
    style B fill:#1a73e8,color:#fff
    style G fill:#f9ab00,color:#fff
    style K fill:#f9ab00,color:#fff
    style O fill:#f9ab00,color:#fff
    style P fill:#34a853,color:#fff

Installation

Prerequisites

• Claude Code (latest version)
• Project directory initialized
• Basic understanding of AI-assisted development

Setup Steps

1. Download the agents

   # Option 1: Clone the repository
   git clone https://github.com/zhsama/claude-sub-agent.git
   cd claude-sub-agent
   
   # Option 2: Download specific agents you need
   # Individual agent files are available in the agents/ directory
   

2. Copy agents and slash command to your project's Claude Code directory

   # Create .claude directory structure in your project
   mkdir -p .claude/agents .claude/commands
   
   # Copy all agents from categorized directories
   cp -r agents/*/*.md .claude/agents/
   
   # Copy slash command
   cp commands/agent-workflow.md .claude/commands/
   

3. Add RULES to CLAUDE.md

   ## Project Documentation Conventions (Important)
   
   **Documentation Files:** All new documentation or task files must be saved under the `docs/` folder in this repository.For example:
   
   - **Tasks & TODOs**: Save in `docs/{YYYY_MM_DD}/tasks/` (e.g., `docs/t2025_08_08/asks/ReleaseTodo.md` for a release checklist).
   - **Requirements/Specs**: Save in `docs/{YYYY_MM_DD}/specs/` (e.g., `docs/2025_08_08/specs/AuthModuleRequirements.md`).
   - **Design Docs**: Save in `docs/{YYYY_MM_DD}/design/` (e.g., `docs/2025_08_08/design/ArchitectureOverview.md`).
   - **Code Files:** Follow the project structure (place new code in the appropriate src/module folder as discussed).
   - **Tests:** Put new test files under the `tests/` directory, mirroring the code structure.
   
   > **Important:** When creating a new file, ensure the directory exists or create it. Never default to the root directory for these files.
   

4. Verify installation

   Repository Structure:

   claude-sub-agent/
   ├── agents/
   │   ├── spec-agents/         # Core workflow agents
   │   │   ├── spec-analyst.md
   │   │   ├── spec-architect.md
   │   │   ├── spec-developer.md
   │   │   ├── spec-orchestrator.md
   │   │   ├── spec-planner.md
   │   │   ├── spec-reviewer.md
   │   │   ├── spec-tester.md
   │   │   └── spec-validator.md
   │   ├── backend/             # Backend specialists
   │   │   └── senior-backend-architect.md
   │   ├── frontend/            # Frontend specialists
   │   │   └── senior-frontend-architect.md
   │   ├── ui-ux/              # Design specialists
   │   │   └── ui-ux-master.md
   │   └── utility/             # Utility agents
   │       └── refactor-agent.md
   └── commands/
       └── agent-workflow.md    # Slash command
   ├── CLAUDE.md
   

   Your project structure after installation:

   your-project/
   ├── .claude/
   │   ├── commands/
   │   │   └── agent-workflow.md   # Slash command
   │   └── agents/
   │       ├── spec-analyst.md
   │       ├── spec-architect.md
   │       ├── spec-developer.md
   │       ├── spec-orchestrator.md
   │       ├── spec-planner.md
   │       ├── spec-reviewer.md
   │       ├── spec-tester.md
   │       ├── spec-validator.md
   │       ├── senior-backend-architect.md
   │       ├── senior-frontend-architect.md
   │       ├── ui-ux-master.md
   │       └── refactor-agent.md
   ├── CLAUDE.md
   └── ... (your project files)
   

Quick Start

Basic Usage

# Start a new project workflow
Ask Claude: "Use the spec-orchestrator agent to create a todo list web application"

# The orchestrator will automatically:
# 1. Analyze requirements
# 2. Design architecture
# 3. Plan tasks
# 4. Implement code
# 5. Write tests
# 6. Review and validate

Simple Example

You: Use spec-orchestrator to create a personal blog platform

Claude (spec-orchestrator): Starting workflow for personal blog platform...

[Planning Phase - 45 minutes]
✓ Requirements analyzed
✓ Architecture designed
✓ Tasks planned
✓ Quality Gate 1: PASSED (96/100)

[Development Phase - 2 hours]
✓ 15 tasks implemented
✓ Tests written
✓ Quality Gate 2: PASSED (88/100)

[Validation Phase - 30 minutes]
✓ Code reviewed
✓ Final validation complete
✓ Quality Gate 3: PASSED (91/100)

Project complete! Generated artifacts:
- requirements.md
- architecture.md
- Source code (15 files)
- Test suites (85% coverage)
- Documentation

Slash Command Usage

For the quickest way to start a complete workflow, use our custom slash command:

Basic Usage

/agent-workflow "Create a task management web application with user authentication and real-time updates"

Advanced Usage

# High-quality enterprise project
/agent-workflow "Develop a CRM system with customer management and analytics" --quality=95

# Quick prototype development  
/agent-workflow "Simple personal blog website" --quality=75 --skip-agent=spec-tester

# From existing requirements
/agent-workflow "Mobile app based on existing requirements" --skip-agent=spec-analyst

# Specific phases only
/agent-workflow "Microservices e-commerce platform" --phase=planning

Command Options

• --quality=[75-95]: Set quality gate threshold
• --skip-agent=[agent-name]: Skip specific agents
• --phase=[planning|development|validation|all]: Run specific phases
• --output-dir=[path]: Specify output directory
• --language=[zh|en]: Documentation language

📖 For complete slash command documentation, see commands/agent-workflow.md

How It Works

1. Claude Code Sub-Agents Integration

According to Claude Code's documentation, sub-agents work by:

• Operating in isolated context windows
• Preventing pollution of the main conversation
• Allowing specialized, focused interactions
• Being automatically selected based on task context

Our system leverages these features by creating specialized agents for each development phase.

2. Workflow Phases

Planning Phase

1. spec-analyst: Analyzes requirements and creates user stories
2. spec-architect: Designs system architecture
3. spec-planner: Breaks down work into tasks
4. Quality Gate 1: Validates planning completeness

Development Phase

1. spec-developer: Implements code based on tasks
2. spec-tester: Writes comprehensive tests
3. Quality Gate 2: Validates code quality

Validation Phase

1. spec-reviewer: Reviews code for best practices
2. spec-validator: Final production readiness check
3. Quality Gate 3: Ensures deployment readiness

3. Agent Communication

Agents communicate through structured artifacts:

• Each agent produces specific documents
• Next agent uses previous outputs as input
• Orchestrator manages the flow
• Quality gates ensure consistency

Agent Reference

Agent Classification System

Our agents are organized into specialized categories for better organization and domain expertise:

• spec-agents/: Core workflow orchestration agents
• backend/: Backend system specialists
• frontend/: Frontend development specialists
• ui-ux/: User experience and design specialists
• utility/: General-purpose utility agents

Core Workflow Agents (spec-agents/)

| Agent | Purpose | Inputs | Outputs | |-------|---------|--------|---------| | spec-orchestrator | Workflow coordination | Project description | Status reports, routing | | spec-analyst | Requirements analysis | User description | requirements.md, user-stories.md | | spec-architect | System design | Requireme