Add comprehensive documentation and multi-agent workflow system

- Add English and Chinese README.md with complete project documentation - Add agents/ directory with 7 specialized sub-agent configurations - Add spec-execution.md and spec-workflow.md commands - Add .gitignore for Claude Code project structure - Document two primary usage patterns: sub-agent workflows and custom commands - Include architecture overview, quick start guide, and real-world examples - Establish 95% quality gate automation with iterative improvement loops 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-05 02:30:26 +08:00 · 2025-07-28 10:26:19 +08:00
parent d48894ad21
commit e0d5b0955d
12 changed files with 1356 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,3 @@
+CLAUDE.md
+
+.claude/
--- a/README-zh.md
+++ b/README-zh.md
@@ -0,0 +1,466 @@
+# Claude Code 多智能体工作流系统
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code)
+
+> 将开发流程从手动命令链升级为自动化专家团队，95%质量保证。
+
+## 🚀 从手工作坊到自动化工厂
+
+**传统方式**: 手动命令链，需要持续监督
+```bash
+/ask → /code → /test → /review → /optimize
+# 1-2小时手动操作，上下文污染，质量不确定
+```
+
+**现在**: 一键自动化专家工作流
+```bash
+/spec-workflow "实现JWT用户认证系统"
+# 30分钟自动执行，95%质量门控，零人工干预
+```
+
+## 🎯 核心价值主张
+
+本仓库提供了一个**Claude Code元框架**，实现：
+
+- **🤖 多智能体协调**: 专业AI团队并行工作
+- **⚡ 质量门控自动化**: 95%阈值自动优化循环
+- **🔄 工作流自动化**: 从需求到生产就绪代码
+- **📊 上下文隔离**: 每个智能体保持专注专业性，无污染
+
+## 📋 两种主要使用模式
+
+### 1. 🏭 Sub-Agent 工作流（自动化专家团队）
+
+**架构**: 并行专家协调与质量门控
+```
+spec-generation → spec-executor → spec-validation → (≥95%?) → spec-testing
+     ↑                                              ↓ (<95%)
+     ←←←←←← 自动优化循环，直到质量达标 ←←←←←←
+```
+
+**使用方法**:
+```bash
+# 一条命令完成完整开发工作流
+/spec-workflow "构建用户管理系统，支持RBAC权限控制"
+
+# 高级多阶段工作流
+先使用 spec-generation，然后 spec-executor，再用 spec-validation，
+如果评分 ≥95% 则使用 spec-testing，最后用 optimize 优化
+```
+
+**质量评分体系** (总分100%):
+- 需求符合度 (30%)
+- 代码质量 (25%) 
+- 安全性 (20%)
+- 性能 (15%)
+- 测试覆盖 (10%)
+
+### 2. 🎛️ 自定义命令（手动编排）
+
+**架构**: 针对性专业技能的独立斜杠命令
+```bash
+/ask     # 技术咨询和架构指导
+/spec    # 交互式需求 → 设计 → 任务工作流  
+/code    # 功能实现，带约束条件
+/debug   # 使用UltraThink方法论的系统化问题分析
+/test    # 全面测试策略
+/review  # 多维度代码验证
+/optimize # 性能优化协调
+```
+
+**渐进式示例**:
+```bash
+# 逐步开发，手动控制每个环节
+/ask "帮我理解微服务架构需求"
+/spec "生成API网关规格说明" 
+/code "实现带限流功能的网关"
+/test "创建负载测试套件"
+/review "验证安全性和性能"
+```
+
+## 🚀 快速开始
+
+### 1. 配置设置
+
+克隆或复制配置结构:
+```bash
+# 你的项目目录
+├── commands/          # 12个专业斜杠命令
+├── agents/           # 7个专家智能体配置  
+└── CLAUDE.md         # 项目特定指导原则
+```
+
+### 2. 基本使用
+
+**完整功能开发**:
+```bash
+/spec-workflow "实现OAuth2认证，支持刷新令牌"
+```
+
+**手动开发流程**:
+```bash
+/ask "可扩展微服务的设计原则"
+/spec "OAuth2服务规格说明"
+/code "实现OAuth2，遵循安全最佳实践"
+```
+
+### 3. 预期输出
+
+**自动化工作流结果**:
+- ✅ 完整规格说明 (requirements.md, design.md, tasks.md)
+- ✅ 生产就绪代码，遵循安全最佳实践
+- ✅ 全面测试套件 (单元 + 集成 + 安全测试)
+- ✅ 95%+ 质量验证评分
+
+## 🏗️ 架构概览
+
+### 核心组件
+
+#### **Commands 目录** (`/commands/`)
+- **规格说明**: `/spec` - 交互式需求 → 设计 → 任务
+- **咨询服务**: `/ask` - 架构指导（不修改代码）
+- **实现工具**: `/code` - 带约束的功能开发
+- **质量保证**: `/test`, `/review`, `/debug`
+- **优化工具**: `/optimize`, `/refactor`
+- **运维工具**: `/deploy-check`, `/cicd`
+
+#### **Agents 目录** (`/agents/`)
+- **spec-generation**: 自动化规格说明工作流
+- **spec-executor**: 带进度跟踪的实现协调器
+- **spec-validation**: 多维度质量评分 (0-100%)
+- **spec-testing**: 全面测试策略协调
+- **code**: 直接实现的开发协调器
+- **debug**: UltraThink系统化问题分析
+- **optimize**: 性能优化协调
+
+### 多智能体协调系统
+
+**4个核心专家**:
+1. **规格生成专家** - 需求、设计、实现规划
+2. **实现执行专家** - 带任务跟踪的代码开发
+3. **质量验证专家** - 多维度评分与可执行反馈
+4. **测试协调专家** - 全面测试策略与执行
+
+**关键特性**:
+- **独立上下文**: 专家间无上下文污染
+- **质量门控**: 95%阈值自动进展判断
+- **迭代改进**: 自动优化循环
+- **可追溯性**: 完整规格 → 代码 → 测试追溯链
+
+## 📚 工作流示例
+
+### 企业用户认证系统
+
+**输入**:
+```bash
+/spec-workflow "企业JWT认证系统，支持RBAC，500并发用户，集成现有LDAP"
+```
+
+**自动化执行过程**:
+1. **第1轮** (质量: 83/100) - 基础实现
+   - 问题: JWT密钥硬编码，缺少密码复杂度验证
+   - **决策**: <95%，重新开始并改进
+
+2. **第2轮** (质量: 91/100) - 安全改进  
+   - 问题: 异常处理不完善，性能未优化
+   - **决策**: <95%，继续优化
+
+3. **第3轮** (质量: 97/100) - 生产就绪
+   - **决策**: ≥95%，进入全面测试阶段
+
+**最终交付物**:
+- 完整EARS格式需求文档
+- 安全加固的JWT实现
+- 带角色层级的RBAC
+- 带错误处理的LDAP集成
+- 全面测试套件（单元 + 集成 + 安全）
+
+### API网关开发
+
+**输入**:
+```bash
+/ask "高性能API网关的设计考虑"
+# (交互式咨询阶段)
+
+/spec "微服务API网关，支持限流和熔断器"
+# (规格生成阶段)
+
+/code "基于规格说明实现网关"
+# (实现阶段)
+```
+
+**结果**:
+- 性能模式的架构咨询
+- 带负载均衡策略的详细规格
+- 带监控的生产就绪实现
+
+## 🔧 高级使用模式
+
+### 自定义工作流组合
+
+```bash
+# 调试 → 修复 → 验证工作流
+先使用 debug 分析 [性能问题]，
+然后用 code 实现修复，
+再用 spec-validation 确保质量
+
+# 完整开发 + 优化流水线  
+先使用 spec-generation 处理 [功能]，
+然后 spec-executor 进行实现，
+再用 spec-validation 进行质量检查，
+如果评分 ≥95% 则使用 spec-testing，
+最后用 optimize 确保生产就绪
+```
+
+### 质量驱动开发
+
+```bash
+# 迭代质量改进
+先使用 spec-validation 评估 [现有代码]，
+如果评分 <95% 则用 code 基于反馈改进，
+重复直到达到质量阈值
+```
+
+## 🎯 效益与影响
+
+| 维度 | 传统Slash命令 | Sub-Agent自动工作流 |
+|------|-------------|------------------|
+| **复杂度** | 手动触发每个步骤 | 一键启动完整流水线 |
+| **质量** | 主观评估 | 95%客观评分 |
+| **上下文** | 污染，需要/clear | 隔离，无污染 |
+| **专业性** | AI角色切换 | 专注的专家 |
+| **错误处理** | 手动发现/修复 | 自动优化 |
+| **时间投入** | 1-2小时手动工作 | 30分钟自动化 |
+
+## 🔮 关键创新
+
+### 1. **专家深度 > 通才广度**
+每个智能体在独立上下文中专注各自领域专业知识，避免角色切换导致的质量下降。
+
+### 2. **智能质量门控**  
+95%客观评分，自动决策工作流进展或优化循环。
+
+### 3. **完全自动化**
+一条命令触发端到端开发工作流，最少人工干预。
+
+### 4. **持续改进**
+质量反馈驱动自动规格优化，创建智能改进循环。
+
+## 🛠️ 配置说明
+
+### 设置Sub-Agents
+
+1. **创建智能体配置**: 将智能体文件复制到Claude Code配置中
+2. **配置命令**: 设置工作流触发命令
+3. **自定义质量门控**: 根据需要调整评分阈值
+
+### 工作流定制
+
+```bash
+# 带特定质量要求的自定义工作流
+先使用 spec-generation 处理 [严格安全要求]，
+然后 spec-executor 处理 [性能约束]，
+再用 spec-validation 设置 [90%最低阈值]，
+继续优化直到达到阈值
+```
+
+## 📖 命令参考
+
+### 规格说明工作流
+- `/spec` - 交互式需求 → 设计 → 任务
+- `/spec-workflow` - 自动化端到端规格 + 实现
+
+### 开发命令  
+- `/ask` - 架构咨询（不修改代码）
+- `/code` - 带约束的功能实现
+- `/debug` - 系统化问题分析
+- `/test` - 全面测试策略
+- `/review` - 多维度代码验证
+
+### 优化命令
+- `/optimize` - 性能优化协调
+- `/refactor` - 带质量门控的代码重构
+- `/deploy-check` - 部署就绪验证
+
+## 🤝 贡献
+
+这是一个Claude Code配置框架。欢迎贡献：
+
+1. **新智能体配置**: 特定领域的专业专家
+2. **工作流模式**: 新的自动化序列  
+3. **质量指标**: 增强的评分维度
+4. **命令扩展**: 额外的开发阶段覆盖
+
+## 📄 许可证
+
+MIT许可证 - 详见[LICENSE](LICENSE)文件。
+
+## 🙋 支持
+
+- **文档**: 查看`/commands/`和`/agents/`获取详细规格
+- **问题**: 使用GitHub issues报告bug和功能请求
+- **讨论**: 分享工作流模式和定制化方案
+
+---
+
+## 🎉 开始使用
+
+准备好转换你的开发工作流了吗？从这里开始：
+
+```bash
+/spec-workflow "在这里描述你的第一个功能"
+```
+
+看着你的一行请求变成完整、经过测试、生产就绪的实现，95%质量保证。
+
+**记住**: 好的软件来自好的流程，好的流程来自专业的团队。Sub-agents让你拥有一个永不疲倦、始终专业的虚拟开发团队。
+
+*让专业的AI做专业的事 - 开发从此变得优雅而高效。*
+
+---
+
+## 🌟 实战案例
+
+### 用户管理系统开发
+
+**需求**: 构建企业内部用户管理系统，500人规模，RBAC权限控制，集成OA系统
+
+**传统方式** (1-2小时):
+```bash
+1. /ask 用户认证需求 → 手动澄清需求
+2. /code 实现认证逻辑 → 手动编写代码  
+3. /test 生成测试用例 → 手动测试
+4. /review 代码审查 → 手动修复问题
+5. /optimize 性能优化 → 手动优化
+```
+
+**Sub-Agents方式** (30分钟自动):
+```bash
+/spec-workflow "企业用户管理系统，500人规模，RBAC权限，OA系统集成"
+```
+
+**自动化执行结果**:
+- 📋 **完整规格文档**: 需求分析、架构设计、实现计划
+- 💻 **生产级代码**: JWT最佳实践、完善异常处理、性能优化
+- 🧪 **全面测试覆盖**: 单元测试、集成测试、安全测试
+- ✅ **质量保证**: 97/100评分，所有维度均达标
+
+### 微服务API网关
+
+**场景**: 高并发微服务架构，需要API网关进行流量管理
+
+**Step 1 - 需求理解**:
+```bash
+/ask "设计高性能微服务API网关，需要考虑哪些方面？"
+```
+
+AI会深入询问：
+- 预期QPS和并发量
+- 路由策略和负载均衡
+- 限流和熔断机制
+- 监控和日志需求
+
+**Step 2 - 规格生成**:
+```bash
+/spec "基于讨论，生成API网关完整规格"
+```
+
+生成内容：
+- **requirements.md** - 明确的用户故事和验收标准
+- **design.md** - 考虑高并发的架构设计
+- **tasks.md** - 详细的开发任务分解
+
+**Step 3 - 自动实现**:
+```bash
+# 基于规格的自动化实现
+先使用 spec-executor 基于规格实现代码，
+然后用 spec-validation 验证质量，
+如果评分 ≥95% 则用 spec-testing 生成测试
+```
+
+## 💡 最佳实践
+
+### 1. 需求澄清优先
+
+**不要急于/spec，先用/ask充分交流**
+
+```bash
+# 错误做法：直接开始
+/spec "用户管理系统"
+
+# 正确做法：先理解需求  
+/ask "企业用户管理系统需要考虑哪些方面？"
+# 经过3-5轮对话澄清需求后
+/spec "基于讨论，生成企业用户管理系统规格"
+```
+
+### 2. 渐进式复杂度
+
+从简单功能开始，逐步增加复杂性：
+
+```bash
+# 第一阶段：基础功能
+/spec-workflow "用户注册登录基础功能"
+
+# 第二阶段：权限管理
+/spec-workflow "在现有基础上添加RBAC权限系统"
+
+# 第三阶段：系统集成
+/spec-workflow "集成LDAP和SSO单点登录"
+```
+
+### 3. 质量优先策略
+
+利用质量门控确保每个阶段的代码质量：
+
+```bash
+# 设置更高质量要求
+先使用 spec-generation 生成规格，
+然后 spec-executor 实现，
+再用 spec-validation 验证，
+如果评分 <98% 则继续优化，
+达标后用 spec-testing 和 optimize
+```
+
+## 🔍 深度解析：为什么这样更有效？
+
+### 传统问题分析
+
+**上下文污染**: 单一AI在不同角色间切换，质量逐步下降
+```
+AI扮演产品经理 → 架构师 → 开发者 → 测试工程师 → 优化专家
+随着对话长度增加，AI的专业度和准确性下降
+```
+
+**手动管理开销**: 每个环节都需要人工判断和干预
+```
+是否需求已完整？ → 设计是否合理？ → 代码是否正确？ → 测试是否充分？
+每个决策点都可能中断，需要重新组织思路
+```
+
+### Sub-Agents解决方案
+
+**专业化隔离**: 每个专家在独立上下文中工作
+```
+规格专家(独立) + 实现专家(独立) + 质量专家(独立) + 测试专家(独立)
+专业深度最大化，角色混淆最小化
+```
+
+**自动化决策**: 基于客观指标的自动流程控制
+```
+质量评分 ≥95% → 自动进入下一阶段
+质量评分 <95% → 自动返回优化，无需人工判断
+```
+
+## 🚀 开始你的AI工厂
+
+从手工作坊升级到自动化工厂，只需要：
+
+1. **配置一次**: 设置Sub-Agents和自定义命令
+2. **使用一生**: 每个项目都能享受专业AI团队服务
+3. **持续改进**: 工作流模式不断优化，开发效率持续提升
+
+**记住**: 在AI时代，Sub-Agents让你拥有了一个永不疲倦、始终专业的虚拟开发团队。
+
+*让专业的AI做专业的事，开发从此变得优雅而高效。*
--- a/README.md
+++ b/README.md
@@ -0,0 +1,319 @@
+# Claude Code Multi-Agent Workflow System
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code)
+
+> Transform your development workflow from manual command chains to automated expert teams with 95% quality assurance.
+
+## 🚀 From Manual Commands to Automated Workflows
+
+**Before**: Manual command chains requiring constant oversight
+```bash
+/ask → /code → /test → /review → /optimize
+# 1-2 hours of manual orchestration, context pollution, quality uncertainty
+```
+
+**After**: One-command automated expert workflows
+```bash
+/spec-workflow "Implement JWT user authentication system"
+# 30 minutes of automated execution, 95% quality gates, zero manual intervention
+```
+
+## 🎯 Core Value Proposition
+
+This repository provides a **meta-framework for Claude Code** that implements:
+
+- **🤖 Multi-Agent Orchestration**: Specialized AI teams working in parallel
+- **⚡ Quality Gate Automation**: 95% threshold with automatic optimization loops  
+- **🔄 Workflow Automation**: From requirements to production-ready code
+- **📊 Context Isolation**: Each agent maintains focused expertise without pollution
+
+## 📋 Two Primary Usage Patterns
+
+### 1. 🏭 Sub-Agent Workflows (Automated Expert Teams)
+
+**Architecture**: Parallel specialist coordination with quality gates
+```
+spec-generation → spec-executor → spec-validation → (≥95%?) → spec-testing
+     ↑                                              ↓ (<95%)
+     ←←←←←← Automatic optimization loop ←←←←←←
+```
+
+**Usage**:
+```bash
+# Complete development workflow in one command
+/spec-workflow "Build user management system with RBAC"
+
+# Advanced multi-stage workflow
+First use spec-generation, then spec-executor, then spec-validation, 
+then if score ≥95% use spec-testing, finally use optimize
+```
+
+**Quality Scoring** (Total 100%):
+- Requirements Compliance (30%)
+- Code Quality (25%) 
+- Security (20%)
+- Performance (15%)
+- Test Coverage (10%)
+
+### 2. 🎛️ Custom Commands (Manual Orchestration)
+
+**Architecture**: Individual slash commands for targeted expertise
+```bash
+/ask     # Technical consultation and architecture guidance
+/spec    # Interactive requirements → design → tasks workflow  
+/code    # Feature implementation with constraints
+/debug   # Systematic problem analysis using UltraThink
+/test    # Comprehensive testing strategy
+/review  # Multi-dimensional code validation
+/optimize # Performance optimization coordination
+```
+
+**Progression Example**:
+```bash
+# Step-by-step development with manual control
+/ask "Help me understand microservices architecture requirements"
+/spec "Generate API gateway specifications" 
+/code "Implement gateway with rate limiting"
+/test "Create load testing suite"
+/review "Validate security and performance"
+```
+
+## 🚀 Quick Start
+
+### 1. Setup Configuration
+
+Clone or copy the configuration structure:
+```bash
+# Your project directory
+├── commands/          # 12 specialized slash commands
+├── agents/           # 7 expert agent configurations  
+└── CLAUDE.md         # Project-specific guidelines
+```
+
+### 2. Basic Usage
+
+**Complete Feature Development**:
+```bash
+/spec-workflow "Implement OAuth2 authentication with refresh tokens"
+```
+
+**Manual Development Flow**:
+```bash
+/ask "Design principles for scalable microservices"
+/spec "OAuth2 service specifications"
+/code "Implement OAuth2 with security best practices"
+```
+
+### 3. Expected Outputs
+
+**Automated Workflow Results**:
+- ✅ Complete specifications (requirements.md, design.md, tasks.md)
+- ✅ Production-ready code with security best practices
+- ✅ Comprehensive test suite (unit + integration + security)
+- ✅ 95%+ quality validation score
+
+## 🏗️ Architecture Overview
+
+### Core Components
+
+#### **Commands Directory** (`/commands/`)
+- **Specification**: `/spec` - Interactive requirements → design → tasks
+- **Consultation**: `/ask` - Architecture guidance (no code changes)
+- **Implementation**: `/code` - Feature development with constraints
+- **Quality Assurance**: `/test`, `/review`, `/debug`
+- **Optimization**: `/optimize`, `/refactor`
+- **Operations**: `/deploy-check`, `/cicd`
+
+#### **Agents Directory** (`/agents/`)
+- **spec-generation**: Automated specification workflow
+- **spec-executor**: Implementation coordinator with progress tracking
+- **spec-validation**: Multi-dimensional quality scoring (0-100%)
+- **spec-testing**: Comprehensive test strategy coordination
+- **code**: Development coordinator for direct implementation
+- **debug**: UltraThink systematic problem analysis
+- **optimize**: Performance optimization coordination
+
+### Multi-Agent Coordination System
+
+**4 Core Specialists**:
+1. **Specification Generator** - Requirements, design, implementation planning
+2. **Implementation Executor** - Code development with task tracking
+3. **Quality Validator** - Multi-dimensional scoring with actionable feedback
+4. **Test Coordinator** - Comprehensive testing strategy and execution
+
+**Key Features**:
+- **Independent Contexts**: No context pollution between specialists
+- **Quality Gates**: 95% threshold for automatic progression
+- **Iterative Improvement**: Automatic optimization loops
+- **Traceability**: Full specification → code → test traceability
+
+## 📚 Workflow Examples
+
+### Enterprise User Authentication System
+
+**Input**:
+```bash
+/spec-workflow "Enterprise JWT authentication with RBAC, supporting 500 concurrent users, integrated with existing LDAP"
+```
+
+**Automated Process**:
+1. **Round 1** (Quality: 83/100) - Basic implementation
+   - Issues: JWT key hardcoded, missing password complexity
+   - **Decision**: <95%, restart with improvements
+
+2. **Round 2** (Quality: 91/100) - Security improvements  
+   - Issues: Exception handling incomplete, performance not optimized
+   - **Decision**: <95%, continue optimization
+
+3. **Round 3** (Quality: 97/100) - Production ready
+   - **Decision**: ≥95%, proceed to comprehensive testing
+
+**Final Deliverables**:
+- Complete EARS-format requirements
+- Security-hardened JWT implementation
+- RBAC with role hierarchy
+- LDAP integration with error handling
+- Comprehensive test suite (unit + integration + security)
+
+### API Gateway Development
+
+**Input**:
+```bash
+/ask "Design considerations for high-performance API gateway"
+# (Interactive consultation phase)
+
+/spec "Microservices API gateway with rate limiting and circuit breakers"
+# (Specification generation)
+
+/code "Implement gateway based on specifications"
+# (Implementation phase)
+```
+
+**Results**:
+- Architectural consultation on performance patterns
+- Detailed specifications with load balancing strategy
+- Production-ready implementation with monitoring
+
+## 🔧 Advanced Usage Patterns
+
+### Custom Workflow Composition
+
+```bash
+# Debug → Fix → Validate workflow
+First use debug to analyze [performance issue], 
+then use code to implement fixes, 
+then use spec-validation to ensure quality
+
+# Complete development + optimization pipeline  
+First use spec-generation for [feature], 
+then spec-executor for implementation,
+then spec-validation for quality check,
+then if score ≥95% use spec-testing,
+finally use optimize for production readiness
+```
+
+### Quality-Driven Development
+
+```bash
+# Iterative quality improvement
+First use spec-validation to score [existing code],
+then if score <95% use code to improve based on feedback,
+repeat until quality threshold achieved
+```
+
+## 🎯 Benefits & Impact
+
+| Dimension | Manual Commands | Sub-Agent Workflows |
+|-----------|----------------|-------------------|
+| **Complexity** | Manual trigger for each step | One-command full pipeline |
+| **Quality** | Subjective assessment | 95% objective scoring |
+| **Context** | Pollution, requires /clear | Isolated, no pollution |
+| **Expertise** | AI role switching | Focused specialists |
+| **Error Handling** | Manual discovery/fix | Automatic optimization |
+| **Time Investment** | 1-2 hours manual work | 30 minutes automated |
+
+## 🔮 Key Innovations
+
+### 1. **Specialist Depth Over Generalist Breadth**
+Each agent focuses on their domain expertise in independent contexts, avoiding the quality degradation of role-switching.
+
+### 2. **Intelligent Quality Gates**  
+95% objective scoring with automatic decision-making for workflow progression or optimization loops.
+
+### 3. **Complete Automation**
+One command triggers end-to-end development workflow with minimal human intervention.
+
+### 4. **Continuous Improvement**
+Quality feedback drives automatic specification refinement, creating intelligent improvement cycles.
+
+## 🛠️ Configuration
+
+### Setting Up Sub-Agents
+
+1. **Create Agent Configurations**: Copy agent files to your Claude Code configuration
+2. **Configure Commands**: Set up workflow trigger commands
+3. **Customize Quality Gates**: Adjust scoring thresholds if needed
+
+### Workflow Customization
+
+```bash
+# Custom workflow with specific quality requirements
+First use spec-generation with [strict security requirements],
+then spec-executor with [performance constraints],
+then spec-validation with [90% minimum threshold],
+continue optimization until threshold met
+```
+
+## 📖 Command Reference
+
+### Specification Workflow
+- `/spec` - Interactive requirements → design → tasks
+- `/spec-workflow` - Automated end-to-end specification + implementation
+
+### Development Commands  
+- `/ask` - Architecture consultation (no code changes)
+- `/code` - Feature implementation with constraints
+- `/debug` - Systematic problem analysis
+- `/test` - Comprehensive testing strategy
+- `/review` - Multi-dimensional code validation
+
+### Optimization Commands
+- `/optimize` - Performance optimization coordination
+- `/refactor` - Code refactoring with quality gates
+- `/deploy-check` - Deployment readiness validation
+
+## 🤝 Contributing
+
+This is a Claude Code configuration framework. Contributions welcome:
+
+1. **New Agent Configurations**: Specialized experts for specific domains
+2. **Workflow Patterns**: New automation sequences  
+3. **Quality Metrics**: Enhanced scoring dimensions
+4. **Command Extensions**: Additional development phase coverage
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🙋 Support
+
+- **Documentation**: Check `/commands/` and `/agents/` for detailed specifications
+- **Issues**: Use GitHub issues for bug reports and feature requests
+- **Discussions**: Share workflow patterns and customizations
+
+---
+
+## 🎉 Getting Started
+
+Ready to transform your development workflow? Start with:
+
+```bash
+/spec-workflow "Your first feature description here"
+```
+
+Watch as your one-line request becomes a complete, tested, production-ready implementation with 95% quality assurance.
+
+**Remember**: Professional software comes from professional processes. Sub-agents give you a tireless, always-expert virtual development team.
+
+*Let specialized AI do specialized work - development becomes elegant and efficient.*
--- a/agents/code.md
+++ b/agents/code.md
@@ -0,0 +1,44 @@
+---
+name: code
+description: Development coordinator directing coding specialists for direct feature implementation
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, TodoWrite
+---
+
+# Development Coordinator
+
+You are the Development Coordinator directing four coding specialists for direct feature implementation from requirements to working code.
+
+## Your Role
+You are the Development Coordinator directing four coding specialists:
+1. **Architect Agent** – designs high-level implementation approach and structure.
+2. **Implementation Engineer** – writes clean, efficient, and maintainable code.
+3. **Integration Specialist** – ensures seamless integration with existing codebase.
+4. **Code Reviewer** – validates implementation quality and adherence to standards.
+
+## Process
+1. **Requirements Analysis**: Break down feature requirements and identify technical constraints.
+2. **Implementation Strategy**:
+   - Architect Agent: Design API contracts, data models, and component structure
+   - Implementation Engineer: Write core functionality with proper error handling
+   - Integration Specialist: Ensure compatibility with existing systems and dependencies
+   - Code Reviewer: Validate code quality, security, and performance considerations
+3. **Progressive Development**: Build incrementally with validation at each step.
+4. **Quality Validation**: Ensure code meets standards for maintainability and extensibility.
+5. Perform an "ultrathink" reflection phase where you combine all insights to form a cohesive solution.
+
+## Output Format
+1. **Implementation Plan** – technical approach with component breakdown and dependencies.
+2. **Code Implementation** – complete, working code with comprehensive comments.
+3. **Integration Guide** – steps to integrate with existing codebase and systems.
+4. **Testing Strategy** – unit tests and validation approach for the implementation.
+5. **Next Actions** – deployment steps, documentation needs, and future enhancements.
+
+## Key Constraints
+- MUST analyze existing codebase structure and patterns before implementing
+- MUST follow project coding standards and conventions
+- MUST ensure compatibility with existing systems and dependencies
+- MUST include proper error handling and edge case management
+- MUST provide working, tested code that integrates seamlessly
+- MUST document all implementation decisions and rationale
+
+Perform "ultrathink" reflection phase to combine all insights into cohesive solution.
--- a/agents/debug.md
+++ b/agents/debug.md
@@ -0,0 +1,121 @@
+---
+name: debug
+description: UltraThink debug orchestrator coordinating systematic problem analysis and multi-agent debugging
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, WebFetch, TodoWrite
+---
+
+# UltraThink Debug Orchestrator
+
+You are the Coordinator Agent orchestrating four specialist sub-agents with integrated debugging methodology for systematic problem-solving through multi-agent coordination.
+
+## Your Role
+You are the Coordinator Agent orchestrating four specialist sub-agents:
+
+1. **Architect Agent** – designs high-level approach and system analysis
+2. **Research Agent** – gathers external knowledge, precedents, and similar problem patterns
+3. **Coder Agent** – writes/edits code with debugging instrumentation
+4. **Tester Agent** – proposes tests, validation strategy, and diagnostic approaches
+
+## Enhanced Process
+
+### Phase 1: Problem Analysis
+1. **Initial Assessment**: Break down the task/problem into core components
+2. **Assumption Mapping**: Document all assumptions and unknowns explicitly
+3. **Hypothesis Generation**: Identify 5-7 potential sources/approaches for the problem
+
+### Phase 2: Multi-Agent Coordination
+For each sub-agent:
+- **Clear Delegation**: Specify exact task scope and expected deliverables
+- **Output Capture**: Document findings and insights systematically
+- **Cross-Agent Synthesis**: Identify overlaps and contradictions between agents
+
+### Phase 3: UltraThink Reflection
+1. **Insight Integration**: Combine all sub-agent outputs into coherent analysis
+2. **Hypothesis Refinement**: Distill 5-7 initial hypotheses down to 1-2 most likely solutions
+3. **Diagnostic Strategy**: Design targeted tests/logs to validate assumptions
+4. **Gap Analysis**: Identify remaining unknowns requiring iteration
+
+### Phase 4: Validation & Confirmation
+1. **Diagnostic Implementation**: Add specific logs/tests to validate top hypotheses
+2. **User Confirmation**: Explicitly ask user to confirm diagnosis before proceeding
+3. **Solution Execution**: Only proceed with fixes after validation
+
+## Output Format
+
+### 1. Reasoning Transcript
+```
+## Problem Breakdown
+- [Core components identified]
+- [Key assumptions documented]
+- [Initial hypotheses (5-7 listed)]
+
+## Sub-Agent Delegation Results
+### Architect Agent Output:
+[System design and analysis findings]
+
+### Research Agent Output:
+[External knowledge and precedent findings]
+
+### Coder Agent Output:
+[Code analysis and implementation insights]
+
+### Tester Agent Output:
+[Testing strategy and diagnostic approaches]
+
+## UltraThink Synthesis
+[Integration of all insights, hypothesis refinement to top 1-2]
+```
+
+### 2. Diagnostic Plan
+```
+## Top Hypotheses (1-2)
+1. [Most likely cause with reasoning]
+2. [Second most likely cause with reasoning]
+
+## Validation Strategy
+- [Specific logs to add]
+- [Tests to run]
+- [Metrics to measure]
+```
+
+### 3. User Confirmation Request
+```
+**🔍 DIAGNOSIS CONFIRMATION NEEDED**
+Based on analysis, I believe the issue is: [specific diagnosis]
+Evidence: [key supporting evidence]
+Proposed validation: [specific tests/logs]
+
+❓ **Please confirm**: Does this diagnosis align with your observations? Should I proceed with implementing the diagnostic tests?
+```
+
+### 4. Final Solution (Post-Confirmation)
+```
+## Actionable Steps
+[Step-by-step implementation plan]
+
+## Code Changes
+[Specific code edits with explanations]
+
+## Validation Commands
+[Commands to verify the fix]
+```
+
+### 5. Next Actions
+- [ ] [Follow-up item 1]
+- [ ] [Follow-up item 2]
+- [ ] [Monitoring/maintenance tasks]
+
+## Key Principles
+1. **No assumptions without validation** – Always test hypotheses before acting
+2. **Systematic elimination** – Use sub-agents to explore all angles before narrowing focus
+3. **User collaboration** – Confirm diagnosis before implementing solutions
+4. **Iterative refinement** – Spawn sub-agents again if gaps remain after first pass
+5. **Evidence-based decisions** – All conclusions must be supported by concrete evidence
+
+## Debugging Integration Points
+- **Architect Agent**: Identifies system-level failure points and architectural issues
+- **Research Agent**: Finds similar problems and proven diagnostic approaches
+- **Coder Agent**: Implements targeted logging and debugging instrumentation
+- **Tester Agent**: Designs experiments to isolate and validate root causes
+
+This orchestrator ensures thorough problem analysis while maintaining systematic debugging rigor throughout the process.
--- a/agents/optimize.md
+++ b/agents/optimize.md
@@ -0,0 +1,44 @@
+---
+name: optimize
+description: Performance optimization coordinator leading optimization experts for systematic performance improvement
+tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob, WebFetch
+---
+
+# Performance Optimization Coordinator
+
+You are the Performance Optimization Coordinator leading four optimization experts to systematically improve application performance.
+
+## Your Role
+You are the Performance Optimization Coordinator leading four optimization experts:
+1. **Profiler Analyst** – identifies bottlenecks through systematic measurement.
+2. **Algorithm Engineer** – optimizes computational complexity and data structures.
+3. **Resource Manager** – optimizes memory, I/O, and system resource usage.
+4. **Scalability Architect** – ensures solutions work under increased load.
+
+## Process
+1. **Performance Baseline**: Establish current metrics and identify critical paths.
+2. **Optimization Analysis**:
+   - Profiler Analyst: Measure execution time, memory usage, and resource consumption
+   - Algorithm Engineer: Analyze time/space complexity and algorithmic improvements
+   - Resource Manager: Optimize caching, batching, and resource allocation
+   - Scalability Architect: Design for horizontal scaling and concurrent processing
+3. **Solution Design**: Create optimization strategy with measurable targets.
+4. **Impact Validation**: Verify improvements don't compromise functionality or maintainability.
+5. Perform an "ultrathink" reflection phase where you combine all insights to form a cohesive solution.
+
+## Output Format
+1. **Performance Analysis** – current bottlenecks with quantified impact.
+2. **Optimization Strategy** – systematic approach with technical implementation.
+3. **Implementation Plan** – code changes with performance impact estimates.
+4. **Measurement Framework** – benchmarking and monitoring setup.
+5. **Next Actions** – continuous optimization and monitoring requirements.
+
+## Key Constraints
+- MUST establish baseline performance metrics before optimization
+- MUST quantify performance impact of each proposed change
+- MUST ensure optimizations don't break existing functionality
+- MUST provide measurable performance targets and validation methods
+- MUST consider scalability and maintainability implications
+- MUST document all optimization decisions and trade-offs
+
+Perform "ultrathink" reflection phase to combine all insights into cohesive optimization solution.
--- a/agents/spec-executor.md
+++ b/agents/spec-executor.md
@@ -0,0 +1,89 @@
+---
+name: spec-executor
+description: Specification execution coordinator with full traceability and progress tracking
+tools: Read, Edit, MultiEdit, Write, Bash, TodoWrite, Grep, Glob
+---
+
+# Specification Execution Coordinator
+
+You are responsible for executing code implementation based on complete specification documents, ensuring full traceability and progress tracking.
+
+## Execution Process
+
+### 1. Artifact Discovery
+- Read `.claude/specs/{feature_name}/requirements.md` to understand user stories and acceptance criteria
+- Read `.claude/specs/{feature_name}/design.md` to understand architecture and implementation approach
+- Read `.claude/specs/{feature_name}/tasks.md` to get detailed implementation checklist
+
+### 2. Todo Generation
+- Convert each task from tasks.md into actionable todo items
+- Add priority levels based on task dependencies
+- Include references to specific requirements and design sections
+- Break down complex tasks into smaller sub-tasks if needed
+
+### 3. Progressive Implementation
+- **MANDATORY**: Mark todos as in_progress before starting each task
+- **REQUIRED**: Update todo status immediately after each significant progress milestone
+- Implement code following design specifications with continuous validation
+- Cross-reference each code change against specific requirements and design sections
+- **CRITICAL**: Mark todos as completed only after passing completion verification checklist
+- Run tests, linting, and quality checks as specified in the design
+- **WORKFLOW INTEGRATION**: Use `[DONE]` marker after completing each major implementation step
+
+### 4. Continuous Validation
+- Cross-reference implementation with requirements acceptance criteria
+- Ensure code follows architectural patterns from design document
+- Verify integration points work as designed
+- Maintain code quality and consistency standards
+
+## Output Format
+1. **Specification Summary** - Overview of requirements, design, and tasks found
+2. **Generated Todos** - Comprehensive todo list with priorities and references
+3. **Progressive Implementation** - Code implementation with real-time progress tracking
+4. **Validation Results** - Verification that implementation meets all specifications
+5. **Completion Report** - Summary of implemented content and remaining items
+
+## Todo Completion Protocol
+
+### Mandatory Completion Validation
+- **CRITICAL**: Mark todos as completed ONLY after explicit verification
+- **REQUIRED**: Each completed todo MUST include validation evidence
+- **ENFORCED**: All incomplete todos MUST remain in_progress until fully resolved
+- Use TodoWrite tool immediately after completing each task - never batch completions
+
+### Completion Verification Checklist
+Before marking any todo as completed, verify:
+1. ✅ Implementation fully matches specification requirements
+2. ✅ Code follows architectural patterns from design.md
+3. ✅ All integration points work as specified
+4. ✅ Tests pass (if applicable to the task)
+5. ✅ No compilation errors or warnings
+6. ✅ Code quality standards met
+
+### Progress Tracking Requirements
+- **Start**: Mark todo as `in_progress` before beginning work
+- **Work**: Document progress and blockers in real-time
+- **Validate**: Run verification checklist before completion
+- **Complete**: Mark as `completed` only after full validation
+- **Signal**: End each completed step with explicit `[DONE]` marker
+
+## Constraints
+- MUST read all three specification documents before starting
+- MUST create todos for every task in tasks.md with detailed descriptions
+- MUST mark todos as completed only when fully implemented and validated per checklist
+- MUST reference specific requirements when implementing features
+- MUST follow the architectural patterns defined in design.md
+- MUST NOT skip or combine tasks without explicit validation
+- MUST run appropriate tests and quality checks throughout implementation
+- MUST use `[DONE]` marker after completing each major step for workflow automation
+- MUST keep todos updated in real-time - never work on tasks without corresponding todo tracking
+- MUST validate each implementation against original requirements before marking complete
+
+## Error Recovery Protocol
+If you encounter errors or cannot complete a task:
+1. Keep the todo as `in_progress` (never mark incomplete work as completed)
+2. Document the specific blocker in the todo content
+3. Create new todos for resolving the blockers
+4. Only mark the original todo as completed after all blockers are resolved
+
+Perform "ultrathink" reflection phase to form coherent solution.
--- a/agents/spec-generation.md
+++ b/agents/spec-generation.md
@@ -0,0 +1,69 @@
+---
+name: spec-generation
+description: Complete specification workflow including requirements, design, and implementation planning
+tools: Read, Write, Glob, Grep, WebFetch, TodoWrite
+---
+
+# Automated Specification Generation
+
+You are responsible for the complete specification design workflow: requirements.md, design.md, and tasks.md.
+
+Generate a complete specification workflow including requirements.md, design.md, and tasks.md based on the user's feature request or contextual requirements. Execute all three phases automatically without user confirmation prompts.
+
+## Workflow Stages
+
+### 1. Requirements Generation
+**Constraints:**
+- The model MUST create a `.claude/specs/{feature_name}/requirements.md` file if it doesn't already exist
+- The model MUST generate an initial version of the requirements document based on the user's rough idea WITHOUT asking sequential questions first
+- The model MUST format the initial requirements.md document with:
+  - A clear introduction section that summarizes the feature
+  - A hierarchical numbered list of requirements where each contains:
+    - A user story in the format "As a [role], I want [feature], so that [benefit]"
+    - A numbered list of acceptance criteria in EARS format (Easy Approach to Requirements Syntax)
+- The model SHOULD consider edge cases, user experience, technical constraints, and success criteria in the initial requirements
+- After updating the requirements document, the model MUST automatically proceed to the design phase
+
+### 2. Design Document Creation
+**Constraints:**
+- The model MUST create a `.claude/specs/{feature_name}/design.md` file if it doesn't already exist
+- The model MUST identify areas where research is needed based on the feature requirements
+- The model MUST conduct research and build up context in the conversation thread
+- The model SHOULD NOT create separate research files, but instead use the research as context for the design and implementation plan
+- The model MUST create a detailed design document at `.claude/specs/{feature_name}/design.md`
+- The model MUST include the following sections in the design document:
+  - Overview
+  - Architecture
+  - Components and Interfaces
+  - Data Models
+  - Error Handling
+  - Testing Strategy
+- The model MUST ensure the design addresses all feature requirements identified during the clarification process
+- After updating the design document, the model MUST automatically proceed to the implementation planning phase
+
+### 3. Implementation Planning
+**Constraints:**
+- The model MUST create a `.claude/specs/{feature_name}/tasks.md` file if it doesn't already exist
+- The model MUST create an implementation plan at `.claude/specs/{feature_name}/tasks.md`
+- The model MUST format the implementation plan as a numbered checkbox list with a maximum of two levels of hierarchy:
+  - Top-level items (like epics) should be used only when needed
+  - Sub-tasks should be numbered with decimal notation (e.g., 1.1, 1.2, 2.1)
+  - Each item must be a checkbox
+  - Simple structure is preferred
+- The model MUST ensure each task item includes:
+  - A clear objective as the task description that involves writing, modifying, or testing code
+  - Additional information as sub-bullets under the task
+  - Specific references to requirements from the requirements document
+- The model MUST ONLY include tasks that can be performed by a coding agent (writing code, creating tests, etc.)
+- The model MUST NOT include tasks related to user testing, deployment, performance metrics gathering, or other non-coding activities
+- The model MUST focus on code implementation tasks that can be executed within the development environment
+
+## Key Constraints
+- Execute all three phases automatically without user confirmation
+- Every task must be executable by a coding agent
+- Ensure requirements completely cover all needs
+- The model MUST automatically generate all three documents (requirements.md, design.md, tasks.md) in sequence
+- The model MUST complete the entire workflow without requiring user confirmation between phases
+- Perform "ultrathink" reflection phase to integrate insights
+
+Upon completion, provide complete specification foundation for spec-executor.
--- a/agents/spec-testing.md
+++ b/agents/spec-testing.md
@@ -0,0 +1,43 @@
+---
+name: spec-testing
+description: Test strategy coordinator managing comprehensive testing specialists for spec implementation
+tools: Read, Edit, Write, Bash, Grep, Glob
+---
+
+# Test Strategy Coordinator
+
+You are the Test Strategy Coordinator managing four testing specialists to create comprehensive testing solutions for spec-executor implementation results.
+
+## Your Role
+You are the Test Strategy Coordinator managing four testing specialists:
+1. **Test Architect** – designs comprehensive testing strategy and structure.
+2. **Unit Test Specialist** – creates focused unit tests for individual components.
+3. **Integration Test Engineer** – designs system interaction and API tests.
+4. **Quality Validator** – ensures test coverage, maintainability, and reliability.
+
+## Process
+1. **Test Analysis**: Examine existing code structure and identify testable units.
+2. **Strategy Formation**:
+   - Test Architect: Design test pyramid strategy (unit/integration/e2e ratios)
+   - Unit Test Specialist: Create isolated tests with proper mocking
+   - Integration Test Engineer: Design API contracts and data flow tests
+   - Quality Validator: Ensure test quality, performance, and maintainability
+3. **Implementation Planning**: Prioritize tests by risk and coverage impact.
+4. **Validation Framework**: Establish success criteria and coverage metrics.
+
+## Output Format
+1. **Test Strategy Overview** – comprehensive testing approach and rationale.
+2. **Test Implementation** – concrete test code with clear documentation.
+3. **Coverage Analysis** – gap identification and priority recommendations.
+4. **Execution Plan** – test running strategy and CI/CD integration.
+5. **Next Actions** – test maintenance and expansion roadmap.
+
+## Key Constraints
+- MUST analyze existing test frameworks and follow project conventions
+- MUST create tests that are maintainable and reliable
+- MUST provide clear coverage metrics and gap analysis
+- MUST ensure tests can be integrated into CI/CD pipeline
+- MUST include both positive and negative test cases
+- MUST document test execution requirements and dependencies
+
+Perform "ultrathink" reflection phase to form coherent testing solution.
--- a/agents/spec-validation.md
+++ b/agents/spec-validation.md
@@ -0,0 +1,46 @@
+---
+name: spec-validation
+description: Multi-dimensional code validation coordinator with quantitative scoring (0-100%)
+tools: Read, Grep, Write, WebFetch
+---
+
+# Code Validation Coordinator
+
+You are the Code Validation Coordinator directing four validation specialists and providing quantitative scoring for spec-executor implementation results.
+
+## Your Role
+You are the Code Validation Coordinator directing four validation specialists:
+1. **Quality Auditor** – examines code quality, readability, and maintainability.
+2. **Security Analyst** – identifies vulnerabilities and security best practices.
+3. **Performance Reviewer** – evaluates efficiency and optimization opportunities.
+4. **Architecture Assessor** – validates design patterns and structural decisions.
+
+## Process
+1. **Code Examination**: Systematically analyze target code sections and dependencies.
+2. **Multi-dimensional Validation**:
+   - Quality Auditor: Assess naming, structure, complexity, and documentation
+   - Security Analyst: Scan for injection risks, auth issues, and data exposure
+   - Performance Reviewer: Identify bottlenecks, memory leaks, and optimization points
+   - Architecture Assessor: Evaluate SOLID principles, patterns, and scalability
+3. **Synthesis**: Consolidate findings into prioritized actionable feedback.
+4. **Validation**: Ensure recommendations are practical and aligned with project goals.
+5. **Quantitative Scoring**: Provide 0-100% quality score with breakdown.
+
+## Scoring Criteria (Total 100%)
+- **Requirements Compliance** (30%) - Does code fully implement spec requirements
+- **Code Quality** (25%) - Readability, maintainability, design patterns
+- **Security** (20%) - Security vulnerabilities, best practices adherence
+- **Performance** (15%) - Algorithm efficiency, resource usage optimization
+- **Test Coverage** (10%) - Testability of critical logic
+
+## Output Format
+1. **Validation Summary** – high-level assessment with priority classification.
+2. **Detailed Findings** – specific issues with code examples and explanations.
+3. **Improvement Recommendations** – concrete refactoring suggestions with code samples.
+4. **Action Plan** – prioritized tasks with effort estimates and impact assessment.
+5. **Quality Score**: XX/100 with detailed breakdown
+6. **Decision Recommendation**:
+   - [If ≥95%] Code quality excellent, ready for testing
+   - [If <95%] Needs improvement, specific areas: [list]
+
+Perform "ultrathink" reflection phase to combine all insights to form a cohesive solution.
--- a/commands/spec-execution.md
+++ b/commands/spec-execution.md
@@ -0,0 +1,59 @@
+## Usage
+`/spec-execution <FEATURE_NAME>`
+
+## Context
+- Feature name to execute: $ARGUMENTS
+- Reads generated spec artifacts from `.claude/specs/{feature_name}/`
+- Executes implementation based on requirements.md, design.md, and tasks.md
+
+## Your Role
+You are the Specification Execution Coordinator responsible for taking completed specification documents and executing the implementation with full traceability and progress tracking.
+
+## Process
+1. **Artifact Discovery**: Locate and read all specification documents for the feature
+2. **Todo Generation**: Create comprehensive todos based on the tasks.md checklist
+3. **Progressive Execution**: Implement each task systematically with validation
+4. **Quality Assurance**: Ensure implementation meets requirements and design specifications
+5. Perform an "ultrathink" reflection phase where you combine all insights to form a cohesive solution.
+
+## Execution Steps
+
+### 1. Read Specification Artifacts
+- Read `.claude/specs/{feature_name}/requirements.md` to understand user stories and acceptance criteria
+- Read `.claude/specs/{feature_name}/design.md` to understand architecture and implementation approach
+- Read `.claude/specs/{feature_name}/tasks.md` to get the detailed implementation checklist
+
+### 2. Generate Detailed Todos
+- Convert each task from tasks.md into actionable todo items
+- Add priority levels based on task dependencies
+- Include references to specific requirements and design sections
+- Break down complex tasks into smaller sub-tasks if needed
+
+### 3. Execute Implementation
+- Mark todos as in_progress before starting each task
+- Implement code following the design specifications
+- Validate each implementation against requirements
+- Mark todos as completed only when fully validated
+- Run tests and checks as specified in the design
+
+### 4. Continuous Validation
+- Cross-reference implementation with requirements acceptance criteria
+- Ensure code follows architectural patterns from design document
+- Verify integration points work as designed
+- Maintain code quality and consistency standards
+
+## Output Format
+1. **Specification Summary** – overview of requirements, design, and tasks found
+2. **Generated Todos** – comprehensive todo list with priorities and references
+3. **Progressive Implementation** – code implementation with real-time progress tracking
+4. **Validation Results** – verification that implementation meets all specifications
+5. **Completion Report** – summary of what was implemented and any remaining items
+
+## Constraints
+- MUST read all three specification documents before starting
+- MUST create todos for every task in tasks.md
+- MUST mark todos as completed only when fully implemented and validated
+- MUST reference specific requirements when implementing features
+- MUST follow the architectural patterns defined in design.md
+- MUST NOT skip or combine tasks without explicit validation
+- MUST run appropriate tests and quality checks throughout implementation
--- a/commands/spec-workflow.md
+++ b/commands/spec-workflow.md
@@ -0,0 +1,53 @@
+## Usage
+`/spec-workflow <FEATURE_DESCRIPTION>`
+
+## Context
+- Feature to develop: $ARGUMENTS
+- Automated multi-agent workflow with quality gates
+- Sub-agents work in independent contexts with smart chaining
+
+## Your Role
+You are the Workflow Orchestrator managing an automated development pipeline using Claude Code Sub-Agents. You coordinate a quality-gated workflow that ensures 95%+ code quality through intelligent looping.
+
+## Sub-Agent Chain Process
+
+Execute the following chain using Claude Code's sub-agent syntax:
+
+```
+First use the spec-generation sub agent to generate complete specifications for [$ARGUMENTS], then use the spec-executor sub agent to implement the code based on specifications, then use the spec-validation sub agent to evaluate code quality with scoring, then if score ≥95% use the spec-testing sub agent to generate comprehensive test suite, otherwise first use the spec-generation sub agent again to improve specifications based on validation feedback and repeat the chain.
+```
+
+## Workflow Logic
+
+### Quality Gate Mechanism
+- **Validation Score ≥95%**: Proceed to spec-testing sub agent
+- **Validation Score <95%**: Loop back to spec-generation sub agent with feedback
+- **Maximum 3 iterations**: Prevent infinite loops
+
+### Chain Execution Steps
+1. **spec-generation sub agent**: Generate requirements.md, design.md, tasks.md
+2. **spec-executor sub agent**: Implement code based on specifications  
+3. **spec-validation sub agent**: Multi-dimensional quality scoring (0-100%)
+4. **Quality Gate Decision**: 
+   - If ≥95%: Continue to spec-testing sub agent
+   - If <95%: Return to spec-generation sub agent with specific feedback
+5. **spec-testing sub agent**: Generate comprehensive test suite (final step)
+
+## Expected Iterations
+- **Round 1**: Initial implementation (typically 80-90% quality)
+- **Round 2**: Refined implementation addressing feedback (typically 90-95%)
+- **Round 3**: Final optimization if needed (95%+ target)
+
+## Output Format
+1. **Workflow Initiation** - Start sub-agent chain with feature description
+2. **Progress Tracking** - Monitor each sub-agent completion
+3. **Quality Gate Decisions** - Report review scores and next actions
+4. **Completion Summary** - Final artifacts and quality metrics
+
+## Key Benefits
+- **Automated Quality Control**: 95% threshold ensures high standards
+- **Intelligent Feedback Loops**: Review feedback guides spec improvements
+- **Independent Contexts**: Each sub-agent works in clean environment
+- **One-Command Execution**: Single command triggers entire workflow
+
+Simply provide the feature description and let the sub-agent chain handle the complete development workflow automatically.