catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: 增强 command-guide skill 支持深度命令分析和 CLI 辅助查询

Browse Source 
新增 Mode 6: 深度命令分析
- 创建 reference 备份目录（80个文档：11 agents + 69 commands）
- 支持简单查询（直接文件查找）和复杂查询（CLI 辅助分析）
- 集成 gemini/qwen 进行跨命令对比、最佳实践、工作流分析
- 添加查询复杂度自动分类和降级策略

更新文档
- SKILL.md: 添加 Mode 6 说明和 Reference Documentation 章节
- implementation-details.md: 添加完整的 Mode 6 实现逻辑
- 版本更新至 v1.3.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-11-06 16:27:58 +08:00
parent 0ab3d0e1af
commit 1897ba4e82
85 changed files with 30439 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

417
.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md Normal file
View File

@@ -0,0 +1,417 @@
---
name: action-plan-verify
description: Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation
argument-hint: "[optional: --session session-id]"
allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Goal
Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
## Operating Constraints
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
**Synthesis Authority**: The `role analysis documents` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
## Execution Steps
### 1. Initialize Analysis Context
```bash
# Detect active workflow session
IF --session parameter provided:
session_id = provided session
ELSE:
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
ELSE:
ERROR: "No active workflow session found. Use --session <session-id>"
EXIT
# Derive absolute paths
session_dir = .workflow/WFS-{session}
brainstorm_dir = session_dir/.brainstorming
task_dir = session_dir/.task
# Validate required artifacts
SYNTHESIS = brainstorm_dir/role analysis documents
IMPL_PLAN = session_dir/IMPL_PLAN.md
TASK_FILES = Glob(task_dir/*.json)
# Abort if missing
IF NOT EXISTS(SYNTHESIS):
ERROR: "role analysis documents not found. Run /workflow:brainstorm:synthesis first"
EXIT
IF NOT EXISTS(IMPL_PLAN):
ERROR: "IMPL_PLAN.md not found. Run /workflow:plan first"
EXIT
IF TASK_FILES.count == 0:
ERROR: "No task JSON files found. Run /workflow:plan first"
EXIT
```
### 2. Load Artifacts (Progressive Disclosure)
Load only minimal necessary context from each artifact:
**From workflow-session.json** (NEW - PRIMARY REFERENCE):
- Original user prompt/intent (project or description field)
- User's stated goals and objectives
- User's scope definition
**From role analysis documents**:
- Functional Requirements (IDs, descriptions, acceptance criteria)
- Non-Functional Requirements (IDs, targets)
- Business Requirements (IDs, success metrics)
- Key Architecture Decisions
- Risk factors and mitigation strategies
- Implementation Roadmap (high-level phases)
**From IMPL_PLAN.md**:
- Summary and objectives
- Context Analysis
- Implementation Strategy
- Task Breakdown Summary
- Success Criteria
- Brainstorming Artifacts References (if present)
**From task.json files**:
- Task IDs
- Titles and descriptions
- Status
- Dependencies (depends_on, blocks)
- Context (requirements, focus_paths, acceptance, artifacts)
- Flow control (pre_analysis, implementation_approach)
- Meta (complexity, priority, use_codex)
### 3. Build Semantic Models
Create internal representations (do not include raw artifacts in output):
**Requirements inventory**:
- Each functional/non-functional/business requirement with stable ID
- Requirement text, acceptance criteria, priority
**Architecture decisions inventory**:
- ADRs from synthesis
- Technology choices
- Data model references
**Task coverage mapping**:
- Map each task to one or more requirements (by ID reference or keyword inference)
- Map each requirement to covering tasks
**Dependency graph**:
- Task-to-task dependencies (depends_on, blocks)
- Requirement-level dependencies (from synthesis)
### 4. Detection Passes (Token-Efficient Analysis)
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
#### A. User Intent Alignment (NEW - CRITICAL)
- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
- **Success Criteria Match**: Plan's success criteria reflect user's expectations
- **Intent Conflicts**: Tasks contradicting user's original objectives
#### B. Requirements Coverage Analysis
- **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
- **Unmapped Tasks**: Tasks with no clear requirement linkage
- **NFR Coverage Gaps**: Non-functional requirements (performance, security, scalability) not reflected in tasks
#### B. Consistency Validation
- **Requirement Conflicts**: Tasks contradicting synthesis requirements
- **Architecture Drift**: IMPL_PLAN architecture not matching synthesis ADRs
- **Terminology Drift**: Same concept named differently across IMPL_PLAN and tasks
- **Data Model Inconsistency**: Tasks referencing entities/fields not in synthesis data model
#### C. Dependency Integrity
- **Circular Dependencies**: Task A depends on B, B depends on C, C depends on A
- **Missing Dependencies**: Task requires outputs from another task but no explicit dependency
- **Broken Dependencies**: Task depends on non-existent task ID
- **Logical Ordering Issues**: Implementation tasks before foundational setup without dependency note
#### D. Synthesis Alignment
- **Priority Conflicts**: High-priority synthesis requirements mapped to low-priority tasks
- **Success Criteria Mismatch**: IMPL_PLAN success criteria not covering synthesis acceptance criteria
- **Risk Mitigation Gaps**: Critical risks in synthesis without corresponding mitigation tasks
#### E. Task Specification Quality
- **Ambiguous Focus Paths**: Tasks with vague or missing focus_paths
- **Underspecified Acceptance**: Tasks without clear acceptance criteria
- **Missing Artifacts References**: Tasks not referencing relevant brainstorming artifacts in context.artifacts
- **Weak Flow Control**: Tasks without clear implementation_approach or pre_analysis steps
- **Missing Target Files**: Tasks without flow_control.target_files specification
#### F. Duplication Detection
- **Overlapping Task Scope**: Multiple tasks with nearly identical descriptions
- **Redundant Requirements Coverage**: Same requirement covered by multiple tasks without clear partitioning
#### G. Feasibility Assessment
- **Complexity Misalignment**: Task marked "simple" but requires multiple file modifications
- **Resource Conflicts**: Parallel tasks requiring same resources/files
- **Skill Gap Risks**: Tasks requiring skills not in team capability assessment (from synthesis)
### 5. Severity Assignment
Use this heuristic to prioritize findings:
- **CRITICAL**:
- Violates user's original intent (goal misalignment, scope drift)
- Violates synthesis authority (requirement conflict)
- Core requirement with zero coverage
- Circular dependencies
- Broken dependencies
- **HIGH**:
- NFR coverage gaps
- Priority conflicts
- Missing risk mitigation tasks
- Ambiguous acceptance criteria
- **MEDIUM**:
- Terminology drift
- Missing artifacts references
- Weak flow control
- Logical ordering issues
- **LOW**:
- Style/wording improvements
- Minor redundancy not affecting execution
### 6. Produce Compact Analysis Report
Output a Markdown report (no file writes) with the following structure:
```markdown
## Action Plan Verification Report
**Session**: WFS-{session-id}
**Generated**: {timestamp}
**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files
---
### Executive Summary
- **Overall Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
- **Recommendation**: BLOCK_EXECUTION | PROCEED_WITH_FIXES | PROCEED_WITH_CAUTION | PROCEED
- **Critical Issues**: {count}
- **High Issues**: {count}
- **Medium Issues**: {count}
- **Low Issues**: {count}
---
### Findings Summary
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|----|----------|----------|-------------|---------|----------------|
| C1 | Coverage | CRITICAL | synthesis:FR-03 | Requirement "User auth" has zero task coverage | Add authentication implementation task |
| H1 | Consistency | HIGH | IMPL-1.2 vs synthesis:ADR-02 | Task uses REST while synthesis specifies GraphQL | Align task with ADR-02 decision |
| M1 | Specification | MEDIUM | IMPL-2.1 | Missing context.artifacts reference | Add @synthesis reference |
| L1 | Duplication | LOW | IMPL-3.1, IMPL-3.2 | Similar scope | Consider merging |
(Add one row per finding; generate stable IDs prefixed by severity initial.)
---
### Requirements Coverage Analysis
| Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
|----------------|---------------------|-----------|----------|----------------|-------|
| FR-01 | User authentication | Yes | IMPL-1.1, IMPL-1.2 | Match | Complete |
| FR-02 | Data export | Yes | IMPL-2.3 | Mismatch | High req → Med priority task |
| FR-03 | Profile management | No | - | - | **CRITICAL: Zero coverage** |
| NFR-01 | Response time <200ms | No | - | - | **HIGH: No performance tasks** |
**Coverage Metrics**:
- Functional Requirements: 85% (17/20 covered)
- Non-Functional Requirements: 40% (2/5 covered)
- Business Requirements: 100% (5/5 covered)
---
### Unmapped Tasks
| Task ID | Title | Issue | Recommendation |
|---------|-------|-------|----------------|
| IMPL-4.5 | Refactor utils | No requirement linkage | Link to technical debt or remove |
---
### Dependency Graph Issues
**Circular Dependencies**: None detected
**Broken Dependencies**:
- IMPL-2.3 depends on "IMPL-2.4" (non-existent)
**Logical Ordering Issues**:
- IMPL-5.1 (integration test) has no dependency on IMPL-1.* (implementation tasks)
---
### Synthesis Alignment Issues
| Issue Type | Synthesis Reference | IMPL_PLAN/Task | Impact | Recommendation |
|------------|---------------------|----------------|--------|----------------|
| Architecture Conflict | synthesis:ADR-01 (JWT auth) | IMPL_PLAN uses session cookies | HIGH | Update IMPL_PLAN to use JWT |
| Priority Mismatch | synthesis:FR-02 (High) | IMPL-2.3 (Medium) | MEDIUM | Elevate task priority |
| Missing Risk Mitigation | synthesis:Risk-03 (API rate limits) | No mitigation tasks | HIGH | Add rate limiting implementation task |
---
### Task Specification Quality Issues
**Missing Artifacts References**: 12 tasks lack context.artifacts
**Weak Flow Control**: 5 tasks lack implementation_approach
**Missing Target Files**: 8 tasks lack flow_control.target_files
**Sample Issues**:
- IMPL-1.2: No context.artifacts reference to synthesis
- IMPL-3.1: Missing flow_control.target_files specification
- IMPL-4.2: Vague focus_paths ["src/"] - needs refinement
---
### Feasibility Concerns
| Concern | Tasks Affected | Issue | Recommendation |
|---------|----------------|-------|----------------|
| Skill Gap | IMPL-6.1, IMPL-6.2 | Requires Kubernetes expertise not in team | Add training task or external consultant |
| Resource Conflict | IMPL-3.1, IMPL-3.2 | Both modify src/auth/service.ts in parallel | Add dependency or serialize |
---
### Metrics
- **Total Requirements**: 30 (20 functional, 5 non-functional, 5 business)
- **Total Tasks**: 25
- **Overall Coverage**: 77% (23/30 requirements with ≥1 task)
- **Critical Issues**: 2
- **High Issues**: 5
- **Medium Issues**: 8
- **Low Issues**: 3
---
### Next Actions
#### Action Recommendations
**If CRITICAL Issues Exist**:
- **BLOCK EXECUTION** - Resolve critical issues before proceeding
- Use TodoWrite to track all required fixes
- Fix broken dependencies and circular references
**If Only HIGH/MEDIUM/LOW Issues**:
- **PROCEED WITH CAUTION** - Fix high-priority issues first
- Use TodoWrite to systematically track and complete all improvements
#### TodoWrite-Based Remediation Workflow
**Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
**Recommended Workflow**:
1. **Create TodoWrite Task List**: Extract all findings from report
2. **Process by Priority**: CRITICAL → HIGH → MEDIUM → LOW
3. **Complete Each Fix**: Mark tasks as in_progress/completed as you work
4. **Validate Changes**: Verify each modification against requirements
**TodoWrite Task Structure Example**:
```markdown
Priority Order:
1. Fix coverage gaps (CRITICAL)
2. Resolve consistency conflicts (CRITICAL/HIGH)
3. Add missing specifications (MEDIUM)
4. Improve task quality (LOW)
```
**Notes**:
- TodoWrite provides real-time progress tracking
- Each finding becomes a trackable todo item
- User can monitor progress throughout remediation
- Architecture drift in IMPL_PLAN requires manual editing
```
### 7. Save Report and Execute TodoWrite-Based Remediation
**Save Analysis Report**:
```bash
report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
Write(report_path, full_report_content)
```
**After Report Generation**:
1. **Extract Findings**: Parse all issues by severity
2. **Create TodoWrite Task List**: Convert findings to actionable todos
3. **Execute Fixes**: Process each todo systematically
4. **Update Task Files**: Apply modifications directly to task JSON files
5. **Update IMPL_PLAN**: Apply strategic changes if needed
At end of report, provide remediation guidance:
```markdown
### 🔧 Remediation Workflow
**Recommended Approach**:
1. **Initialize TodoWrite**: Create comprehensive task list from all findings
2. **Process by Severity**: Start with CRITICAL, then HIGH, MEDIUM, LOW
3. **Apply Fixes Directly**: Modify task.json files and IMPL_PLAN.md as needed
4. **Track Progress**: Mark todos as completed after each fix
**TodoWrite Execution Pattern**:
```bash
# Step 1: Create task list from verification report
TodoWrite([
{ content: "Fix FR-03 coverage gap - add authentication task", status: "pending", activeForm: "Fixing FR-03 coverage gap" },
{ content: "Fix IMPL-1.2 consistency - align with ADR-02", status: "pending", activeForm: "Fixing IMPL-1.2 consistency" },
{ content: "Add context.artifacts to IMPL-1.2", status: "pending", activeForm: "Adding context.artifacts to IMPL-1.2" },
# ... additional todos for each finding
])
# Step 2: Process each todo systematically
# Mark as in_progress when starting
# Apply fix using Read/Edit tools
# Mark as completed when done
# Move to next priority item
```
**File Modification Workflow**:
```bash
# For task JSON modifications:
1. Read(.workflow/WFS-{session}/.task/IMPL-X.Y.json)
2. Edit() to apply fixes
3. Mark todo as completed
# For IMPL_PLAN modifications:
1. Read(.workflow/WFS-{session}/IMPL_PLAN.md)
2. Edit() to apply strategic changes
3. Mark todo as completed
```
**Note**: All fixes execute immediately after user confirmation without additional commands.

585
.claude/skills/command-guide/reference/commands/workflow/brainstorm/api-designer.md Normal file
View File

@@ -0,0 +1,585 @@
---
name: api-designer
description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🔌 **API Designer Analysis Generator**
### Purpose
**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **API Architecture**: RESTful/GraphQL design patterns and best practices
- **Endpoint Design**: Resource modeling, URL structure, and HTTP method selection
- **Data Contracts**: Request/response schemas, validation rules, and data transformation
- **API Documentation**: OpenAPI/Swagger specifications and developer experience
### Role Boundaries & Responsibilities
#### **What This Role OWNS (API Contract Within Architectural Framework)**
- **API Contract Definition**: Specific endpoint paths, HTTP methods, and status codes
- **Resource Modeling**: Mapping domain entities to RESTful resources or GraphQL types
- **Request/Response Schemas**: Detailed data contracts, validation rules, and error formats
- **API Versioning Strategy**: Version management, deprecation policies, and migration paths
- **Developer Experience**: API documentation (OpenAPI/Swagger), code examples, and SDKs
#### **What This Role DOES NOT Own (Defers to Other Roles)**
- **System Architecture Decisions**: Microservices vs monolithic, overall communication patterns → Defers to **System Architect**
- **Canonical Data Model**: Underlying data schemas and entity relationships → Defers to **Data Architect**
- **UI/Frontend Integration**: How clients consume the API → Defers to **UI Designer**
#### **Handoff Points**
- **FROM System Architect**: Receives architectural constraints (REST vs GraphQL, sync vs async) that define the design space
- **FROM Data Architect**: Receives canonical data model and translates it into public API data contracts (as projection/view)
- **TO Frontend Teams**: Provides complete API specifications, documentation, and integration guides
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Check existing analysis
CHECK: brainstorm_dir/api-designer/analysis.md
IF EXISTS:
SHOW existing analysis summary
ASK: "Analysis exists. Do you want to:"
OPTIONS:
1. "Update with new insights" → Update existing
2. "Replace completely" → Generate new
3. "Cancel" → Exit without changes
ELSE:
CREATE new analysis
```
### Phase 3: Agent Task Generation
**Framework-Based Analysis** (when guidance-specification.md exists):
```bash
Task(subagent_type="conceptual-planning-agent",
prompt="Generate API designer analysis addressing topic framework
## Framework Integration Required
**MANDATORY**: Load and address guidance-specification.md discussion points
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
**Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
## Analysis Requirements
1. **Load Topic Framework**: Read guidance-specification.md completely
2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
5. **Structured Response**: Use framework structure for analysis organization
## Framework Sections to Address
- Core Requirements (from API design perspective)
- Technical Considerations (detailed API architecture analysis)
- User Experience Factors (developer experience and API usability)
- Implementation Challenges (API design risks and solutions)
- Success Metrics (API performance metrics and adoption tracking)
## Output Structure Required
```markdown
# API Designer Analysis: [Topic]
**Framework Reference**: @../guidance-specification.md
**Role Focus**: Backend API Design and Contract Definition
## Core Requirements Analysis
[Address framework requirements from API design perspective]
## Technical Considerations
[Detailed API architecture and endpoint design analysis]
## Developer Experience Factors
[API usability, documentation, and integration ease]
## Implementation Challenges
[API design risks and mitigation strategies]
## Success Metrics
[API performance metrics, adoption rates, and developer satisfaction]
## API Design-Specific Recommendations
[Detailed API design recommendations and best practices]
```",
description="Generate API designer framework-based analysis")
```
### Phase 4: Update Mechanism
**Analysis Update Process**:
```bash
# For existing analysis updates
IF update_mode = "incremental":
Task(subagent_type="conceptual-planning-agent",
prompt="Update existing API designer analysis
## Current Analysis Context
**Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
## Update Requirements
1. **Preserve Structure**: Maintain existing analysis structure
2. **Add New Insights**: Integrate new API design insights and recommendations
3. **Framework Alignment**: Ensure continued alignment with topic framework
4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
5. **Maintain References**: Keep @../guidance-specification.md reference
## Update Instructions
- Read existing analysis completely
- Identify areas for enhancement or new insights
- Add API design depth while preserving original structure
- Update recommendations with new API design patterns and approaches
- Maintain framework discussion point addressing",
description="Update API designer analysis incrementally")
```
## Document Structure
### Output Files
```
.workflow/WFS-[topic]/.brainstorming/
├── guidance-specification.md # Input: Framework (if exists)
└── api-designer/
└── analysis.md # ★ OUTPUT: Framework-based analysis
```
### Analysis Structure
**Required Elements**:
- **Framework Reference**: @../guidance-specification.md (if framework exists)
- **Role Focus**: Backend API Design and Contract Definition perspective
- **5 Framework Sections**: Address each framework discussion point
- **API Design Recommendations**: Endpoint-specific insights and solutions
## ⚡ **Two-Step Execution Flow**
### ⚠️ Session Management - FIRST STEP
Session detection and selection:
```bash
# Check for active sessions
active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
if [ multiple_sessions ]; then
prompt_user_to_select_session()
else
use_existing_or_create_new()
fi
```
### Step 1: Context Gathering Phase
**API Designer Perspective Questioning**
Before agent assignment, gather comprehensive API design context:
#### 📋 Role-Specific Questions
1. **API Type & Architecture**
- RESTful, GraphQL, or hybrid API approach?
- Synchronous vs asynchronous communication patterns?
- Real-time requirements (WebSocket, Server-Sent Events)?
2. **Resource Modeling & Endpoints**
- What are the core domain resources/entities?
- Expected CRUD operations for each resource?
- Complex query requirements (filtering, sorting, pagination)?
3. **Data Contracts & Validation**
- Request/response data format requirements (JSON, XML, Protocol Buffers)?
- Input validation and sanitization requirements?
- Data transformation and mapping needs?
4. **API Management & Governance**
- API versioning strategy requirements?
- Authentication and authorization mechanisms?
- Rate limiting and throttling requirements?
- API documentation and developer portal needs?
5. **Integration & Compatibility**
- Client platforms consuming the API (web, mobile, third-party)?
- Backward compatibility requirements?
- External API integrations needed?
#### Context Validation
- **Minimum Response**: Each answer must be ≥50 characters
- **Re-prompting**: Insufficient detail triggers follow-up questions
- **Context Storage**: Save responses to `.brainstorming/api-designer-context.md`
### Step 2: Agent Assignment with Flow Control
**Dedicated Agent Execution**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute dedicated api-designer conceptual analysis for: {topic}
ASSIGNED_ROLE: api-designer
OUTPUT_LOCATION: .brainstorming/api-designer/
USER_CONTEXT: {validated_responses_from_context_gathering}
Flow Control Steps:
[
{
\"step\": \"load_role_template\",
\"action\": \"Load api-designer planning template\",
\"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/api-designer.md))\",
\"output_to\": \"role_template\"
}
]
Conceptual Analysis Requirements:
- Apply api-designer perspective to topic analysis
- Focus on endpoint design, data contracts, and API governance
- Use loaded role template framework for analysis structure
- Generate role-specific deliverables in designated output location
- Address all user context from questioning phase
Deliverables:
- analysis.md: Main API design analysis
- api-specification.md: Detailed endpoint specifications
- data-contracts.md: Request/response schemas and validation rules
- api-documentation.md: API documentation strategy and templates
Embody api-designer role expertise for comprehensive conceptual planning."
```
### Progress Tracking
TodoWrite tracking for two-step process:
```json
[
{"content": "Gather API designer context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
{"content": "Validate context responses and save to api-designer-context.md", "status": "pending", "activeForm": "Validating context"},
{"content": "Load api-designer planning template via flow control", "status": "pending", "activeForm": "Loading template"},
{"content": "Execute dedicated conceptual-planning-agent for api-designer role", "status": "pending", "activeForm": "Executing agent"}
]
```
## 📊 **Output Specification**
### Output Location
```
.workflow/WFS-{topic-slug}/.brainstorming/api-designer/
├── analysis.md # Primary API design analysis
├── api-specification.md # Detailed endpoint specifications (OpenAPI/Swagger)
├── data-contracts.md # Request/response schemas and validation rules
├── versioning-strategy.md # API versioning and backward compatibility plan
└── developer-guide.md # API usage documentation and integration examples
```
### Document Templates
#### analysis.md Structure
```markdown
# API Design Analysis: {Topic}
*Generated: {timestamp}*
## Executive Summary
[Key API design findings and recommendations overview]
## API Architecture Overview
### API Type Selection (REST/GraphQL/Hybrid)
### Communication Patterns
### Authentication & Authorization Strategy
## Resource Modeling
### Core Domain Resources
### Resource Relationships
### URL Structure and Naming Conventions
## Endpoint Design
### Resource Endpoints
- GET /api/v1/resources
- POST /api/v1/resources
- GET /api/v1/resources/{id}
- PUT /api/v1/resources/{id}
- DELETE /api/v1/resources/{id}
### Query Parameters
- Filtering: ?filter[field]=value
- Sorting: ?sort=field,-field2
- Pagination: ?page=1&limit=20
### HTTP Methods and Status Codes
- Success responses (2xx)
- Client errors (4xx)
- Server errors (5xx)
## Data Contracts
### Request Schemas
[JSON Schema or OpenAPI definitions]
### Response Schemas
[JSON Schema or OpenAPI definitions]
### Validation Rules
- Required fields
- Data types and formats
- Business logic constraints
## API Versioning Strategy
### Versioning Approach (URL/Header/Accept)
### Version Lifecycle Management
### Deprecation Policy
### Migration Paths
## Security & Governance
### Authentication Mechanisms
- OAuth 2.0 / JWT / API Keys
### Authorization Patterns
- RBAC / ABAC / Resource-based
### Rate Limiting & Throttling
### CORS and Security Headers
## Error Handling
### Standard Error Response Format
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": [],
"trace_id": "uuid"
}
}
```
### Error Code Taxonomy
### Validation Error Responses
## API Documentation
### OpenAPI/Swagger Specification
### Developer Portal Requirements
### Code Examples and SDKs
### Changelog and Migration Guides
## Performance Optimization
### Response Caching Strategies
### Compression (gzip, brotli)
### Field Selection (sparse fieldsets)
### Bulk Operations and Batch Endpoints
## Monitoring & Observability
### API Metrics
- Request count, latency, error rates
- Endpoint usage analytics
### Logging Strategy
### Distributed Tracing
## Developer Experience
### API Usability Assessment
### Integration Complexity
### SDK and Client Library Needs
### Sandbox and Testing Environments
```
#### api-specification.md Structure
```markdown
# API Specification: {Topic}
*OpenAPI 3.0 Specification*
## API Information
- **Title**: {API Name}
- **Version**: 1.0.0
- **Base URL**: https://api.example.com/v1
- **Contact**: api-team@example.com
## Endpoints
### Users API
#### GET /users
**Description**: Retrieve a list of users
**Parameters**:
- `page` (query, integer): Page number (default: 1)
- `limit` (query, integer): Items per page (default: 20, max: 100)
- `sort` (query, string): Sort field (e.g., "created_at", "-updated_at")
- `filter[status]` (query, string): Filter by user status
**Response 200**:
```json
{
"data": [
{
"id": "uuid",
"username": "string",
"email": "string",
"created_at": "2025-10-15T00:00:00Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 100
},
"links": {
"self": "/users?page=1",
"next": "/users?page=2",
"prev": null
}
}
```
#### POST /users
**Description**: Create a new user
**Request Body**:
```json
{
"username": "string (required, 3-50 chars)",
"email": "string (required, valid email)",
"password": "string (required, min 8 chars)",
"profile": {
"first_name": "string (optional)",
"last_name": "string (optional)"
}
}
```
**Response 201**:
```json
{
"data": {
"id": "uuid",
"username": "string",
"email": "string",
"created_at": "2025-10-15T00:00:00Z"
}
}
```
**Response 400** (Validation Error):
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
```
[Continue for all endpoints...]
## Authentication
### OAuth 2.0 Flow
1. Client requests authorization
2. User grants permission
3. Client receives access token
4. Client uses token in requests
**Header Format**:
```
Authorization: Bearer {access_token}
```
## Rate Limiting
**Headers**:
- `X-RateLimit-Limit`: 1000
- `X-RateLimit-Remaining`: 999
- `X-RateLimit-Reset`: 1634270400
**Response 429** (Too Many Requests):
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "API rate limit exceeded",
"retry_after": 3600
}
}
```
```
## 🔄 **Session Integration**
### Status Synchronization
Upon completion, update `workflow-session.json`:
```json
{
"phases": {
"BRAINSTORM": {
"api_designer": {
"status": "completed",
"completed_at": "timestamp",
"output_directory": ".workflow/WFS-{topic}/.brainstorming/api-designer/",
"key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
}
}
}
}
```
### Cross-Role Collaboration
API designer perspective provides:
- **API Contract Specifications** → Frontend Developer
- **Data Schema Requirements** → Data Architect
- **Security Requirements** → Security Expert
- **Integration Endpoints** → System Architect
- **Performance Constraints** → DevOps Engineer
## ✅ **Quality Assurance**
### Required Analysis Elements
- [ ] Complete endpoint inventory with HTTP methods and paths
- [ ] Detailed request/response schemas with validation rules
- [ ] Clear versioning strategy and backward compatibility plan
- [ ] Comprehensive error handling and status code usage
- [ ] API documentation strategy (OpenAPI/Swagger)
### API Design Principles
- [ ] **Consistency**: Uniform naming conventions and patterns across all endpoints
- [ ] **Simplicity**: Intuitive resource modeling and URL structures
- [ ] **Flexibility**: Support for filtering, sorting, pagination, and field selection
- [ ] **Security**: Proper authentication, authorization, and input validation
- [ ] **Performance**: Caching strategies, compression, and efficient data structures
### Developer Experience Validation
- [ ] API is self-documenting with clear endpoint descriptions
- [ ] Error messages are actionable and helpful for debugging
- [ ] Response formats are consistent and predictable
- [ ] Code examples and integration guides are provided
- [ ] Sandbox environment available for testing
### Technical Completeness
- [ ] **Resource Modeling**: All domain entities mapped to API resources
- [ ] **CRUD Coverage**: Complete create, read, update, delete operations
- [ ] **Query Capabilities**: Advanced filtering, sorting, and search functionality
- [ ] **Versioning**: Clear version management and migration paths
- [ ] **Monitoring**: API metrics, logging, and tracing strategies defined
### Integration Readiness
- [ ] **Client Compatibility**: API works with all target client platforms
- [ ] **External Integration**: Third-party API dependencies identified
- [ ] **Backward Compatibility**: Changes don't break existing clients
- [ ] **Migration Path**: Clear upgrade paths for API consumers
- [ ] **SDK Support**: Client libraries and code generation considered

605
.claude/skills/command-guide/reference/commands/workflow/brainstorm/artifacts.md Normal file
View File

@@ -0,0 +1,605 @@
---
name: artifacts
description: Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis
argument-hint: "topic or challenge description [--count N]"
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
---
## Overview
Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only).
**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
**Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates
**Parameters**:
- `topic` (required): Topic or challenge description (structured format recommended)
- `--count N` (optional): Number of roles user WANTS to select (system will recommend N+2 options for user to choose from, default: 3)
## Task Tracking
**⚠️ TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite)
**When called from auto-parallel**:
- Find the artifacts parent task: "Execute artifacts command for interactive framework generation"
- Mark parent task as "in_progress"
- APPEND artifacts sub-tasks AFTER the parent task (Phase 0-5)
- Mark each sub-task as it completes
- When Phase 5 completes, mark parent task as "completed"
- **PRESERVE all other auto-parallel tasks** (role agents, synthesis)
**Standalone Mode**:
```json
[
{"content": "Initialize session (.workflow/.active-* check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
{"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"},
{"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"},
{"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"},
{"content": "Phase 3: Generate 3-4 questions per role, output and wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 3 role questions"},
{"content": "Phase 4: Detect conflicts, output clarifications, wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 4 conflict resolution"},
{"content": "Phase 5: Transform Q&A to declarative statements, write guidance-specification.md", "status": "pending", "activeForm": "Phase 5 document generation"}
]
```
## User Interaction Protocol
### Question Output Format
All questions output as structured text (detailed format with descriptions):
```markdown
【问题{N} - {短标签}】{问题文本}
a) {选项标签}
说明：{选项说明和影响}
b) {选项标签}
说明：{选项说明和影响}
c) {选项标签}
说明：{选项说明和影响}
请回答：{N}a 或 {N}b 或 {N}c
```
**Multi-select format** (Phase 2 role selection):
```markdown
【角色选择】请选择 {count} 个角色参与头脑风暴分析
a) {role-name} ({中文名})
推荐理由：{基于topic的相关性说明}
b) {role-name} ({中文名})
推荐理由：{基于topic的相关性说明}
...
支持格式：
- 分别选择：2a 2c 2d (选择第2题的a、c、d选项)
- 合并语法：2acd (选择a、c、d)
- 逗号分隔：2a,c,d
请输入选择：
```
### Input Parsing Rules
**Supported formats** (intelligent parsing):
1. **Space-separated**: `1a 2b 3c` → Q1:a, Q2:b, Q3:c
2. **Comma-separated**: `1a,2b,3c` → Q1:a, Q2:b, Q3:c
3. **Multi-select combined**: `2abc` → Q2: options a,b,c
4. **Multi-select spaces**: `2 a b c` → Q2: options a,b,c
5. **Multi-select comma**: `2a,b,c` → Q2: options a,b,c
6. **Natural language**: `问题1选a` → 1a (fallback parsing)
**Parsing algorithm**:
- Extract question numbers and option letters
- Validate question numbers match output
- Validate option letters exist for each question
- If ambiguous/invalid, output example format and request re-input
**Error handling** (lenient):
- Recognize common variations automatically
- If parsing fails, show example and wait for clarification
- Support re-input without penalty
### Batching Strategy
**Batch limits**:
- **Default**: Maximum 10 questions per round
- **Phase 2 (role selection)**: Display all recommended roles at once (count+2 roles)
- **Auto-split**: If questions > 10, split into multiple rounds with clear round indicators
**Round indicators**:
```markdown
===== 第 1 轮问题 (共2轮) =====
【问题1 - ...】...
【问题2 - ...】...
...
【问题10 - ...】...
请回答 (格式: 1a 2b ... 10c)：
```
### Interaction Flow
**Standard flow**:
1. Output questions in formatted text
2. Output expected input format example
3. Wait for user input
4. Parse input with intelligent matching
5. If parsing succeeds → Store answers and continue
6. If parsing fails → Show error, example, and wait for re-input
**No question/option limits**: Text-based interaction removes previous 4-question and 4-option restrictions
## Execution Phases
### Session Management
- Check `.workflow/.active-*` markers first
- Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
- Parse `--count N` parameter from user input (default: 3 if not specified)
- Store decisions in `workflow-session.json` including count parameter
### Phase 0: Automatic Project Context Collection
**Goal**: Gather project architecture, documentation, and relevant code context BEFORE user interaction
**Detection Mechanism** (execute first):
```javascript
// Check if context-package already exists
const contextPackagePath = `.workflow/WFS-{session-id}/.process/context-package.json`;
if (file_exists(contextPackagePath)) {
// Validate package
const package = Read(contextPackagePath);
if (package.metadata.session_id === session_id) {
console.log("✅ Valid context-package found, skipping Phase 0");
return; // Skip to Phase 1
}
}
```
**Implementation**: Invoke `context-search-agent` only if package doesn't exist
```javascript
Task(
subagent_type="context-search-agent",
description="Gather project context for brainstorm",
prompt=`
You are executing as context-search-agent (.claude/agents/context-search-agent.md).
## Execution Mode
**BRAINSTORM MODE** (Lightweight) - Phase 1-2 only (skip deep analysis)
## Session Information
- **Session ID**: ${session_id}
- **Task Description**: ${task_description}
- **Output Path**: .workflow/${session_id}/.process/context-package.json
## Mission
Execute complete context-search-agent workflow for implementation planning:
### Phase 1: Initialization & Pre-Analysis
1. **Detection**: Check for existing context-package (early exit if valid)
2. **Foundation**: Initialize code-index, get project structure, load docs
3. **Analysis**: Extract keywords, determine scope, classify complexity
### Phase 2: Multi-Source Context Discovery
Execute all 3 discovery tracks:
- **Track 1**: Reference documentation (CLAUDE.md, architecture docs)
- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs)
- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
### Phase 3: Synthesis, Assessment & Packaging
1. Apply relevance scoring and build dependency graph
2. Synthesize 3-source data (docs > code > web)
3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
4. Perform conflict detection with risk assessment
5. Generate and validate context-package.json
## Output Requirements
Complete context-package.json with:
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
- **project_context**: architecture_patterns, coding_conventions, tech_stack
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
- **dependencies**: {internal[], external[]} with dependency graph
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy}
## Quality Validation
Before completion verify:
- [ ] Valid JSON format with all required fields
- [ ] File relevance accuracy >80%
- [ ] Dependency graph complete (max 2 transitive levels)
- [ ] Conflict risk level calculated correctly
- [ ] No sensitive data exposed
- [ ] Total files ≤50 (prioritize high-relevance)
Execute autonomously following agent documentation.
Report completion with statistics.
`
)
```
**Graceful Degradation**:
- If agent fails: Log warning, continue to Phase 1 without project context
- If package invalid: Re-run context-search-agent
### Phase 1: Topic Analysis & Intent Classification
**Goal**: Extract keywords/challenges to drive all subsequent question generation, **enriched by Phase 0 project context**
**Steps**:
1. **Load Phase 0 context** (if available):
- Read `.workflow/WFS-{session-id}/.process/context-package.json`
- Extract: tech_stack, existing modules, conflict_risk, relevant files
2. **Deep topic analysis** (context-aware):
- Extract technical entities from topic + existing codebase
- Identify core challenges considering existing architecture
- Consider constraints (timeline/budget/compliance)
- Define success metrics based on current project state
3. **Generate 2-4 context-aware probing questions**:
- Reference existing tech stack in questions
- Consider integration with existing modules
- Address identified conflict risks from Phase 0
- Target root challenges and trade-off priorities
4. **User interaction**: Output questions using text format (see User Interaction Protocol), wait for user input
5. **Parse user answers**: Use intelligent parsing to extract answers from user input (support multiple formats)
6. **Storage**: Store answers to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers, project_context_used}`
**Example Output**:
```markdown
===== Phase 1: 项目意图分析 =====
【问题1 - 核心挑战】实时协作平台的主要技术挑战？
a) 实时数据同步
说明：100+用户同时在线，状态同步复杂度高
b) 可扩展性架构
说明：用户规模增长时的系统扩展能力
c) 冲突解决机制
说明：多用户同时编辑的冲突处理策略
【问题2 - 优先级】MVP阶段最关注的指标？
a) 功能完整性
说明：实现所有核心功能
b) 用户体验
说明：流畅的交互体验和响应速度
c) 系统稳定性
说明：高可用性和数据一致性
请回答 (格式: 1a 2b)：
```
**User input examples**:
- `1a 2c` → Q1:a, Q2:c
- `1a,2c` → Q1:a, Q2:c
**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
### Phase 2: Role Selection
**⚠️ CRITICAL**: User MUST interact to select roles. NEVER auto-select without user confirmation.
**Available Roles**:
- data-architect (数据架构师)
- product-manager (产品经理)
- product-owner (产品负责人)
- scrum-master (敏捷教练)
- subject-matter-expert (领域专家)
- system-architect (系统架构师)
- test-strategist (测试策略师)
- ui-designer (UI 设计师)
- ux-expert (UX 专家)
**Steps**:
1. **Intelligent role recommendation** (AI analysis):
- Analyze Phase 1 extracted keywords and challenges
- Use AI reasoning to determine most relevant roles for the specific topic
- Recommend count+2 roles (e.g., if user wants 3 roles, recommend 5 options)
- Provide clear rationale for each recommended role based on topic context
2. **User selection** (text interaction):
- Output all recommended roles at once (no batching needed for count+2 roles)
- Display roles with labels and relevance rationale
- Wait for user input in multi-select format
- Parse user input (support multiple formats)
- **Storage**: Store selections to `session.selected_roles`
**Example Output**:
```markdown
===== Phase 2: 角色选择 =====
【角色选择】请选择 3 个角色参与头脑风暴分析
a) system-architect (系统架构师)
推荐理由：实时同步架构设计和技术选型的核心角色
b) ui-designer (UI设计师)
推荐理由：协作界面用户体验和实时状态展示
c) product-manager (产品经理)
推荐理由：功能优先级和MVP范围决策
d) data-architect (数据架构师)
推荐理由：数据同步模型和存储方案设计
e) ux-expert (UX专家)
推荐理由：多用户协作交互流程优化
支持格式：
- 分别选择：2a 2c 2d (选择a、c、d)
- 合并语法：2acd (选择a、c、d)
- 逗号分隔：2a,c,d (选择a、c、d)
请输入选择：
```
**User input examples**:
- `2acd` → Roles: a, c, d (system-architect, product-manager, data-architect)
- `2a 2c 2d` → Same result
- `2a,c,d` → Same result
**Role Recommendation Rules**:
- NO hardcoded keyword-to-role mappings
- Use intelligent analysis of topic, challenges, and requirements
- Consider role synergies and coverage gaps
- Explain WHY each role is relevant to THIS specific topic
- Default recommendation: count+2 roles for user to choose from
### Phase 3: Role-Specific Questions (Dynamic Generation)
**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges
**Algorithm**:
```
FOR each selected role:
1. Map Phase 1 challenges to role domain:
- "real-time sync" + system-architect → State management pattern
- "100 users" + system-architect → Communication protocol
- "low latency" + system-architect → Conflict resolution
2. Generate 3-4 questions per role probing implementation depth, trade-offs, edge cases:
Q: "How handle real-time state sync for 100+ users?" (explores approach)
Q: "How resolve conflicts when 2 users edit simultaneously?" (explores edge case)
Options: [Event Sourcing/Centralized/CRDT] (concrete, explain trade-offs for THIS use case)
3. Output questions in text format per role:
- Display all questions for current role (3-4 questions, no 10-question limit)
- Questions in Chinese (用中文提问)
- Wait for user input
- Parse answers using intelligent parsing
- Store answers to session.role_decisions[role]
```
**Batching Strategy**:
- Each role outputs all its questions at once (typically 3-4 questions)
- No need to split per role (within 10-question batch limit)
- Multiple roles processed sequentially (one role at a time for clarity)
**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format)
**Example Topic-Specific Questions** (system-architect role for "real-time collaboration platform"):
- "100+ 用户实时状态同步方案?" → Options: Event Sourcing / 集中式状态管理 / CRDT
- "两个用户同时编辑冲突如何解决?" → Options: 自动合并 / 手动解决 / 版本控制
- "低延迟通信协议选择?" → Options: WebSocket / SSE / 轮询
- "系统扩展性架构方案?" → Options: 微服务 / 单体+缓存 / Serverless
**Quality Requirements**: See "Question Generation Guidelines" section for detailed rules
### Phase 4: Cross-Role Clarification (Conflict Detection)
**Goal**: Resolve ACTUAL conflicts from Phase 3 answers, not pre-defined relationships
**Algorithm**:
```
1. Analyze Phase 3 answers for conflicts:
- Contradictory choices: product-manager "fast iteration" vs system-architect "complex Event Sourcing"
- Missing integration: ui-designer "Optimistic updates" but system-architect didn't address conflict handling
- Implicit dependencies: ui-designer "Live cursors" but no auth approach defined
2. FOR each detected conflict:
Generate clarification questions referencing SPECIFIC Phase 3 choices
3. Output clarification questions in text format:
- Batch conflicts into rounds (max 10 questions per round)
- Display questions with context from Phase 3 answers
- Questions in Chinese (用中文提问)
- Wait for user input
- Parse answers using intelligent parsing
- Store answers to session.cross_role_decisions
4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4")
```
**Batching Strategy**:
- Maximum 10 clarification questions per round
- If conflicts > 10, split into multiple rounds
- Prioritize most critical conflicts first
**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format with background context)
**Example Conflict Detection** (from Phase 3 answers):
- **Architecture Conflict**: "CRDT 与 UI 回滚期望冲突，如何解决?"
- Background: system-architect chose CRDT, ui-designer expects rollback UI
- Options: 采用 CRDT / 显示合并界面 / 切换到 OT
- **Integration Gap**: "实时光标功能缺少身份认证方案"
- Background: ui-designer chose live cursors, no auth defined
- Options: OAuth 2.0 / JWT Token / Session-based
**Quality Requirements**: See "Question Generation Guidelines" section for conflict-specific rules
### Phase 5: Generate Guidance Specification
**Steps**:
1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions`
2. Transform Q&A pairs to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
3. Generate guidance-specification.md (template below) - **PRIMARY OUTPUT FILE**
4. Update workflow-session.json with **METADATA ONLY**:
- session_id (e.g., "WFS-topic-slug")
- selected_roles[] (array of role names, e.g., ["system-architect", "ui-designer", "product-manager"])
- topic (original user input string)
- timestamp (ISO-8601 format)
- phase_completed: "artifacts"
- count_parameter (number from --count flag)
5. Validate: No interrogative sentences in .md file, all decisions traceable, no content duplication in .json
**⚠️ CRITICAL OUTPUT SEPARATION**:
- **guidance-specification.md**: Full guidance content (decisions, rationale, integration points)
- **workflow-session.json**: Session metadata ONLY (no guidance content, no decisions, no Q&A pairs)
- **NO content duplication**: Guidance stays in .md, metadata stays in .json
## Output Document Template
**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
```markdown
# [Project] - Confirmed Guidance Specification
**Metadata**: [timestamp, type, focus, roles]
## 1. Project Positioning & Goals
**CONFIRMED Objectives**: [from topic + Phase 1]
**CONFIRMED Success Criteria**: [from Phase 1 answers]
## 2-N. [Role] Decisions
### SELECTED Choices
**[Question topic]**: [User's answer]
- **Rationale**: [From option description]
- **Impact**: [Implications]
### Cross-Role Considerations
**[Conflict resolved]**: [Resolution from Phase 4]
- **Affected Roles**: [Roles involved]
## Cross-Role Integration
**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
## Risks & Constraints
**Identified Risks**: [From answers] → Mitigation: [Approach]
## Next Steps
**⚠️ Automatic Continuation** (when called from auto-parallel):
- auto-parallel will assign agents to generate role-specific analysis documents
- Each selected role gets dedicated conceptual-planning-agent
- Agents read this guidance-specification.md for framework context
## Appendix: Decision Tracking
| Decision ID | Category | Question | Selected | Phase | Rationale |
|-------------|----------|----------|----------|-------|-----------|
| D-001 | Intent | [Q] | [A] | 1 | [Why] |
| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] |
| D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
```
## Question Generation Guidelines
### Core Principle: Developer-Facing Questions with User Context
**Target Audience**: 开发者（理解技术但需要从用户需求出发）
**Generation Philosophy**:
1. **Phase 1**: 用户场景、业务约束、优先级（建立上下文）
2. **Phase 2**: 基于话题分析的智能角色推荐（非关键词映射）
3. **Phase 3**: 业务需求 + 技术选型（需求驱动的技术决策）
4. **Phase 4**: 技术冲突的业务权衡（帮助开发者理解影响）
### Universal Quality Rules
**Question Structure** (all phases):
```
[业务场景/需求前提] + [技术关注点]
```
**Option Structure** (all phases):
```
标签：[技术方案简称] + (业务特征)
说明：[业务影响] + [技术权衡]
```
**MUST Include** (all phases):
- ✅ All questions in Chinese (用中文提问)
- ✅ 业务场景作为问题前提
- ✅ 技术选项的业务影响说明
- ✅ 量化指标和约束条件
**MUST Avoid** (all phases):
- ❌ 纯技术选型无业务上下文
- ❌ 过度抽象的用户体验问题
- ❌ 脱离话题的通用架构问题
### Phase-Specific Requirements
**Phase 1 Requirements**:
- Questions MUST reference topic keywords (NOT generic "Project type?")
- Focus: 用户使用场景（谁用？怎么用？多频繁？）、业务约束（预算、时间、团队、合规）
- Success metrics: 性能指标、用户体验目标
- Priority ranking: MVP vs 长期规划
**Phase 3 Requirements**:
- Questions MUST reference Phase 1 keywords (e.g., "real-time", "100 users")
- Options MUST be concrete approaches with relevance to topic
- Each option includes trade-offs specific to this use case
- Include 业务需求驱动的技术问题、量化指标（并发数、延迟、可用性）
**Phase 4 Requirements**:
- Questions MUST reference SPECIFIC Phase 3 choices in background context
- Options address the detected conflict directly
- Each option explains impact on both conflicting roles
- NEVER use static "Cross-Role Matrix" - ALWAYS analyze actual Phase 3 answers
- Focus: 技术冲突的业务权衡、帮助开发者理解不同选择的影响
## Validation Checklist
Generated guidance-specification.md MUST:
- ✅ No interrogative sentences (use CONFIRMED/SELECTED)
- ✅ Every decision traceable to user answer
- ✅ Cross-role conflicts resolved or documented
- ✅ Next steps concrete and specific
- ✅ All Phase 1-4 decisions in session metadata
## Update Mechanism
```
IF guidance-specification.md EXISTS:
Prompt: "Regenerate completely / Update sections / Cancel"
ELSE:
Run full Phase 1-5 flow
```
## Governance Rules
**Output Requirements**:
- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections)
- Every decision MUST trace to user answer
- Conflicts MUST be resolved (not marked "TBD")
- Next steps MUST be actionable
- Topic preserved as authoritative reference in session
**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance.
## Storage Validation
**workflow-session.json** (metadata only):
```json
{
"session_id": "WFS-{topic-slug}",
"type": "brainstorming",
"topic": "{original user input}",
"selected_roles": ["system-architect", "ui-designer", "product-manager"],
"phase_completed": "artifacts",
"timestamp": "2025-10-24T10:30:00Z",
"count_parameter": 3
}
```
**⚠️ Rule**: Session JSON stores ONLY metadata (session_id, selected_roles[], topic, timestamps). All guidance content goes to guidance-specification.md.
## File Structure
```
.workflow/WFS-[topic]/
├── .active-brainstorming
├── workflow-session.json # Session metadata ONLY
└── .brainstorming/
└── guidance-specification.md # Full guidance content
```

340
.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md Normal file
View File

@@ -0,0 +1,340 @@
---
name: auto-parallel
description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives
argument-hint: "topic or challenge description" [--count N]
allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
---
# Workflow Brainstorm Parallel Auto Command
## Coordinator Role
**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
**Execution Model - Auto-Continue Workflow**:
This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
4. **Phase 3 executes** → Synthesis command → Reports final summary
**Auto-Continue Mechanism**:
- TodoList tracks current phase status
- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
- Progress updates shown at each phase for visibility
## Core Rules
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
5. **Track Progress**: Update TodoWrite after every phase completion
6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
## Usage
```bash
/workflow:brainstorm:auto-parallel "<topic>" [--count N]
```
**Recommended Structured Format**:
```bash
/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
```
**Parameters**:
- `topic` (required): Topic or challenge description (structured format recommended)
- `--count N` (optional): Number of roles to select (default: 3, max: 9)
## 3-Phase Execution
### Phase 1: Interactive Framework Generation
**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")`
**What It Does**:
- Topic analysis: Extract challenges, generate task-specific questions
- Role selection: Recommend count+2 roles, user selects via AskUserQuestion
- Role questions: Generate 3-4 questions per role, collect user decisions
- Conflict resolution: Detect and resolve cross-role conflicts
- Guidance generation: Transform Q&A to declarative guidance-specification.md
**Parse Output**:
- **⚠️ Memory Check**: If `selected_roles[]` already in conversation memory from previous load, skip file read
- Extract: `selected_roles[]` from workflow-session.json (if not in memory)
- Extract: `session_id` from workflow-session.json (if not in memory)
- Verify: guidance-specification.md exists
**Validation**:
- guidance-specification.md created with confirmed decisions
- workflow-session.json contains selected_roles[] (metadata only, no content duplication)
- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
- Marking parent task "Execute artifacts..." as in_progress
- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
- PRESERVING all other auto-parallel tasks (role agents, synthesis)
- When artifacts Phase 5 completes, marking parent task as completed
---
### Phase 2: Parallel Role Analysis Execution
**For Each Selected Role**:
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute {role-name} analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: {role-name}
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/{role}/
TOPIC: {user-provided-topic}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load {role-name} planning template
- Command: Read(~/.claude/workflows/cli-templates/planning-roles/{role}.md)
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and original user intent
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context (contains original user prompt as PRIMARY reference)
## Analysis Requirements
**Primary Reference**: Original user prompt from workflow-session.json is authoritative
**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
**Role Focus**: {role-name} domain expertise aligned with user intent
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive {role-name} analysis addressing all framework discussion points
- **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
- **FORBIDDEN**: Never use `recommendations.md` or any filename not starting with `analysis`
- **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
- **Content**: Includes both analysis AND recommendations sections within analysis files
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
3. **User Intent Alignment**: Validate analysis aligns with original user objectives from session_context
## Completion Criteria
- Address each discussion point from guidance-specification.md with {role-name} expertise
- Provide actionable recommendations from {role-name} perspective within analysis files
- All output files MUST start with `analysis` prefix (no recommendations.md or other naming)
- Reference framework document using @ notation for integration
- Update workflow-session.json with completion status
"
```
**Parallel Execution**:
- Launch N agents simultaneously (one message with multiple Task calls)
- Each agent operates independently reading same guidance-specification.md
- All agents update progress concurrently
**Input**:
- `selected_roles[]` from Phase 1
- `session_id` from Phase 1
- guidance-specification.md path
**Validation**:
- Each role creates `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
- If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
- **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing)
- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
- All N role analyses completed
**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
**After Phase 2**: Auto-continue to Phase 3 (synthesis)
---
### Phase 3: Synthesis Generation
**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")`
**What It Does**:
- Load original user intent from workflow-session.json
- Read all role analysis.md files
- Integrate role insights into synthesis-specification.md
- Validate alignment with user's original objectives
**Input**: `sessionId` from Phase 1
**Validation**:
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
- Synthesis references all role analyses
**TodoWrite**: Mark phase 3 completed
**Return to User**:
```
Brainstorming complete for session: {sessionId}
Roles analyzed: {count}
Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
✅ Next Steps:
1. /workflow:concept-clarify --session {sessionId} # Optional refinement
2. /workflow:plan --session {sessionId} # Generate implementation plan
```
## TodoWrite Pattern
```javascript
// Initialize (before Phase 1)
TodoWrite({todos: [
{"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
{"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
// Role agent tasks added dynamically after Phase 1 based on selected_roles count
{"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]})
// After Phase 1 (artifacts completes, roles loaded)
// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
TodoWrite({todos: [
{"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
{"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
{"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
{"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
{"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
{"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
// ... (N role tasks based on --count parameter)
{"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]})
// After Phase 2 (all agents launched in parallel)
TodoWrite({todos: [
// ... previous completed tasks
{"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
{"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
{"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
{"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
// ... (all N agents in_progress simultaneously)
{"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
]})
// After Phase 2 (all agents complete)
TodoWrite({todos: [
// ... previous completed tasks
{"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
{"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
{"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
{"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
]})
```
## Input Processing
**Count Parameter Parsing**:
```javascript
// Extract --count from user input
IF user_input CONTAINS "--count":
EXTRACT count_value FROM "--count N" pattern
IF count_value > 9:
count_value = 9 // Cap at maximum 9 roles
ELSE:
count_value = 3 // Default to 3 roles
// Pass to artifacts command
EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
```
**Topic Structuring**:
1. **Already Structured** → Pass directly to artifacts
```
User: "GOAL: Build platform SCOPE: 100 users CONTEXT: Real-time"
→ Pass as-is to artifacts
```
2. **Simple Text** → Pass directly (artifacts handles structuring)
```
User: "Build collaboration platform"
→ artifacts will analyze and structure
```
## Session Management
**⚡ FIRST ACTION**: Check for `.workflow/.active-*` markers before Phase 1
**Multiple Sessions Support**:
- Different Claude instances can have different active brainstorming sessions
- If multiple active sessions found, prompt user to select
- If single active session found, use it
- If no active session exists, create `WFS-[topic-slug]`
**Session Continuity**:
- MUST use selected active session for all phases
- Each role's context stored in session directory
- Session isolation: Each session maintains independent state
## Output Structure
**Phase 1 Output**:
- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
**Phase 2 Output**:
- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
**Phase 3 Output**:
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
## Available Roles
- data-architect (数据架构师)
- product-manager (产品经理)
- product-owner (产品负责人)
- scrum-master (敏捷教练)
- subject-matter-expert (领域专家)
- system-architect (系统架构师)
- test-strategist (测试策略师)
- ui-designer (UI 设计师)
- ux-expert (UX 专家)
**Role Selection**: Handled by artifacts command (intelligent recommendation + user selection)
## Error Handling
- **Role selection failure**: artifacts defaults to product-manager with explanation
- **Agent execution failure**: Agent-specific retry with minimal dependencies
- **Template loading issues**: Agent handles graceful degradation
- **Synthesis conflicts**: Synthesis highlights disagreements without resolution
## Reference Information
**File Structure**:
```
.workflow/WFS-[topic]/
├── .active-brainstorming
├── workflow-session.json # Session metadata ONLY
└── .brainstorming/
├── guidance-specification.md # Framework (Phase 1)
├── {role-1}/
│ └── analysis.md # Role analysis (Phase 2)
├── {role-2}/
│ └── analysis.md
├── {role-N}/
│ └── analysis.md
└── synthesis-specification.md # Integration (Phase 3)
```
**Template Source**: `~/.claude/workflows/cli-templates/planning-roles/`

220
.claude/skills/command-guide/reference/commands/workflow/brainstorm/data-architect.md Normal file
View File

@@ -0,0 +1,220 @@
---
name: data-architect
description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points for data architecture perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 📊 **Data Architect Analysis Generator**
### Purpose
**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **Data Model Design**: Efficient and scalable data models and schemas
- **Data Flow Design**: Data collection, processing, and storage workflows
- **Data Quality Management**: Data accuracy, completeness, and consistency
- **Analytics and Insights**: Data analysis and business intelligence solutions
### Role Boundaries & Responsibilities
#### **What This Role OWNS (Canonical Data Model - Source of Truth)**
- **Canonical Data Model**: The authoritative, system-wide data schema representing domain entities and relationships
- **Entity-Relationship Design**: Defining entities, attributes, relationships, and constraints
- **Data Normalization & Optimization**: Ensuring data integrity, reducing redundancy, and optimizing storage
- **Database Schema Design**: Physical database structures, indexes, partitioning strategies
- **Data Pipeline Architecture**: ETL/ELT processes, data warehousing, and analytics pipelines
- **Data Governance**: Data quality standards, retention policies, and compliance requirements
#### **What This Role DOES NOT Own (Defers to Other Roles)**
- **API Data Contracts**: Public-facing request/response schemas exposed by APIs → Defers to **API Designer**
- **System Integration Patterns**: How services communicate at the macro level → Defers to **System Architect**
- **UI Data Presentation**: How data is displayed to users → Defers to **UI Designer**
#### **Handoff Points**
- **TO API Designer**: Provides canonical data model that API Designer translates into public API data contracts (as projection/view)
- **TO System Architect**: Provides data flow requirements and storage constraints to inform system design
- **FROM System Architect**: Receives system-level integration requirements and scalability constraints
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute data-architect analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: data-architect
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/data-architect/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load data-architect planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/data-architect.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective
**Role Focus**: Data models, pipelines, governance, analytics platforms
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with data architecture expertise
- Provide data model designs, pipeline architectures, and governance strategies
- Include scalability, performance, and quality considerations
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute data-architect analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing data-architect framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured data-architect analysis"
},
{
content: "Update workflow-session.json with data-architect completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/data-architect/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# Data Architect Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Data Architecture perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with data architecture expertise]
### Core Requirements (from framework)
[Data architecture perspective on requirements]
### Technical Considerations (from framework)
[Data model, pipeline, and storage considerations]
### User Experience Factors (from framework)
[Data access patterns and analytics user experience]
### Implementation Challenges (from framework)
[Data migration, quality, and governance challenges]
### Success Metrics (from framework)
[Data quality metrics and analytics success criteria]
## Data Architecture Specific Recommendations
[Role-specific data architecture recommendations and solutions]
---
*Generated by data-architect analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"data_architect": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

200
.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-manager.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: product-manager
description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points for product management perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🎯 **Product Manager Analysis Generator**
### Purpose
**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Product Strategy Focus**: User needs, business value, and market positioning
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **User Needs Analysis**: Target users, problems, and value propositions
- **Business Impact Assessment**: ROI, metrics, and commercial outcomes
- **Market Positioning**: Competitive analysis and differentiation
- **Product Strategy**: Roadmaps, priorities, and go-to-market approaches
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute product-manager analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: product-manager
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-manager/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load product-manager planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/product-manager.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective
**Role Focus**: User value, business impact, market positioning, product strategy
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with product management expertise
- Provide actionable business strategies and user value propositions
- Include market analysis and competitive positioning insights
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute product-manager analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing product-manager framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured product-manager analysis"
},
{
content: "Update workflow-session.json with product-manager completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/product-manager/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# Product Manager Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Product Strategy perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with product management expertise]
### Core Requirements (from framework)
[Product strategy perspective on user needs and requirements]
### Technical Considerations (from framework)
[Business and technical feasibility considerations]
### User Experience Factors (from framework)
[User value proposition and market positioning analysis]
### Implementation Challenges (from framework)
[Business execution and go-to-market considerations]
### Success Metrics (from framework)
[Product success metrics and business KPIs]
## Product Strategy Specific Recommendations
[Role-specific product management strategies and business solutions]
---
*Generated by product-manager analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"product_manager": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

200
.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-owner.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: product-owner
description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points for product ownership perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🎯 **Product Owner Analysis Generator**
### Purpose
**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **Backlog Management**: User story creation, refinement, and prioritization
- **Stakeholder Alignment**: Requirements gathering, value definition, and expectation management
- **Feature Prioritization**: ROI analysis, MoSCoW method, and value-driven delivery
- **Acceptance Criteria**: Definition of Done, acceptance testing, and quality standards
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute product-owner analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: product-owner
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-owner/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load product-owner planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/product-owner.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective
**Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with product ownership expertise
- Provide actionable user stories and acceptance criteria definitions
- Include feature prioritization and stakeholder alignment strategies
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute product-owner analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing product-owner framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured product-owner analysis"
},
{
content: "Update workflow-session.json with product-owner completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/product-owner/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# Product Owner Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Product Backlog & Feature Prioritization perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with product ownership expertise]
### Core Requirements (from framework)
[User story formulation and backlog refinement perspective]
### Technical Considerations (from framework)
[Technical feasibility and implementation sequencing considerations]
### User Experience Factors (from framework)
[User value definition and acceptance criteria analysis]
### Implementation Challenges (from framework)
[Sprint planning, dependency management, and delivery strategies]
### Success Metrics (from framework)
[Feature adoption, value delivery metrics, and stakeholder satisfaction indicators]
## Product Owner Specific Recommendations
[Role-specific backlog management and feature prioritization strategies]
---
*Generated by product-owner analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"product_owner": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

200
.claude/skills/command-guide/reference/commands/workflow/brainstorm/scrum-master.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: scrum-master
description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points for Agile process perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🎯 **Scrum Master Analysis Generator**
### Purpose
**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **Sprint Planning**: Task breakdown, estimation, and iteration planning
- **Team Collaboration**: Communication patterns, impediment removal, and facilitation
- **Process Optimization**: Agile ceremonies, retrospectives, and continuous improvement
- **Delivery Management**: Velocity tracking, burndown analysis, and release planning
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute scrum-master analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: scrum-master
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/scrum-master/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load scrum-master planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/scrum-master.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective
**Role Focus**: Sprint planning, team dynamics, process optimization, delivery management
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with scrum mastery expertise
- Provide actionable sprint planning and team facilitation strategies
- Include process optimization and impediment removal insights
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute scrum-master analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing scrum-master framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured scrum-master analysis"
},
{
content: "Update workflow-session.json with scrum-master completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/scrum-master/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# Scrum Master Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Agile Process & Team Collaboration perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with scrum mastery expertise]
### Core Requirements (from framework)
[Sprint planning and iteration breakdown perspective]
### Technical Considerations (from framework)
[Technical debt management and process considerations]
### User Experience Factors (from framework)
[User story refinement and acceptance criteria analysis]
### Implementation Challenges (from framework)
[Impediment identification and removal strategies]
### Success Metrics (from framework)
[Velocity tracking, burndown metrics, and team performance indicators]
## Scrum Master Specific Recommendations
[Role-specific agile process optimization and team facilitation strategies]
---
*Generated by scrum-master analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"scrum_master": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

200
.claude/skills/command-guide/reference/commands/workflow/brainstorm/subject-matter-expert.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: subject-matter-expert
description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points for domain expertise perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🎯 **Subject Matter Expert Analysis Generator**
### Purpose
**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **Domain Knowledge**: Industry-specific expertise, regulatory requirements, and compliance
- **Technical Standards**: Best practices, design patterns, and architectural guidelines
- **Risk Assessment**: Technical debt, scalability concerns, and maintenance implications
- **Knowledge Transfer**: Documentation strategies, training requirements, and expertise sharing
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute subject-matter-expert analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: subject-matter-expert
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/subject-matter-expert/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load subject-matter-expert planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/subject-matter-expert.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective
**Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with subject matter expertise
- Provide actionable technical standards and best practices recommendations
- Include risk assessment and compliance considerations
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute subject-matter-expert analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing subject-matter-expert framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured subject-matter-expert analysis"
},
{
content: "Update workflow-session.json with subject-matter-expert completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/subject-matter-expert/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# Subject Matter Expert Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: Domain Expertise & Technical Standards perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with subject matter expertise]
### Core Requirements (from framework)
[Domain-specific requirements and industry standards perspective]
### Technical Considerations (from framework)
[Deep technical analysis, architectural patterns, and best practices]
### User Experience Factors (from framework)
[Domain-specific usability standards and industry conventions]
### Implementation Challenges (from framework)
[Technical risks, scalability concerns, and maintenance implications]
### Success Metrics (from framework)
[Domain-specific KPIs, compliance metrics, and quality standards]
## Subject Matter Expert Specific Recommendations
[Role-specific technical expertise and industry best practices]
---
*Generated by subject-matter-expert analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"subject_matter_expert": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

438
.claude/skills/command-guide/reference/commands/workflow/brainstorm/synthesis.md Normal file
View File

@@ -0,0 +1,438 @@
---
name: synthesis
description: Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent
argument-hint: "[optional: --session session-id]"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*)
---
## Overview
Three-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
**Phase 1-2 (Main Flow)**: Session detection → File discovery → Path preparation
**Phase 3A (Analysis Agent)**: Cross-role analysis → Generate recommendations
**Phase 4 (Main Flow)**: User selects enhancements → User answers clarifications → Build update plan
**Phase 5 (Parallel Update Agents)**: Each agent updates ONE role document → Parallel execution
**Phase 6 (Main Flow)**: Metadata update → Completion report
**Key Features**:
- Multi-agent architecture (analysis agent + parallel update agents)
- Clear separation: Agent analysis vs Main flow interaction
- Parallel document updates (one agent per role)
- User intent alignment validation
**Document Flow**:
- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata
- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
## Task Tracking
```json
[
{"content": "Detect session and validate analyses", "status": "in_progress", "activeForm": "Detecting session"},
{"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"},
{"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis agent"},
{"content": "Present enhancements for user selection", "status": "pending", "activeForm": "Presenting enhancements"},
{"content": "Generate and present clarification questions", "status": "pending", "activeForm": "Clarifying with user"},
{"content": "Build update plan from user input", "status": "pending", "activeForm": "Building update plan"},
{"content": "Execute parallel update agents (one per role)", "status": "pending", "activeForm": "Updating documents in parallel"},
{"content": "Update session metadata and generate report", "status": "pending", "activeForm": "Finalizing session"}
]
```
## Execution Phases
### Phase 1: Discovery & Validation
1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker
2. **Validate Files**:
- `guidance-specification.md` (optional, warn if missing)
- `*/analysis*.md` (required, error if empty)
3. **Load User Intent**: Extract from `workflow-session.json` (project/description field)
### Phase 2: Role Discovery & Path Preparation
**Main flow prepares file paths for Agent**:
1. **Discover Analysis Files**:
- Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)
- Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md
- Validate: At least one file exists (error if empty)
2. **Extract Role Information**:
- `role_analysis_paths`: Relative paths from brainstorm_dir
- `participating_roles`: Role names extracted from directory paths
3. **Pass to Agent** (Phase 3):
- `session_id`
- `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/
- `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...]
- `participating_roles`: ["product-manager", "system-architect", ...]
**Main Flow Responsibility**: File discovery and path preparation only (NO file content reading)
### Phase 3A: Analysis & Enhancement Agent
**First agent call**: Cross-role analysis and generate enhancement recommendations
```bash
Task(conceptual-planning-agent): "
## Agent Mission
Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations
## Input from Main Flow
- brainstorm_dir: {brainstorm_dir}
- role_analysis_paths: {role_analysis_paths}
- participating_roles: {participating_roles}
## Execution Instructions
[FLOW_CONTROL]
### Flow Control Steps
**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation:
1. **load_session_metadata**
- Action: Load original user intent as primary reference
- Command: Read({brainstorm_dir}/../workflow-session.json)
- Output: original_user_intent (from project/description field)
2. **load_role_analyses**
- Action: Load all role analysis documents
- Command: For each path in role_analysis_paths: Read({brainstorm_dir}/{path})
- Output: role_analyses_content_map = {role_name: content}
3. **cross_role_analysis**
- Action: Identify consensus themes, conflicts, gaps, underspecified areas
- Output: consensus_themes, conflicting_views, gaps_list, ambiguities
4. **generate_recommendations**
- Action: Convert cross-role analysis findings into structured enhancement recommendations
- Format: EP-001, EP-002, ... (sequential numbering)
- Fields: id, title, affected_roles, category, current_state, enhancement, rationale, priority
- Taxonomy: Map to 9 categories (User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology)
- Output: enhancement_recommendations (JSON array)
### Output to Main Flow
Return JSON array:
[
{
\"id\": \"EP-001\",
\"title\": \"API Contract Specification\",
\"affected_roles\": [\"system-architect\", \"api-designer\"],
\"category\": \"Architecture\",
\"current_state\": \"High-level API descriptions\",
\"enhancement\": \"Add detailed contract definitions with request/response schemas\",
\"rationale\": \"Enables precise implementation and testing\",
\"priority\": \"High\"
},
...
]
"
```
### Phase 4: Main Flow User Interaction
**Main flow handles all user interaction via text output**:
**⚠️ CRITICAL**: ALL questions MUST use Chinese (所有问题必须用中文) for better user understanding
1. **Present Enhancement Options** (multi-select):
```markdown
===== Enhancement 选择 =====
请选择要应用的改进建议（可多选）：
a) EP-001: API Contract Specification
影响角色：system-architect, api-designer
说明：添加详细的请求/响应 schema 定义
b) EP-002: User Intent Validation
影响角色：product-manager, ux-expert
说明：明确用户需求优先级和验收标准
c) EP-003: Error Handling Strategy
影响角色：system-architect
说明：统一异常处理和降级方案
支持格式：1abc 或 1a 1b 1c 或 1a,b,c
请输入选择（可跳过输入 skip）：
```
2. **Generate Clarification Questions** (based on analysis agent output):
- ✅ **ALL questions in Chinese (所有问题必须用中文)**
- Use 9-category taxonomy scan results
- Prioritize most critical questions (no hard limit)
- Each with 2-4 options + descriptions
3. **Interactive Clarification Loop** (max 10 questions per round):
```markdown
===== Clarification 问题 (第 1/2 轮) =====
【问题1 - 用户意图】MVP 阶段的核心目标是什么？
a) 快速验证市场需求
说明：最小功能集，快速上线获取反馈
b) 建立技术壁垒
说明：完善架构，为长期发展打基础
c) 实现功能完整性
说明：覆盖所有规划功能，延迟上线
【问题2 - 架构决策】技术栈选择的优先考虑因素？
a) 团队熟悉度
说明：使用现有技术栈，降低学习成本
b) 技术先进性
说明：采用新技术，提升竞争力
c) 生态成熟度
说明：选择成熟方案，保证稳定性
...（最多10个问题）
请回答 (格式: 1a 2b 3c...)：
```
Wait for user input → Parse all answers in batch → Continue to next round if needed
4. **Build Update Plan**:
```
update_plan = {
"role1": {
"enhancements": [EP-001, EP-003],
"clarifications": [
{"question": "...", "answer": "...", "category": "..."},
...
]
},
"role2": {
"enhancements": [EP-002],
"clarifications": [...]
},
...
}
```
### Phase 5: Parallel Document Update Agents
**Parallel agent calls** (one per role needing updates):
```bash
# Execute in parallel using single message with multiple Task calls
Task(conceptual-planning-agent): "
## Agent Mission
Apply user-confirmed enhancements and clarifications to {role1} analysis document
## Agent Intent
- **Goal**: Integrate synthesis results into role-specific analysis
- **Scope**: Update ONLY {role1}/analysis.md (isolated, no cross-role dependencies)
- **Constraints**: Preserve original insights, add refinements without deletion
## Input from Main Flow
- role: {role1}
- analysis_path: {brainstorm_dir}/{role1}/analysis.md
- enhancements: [EP-001, EP-003] (user-selected improvements)
- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
- original_user_intent: {from session metadata}
## Execution Instructions
[FLOW_CONTROL]
### Flow Control Steps
**AGENT RESPONSIBILITY**: Execute these update steps sequentially:
1. **load_current_analysis**
- Action: Load existing role analysis document
- Command: Read({brainstorm_dir}/{role1}/analysis.md)
- Output: current_analysis_content
2. **add_clarifications_section**
- Action: Insert Clarifications section with Q&A
- Format: \"## Clarifications\\n### Session {date}\\n- **Q**: {question} (Category: {category})\\n **A**: {answer}\"
- Output: analysis_with_clarifications
3. **apply_enhancements**
- Action: Integrate EP-001, EP-003 into relevant sections
- Strategy: Locate section by category (Architecture → Architecture section, UX → User Experience section)
- Output: analysis_with_enhancements
4. **resolve_contradictions**
- Action: Remove conflicts between original content and clarifications/enhancements
- Output: contradiction_free_analysis
5. **enforce_terminology_consistency**
- Action: Align all terminology with user-confirmed choices from clarifications
- Output: terminology_consistent_analysis
6. **validate_user_intent_alignment**
- Action: Verify all updates support original_user_intent
- Output: validated_analysis
7. **write_updated_file**
- Action: Save final analysis document
- Command: Write({brainstorm_dir}/{role1}/analysis.md, validated_analysis)
- Output: File update confirmation
### Output
Updated {role1}/analysis.md with Clarifications section + enhanced content
")
Task(conceptual-planning-agent): "
## Agent Mission
Apply user-confirmed enhancements and clarifications to {role2} analysis document
## Agent Intent
- **Goal**: Integrate synthesis results into role-specific analysis
- **Scope**: Update ONLY {role2}/analysis.md (isolated, no cross-role dependencies)
- **Constraints**: Preserve original insights, add refinements without deletion
## Input from Main Flow
- role: {role2}
- analysis_path: {brainstorm_dir}/{role2}/analysis.md
- enhancements: [EP-002] (user-selected improvements)
- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
- original_user_intent: {from session metadata}
## Execution Instructions
[FLOW_CONTROL]
### Flow Control Steps
**AGENT RESPONSIBILITY**: Execute same 7 update steps as {role1} agent (load → clarifications → enhancements → contradictions → terminology → validation → write)
### Output
Updated {role2}/analysis.md with Clarifications section + enhanced content
")
# ... repeat for each role in update_plan
```
**Agent Characteristics**:
- **Intent**: Integrate user-confirmed synthesis results (NOT generate new analysis)
- **Isolation**: Each agent updates exactly ONE role (parallel execution safe)
- **Context**: Minimal - receives only role-specific enhancements + clarifications
- **Dependencies**: Zero cross-agent dependencies (full parallelism)
- **Validation**: All updates must align with original_user_intent
### Phase 6: Completion & Metadata Update
**Main flow finalizes**:
1. Wait for all parallel agents to complete
2. Update workflow-session.json:
```json
{
"phases": {
"BRAINSTORM": {
"status": "clarification_completed",
"clarification_completed": true,
"completed_at": "timestamp",
"participating_roles": [...],
"clarification_results": {
"enhancements_applied": ["EP-001", "EP-002", ...],
"questions_asked": 3,
"categories_clarified": ["Architecture", "UX", ...],
"roles_updated": ["role1", "role2", ...],
"outstanding_items": []
},
"quality_metrics": {
"user_intent_alignment": "validated",
"requirement_coverage": "comprehensive",
"ambiguity_resolution": "complete",
"terminology_consistency": "enforced"
}
}
}
}
```
3. Generate completion report (show to user):
```markdown
## ✅ Clarification Complete
**Enhancements Applied**: EP-001, EP-002, EP-003
**Questions Answered**: 3/5
**Roles Updated**: role1, role2, role3
### Next Steps
✅ PROCEED: `/workflow:plan --session WFS-{session-id}`
```
## Output
**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
**Updated Structure**:
```markdown
## Clarifications
### Session {date}
- **Q**: {question} (Category: {category})
**A**: {answer}
## {Existing Sections}
{Refined content based on clarifications}
```
**Changes**:
- User intent validated/corrected
- Requirements more specific/measurable
- Architecture with rationale
- Ambiguities resolved, placeholders removed
- Consistent terminology
## Session Metadata
Update `workflow-session.json`:
```json
{
"phases": {
"BRAINSTORM": {
"status": "clarification_completed",
"clarification_completed": true,
"completed_at": "timestamp",
"participating_roles": ["product-manager", "system-architect", ...],
"clarification_results": {
"questions_asked": 3,
"categories_clarified": ["Architecture & Design", ...],
"roles_updated": ["system-architect", "ui-designer", ...],
"outstanding_items": []
},
"quality_metrics": {
"user_intent_alignment": "validated",
"requirement_coverage": "comprehensive",
"ambiguity_resolution": "complete",
"terminology_consistency": "enforced",
"decision_transparency": "documented"
}
}
}
}
```
## Quality Checklist
**Content**:
- All role analyses loaded/analyzed
- Cross-role analysis (consensus, conflicts, gaps)
- 9-category ambiguity scan
- Questions prioritized
- Clarifications documented
**Analysis**:
- User intent validated
- Cross-role synthesis complete
- Ambiguities resolved
- Correct roles updated
- Terminology consistent
- Contradictions removed
**Documents**:
- Clarifications section formatted
- Sections reflect answers
- No placeholders (TODO/TBD)
- Valid Markdown
- Cross-references maintained

387
.claude/skills/command-guide/reference/commands/workflow/brainstorm/system-architect.md Normal file
View File

@@ -0,0 +1,387 @@
---
name: system-architect
description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🏗️ **System Architect Analysis Generator**
### Purpose
**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **Architecture Focus**: Technical architecture, scalability, and system design perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **Technical Architecture**: Scalable and maintainable system design
- **Technology Selection**: Stack evaluation and architectural decisions
- **Performance & Scalability**: Capacity planning and optimization strategies
- **Integration Patterns**: System communication and data flow design
### Role Boundaries & Responsibilities
#### **What This Role OWNS (Macro-Architecture)**
- **System-Level Architecture**: Service boundaries, deployment topology, and system composition
- **Cross-Service Communication Patterns**: Choosing between microservices/monolithic, event-driven/request-response, sync/async patterns
- **Technology Stack Decisions**: Language, framework, database, and infrastructure choices
- **Non-Functional Requirements**: Scalability, performance, availability, disaster recovery, and monitoring strategies
- **Integration Planning**: How systems and services connect at the macro level (not specific API contracts)
#### **What This Role DOES NOT Own (Defers to Other Roles)**
- **API Contract Details**: Specific endpoint definitions, URL structures, HTTP methods → Defers to **API Designer**
- **Data Schemas**: Detailed data model design and entity relationships → Defers to **Data Architect**
- **UI/UX Design**: Interface design and user experience → Defers to **UX Expert** and **UI Designer**
#### **Handoff Points**
- **TO API Designer**: Provides architectural constraints (REST vs GraphQL, sync vs async) that define the API design space
- **TO Data Architect**: Provides system-level data flow requirements and integration patterns
- **FROM Data Architect**: Receives canonical data model to inform system integration design
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Check existing analysis
CHECK: brainstorm_dir/system-architect/analysis.md
IF EXISTS:
SHOW existing analysis summary
ASK: "Analysis exists. Do you want to:"
OPTIONS:
1. "Update with new insights" → Update existing
2. "Replace completely" → Generate new
3. "Cancel" → Exit without changes
ELSE:
CREATE new analysis
```
### Phase 3: Agent Task Generation
**Framework-Based Analysis** (when guidance-specification.md exists):
```bash
Task(subagent_type="conceptual-planning-agent",
prompt="Generate system architect analysis addressing topic framework
## Framework Integration Required
**MANDATORY**: Load and address guidance-specification.md discussion points
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
**Output Location**: {session.brainstorm_dir}/system-architect/analysis.md
## Analysis Requirements
1. **Load Topic Framework**: Read guidance-specification.md completely
2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective
3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions
5. **Structured Response**: Use framework structure for analysis organization
## Framework Sections to Address
- Core Requirements (from architecture perspective)
- Technical Considerations (detailed architectural analysis)
- User Experience Factors (technical UX considerations)
- Implementation Challenges (architecture risks and solutions)
- Success Metrics (technical metrics and monitoring)
## Output Structure Required
```markdown
# System Architect Analysis: [Topic]
**Framework Reference**: @../guidance-specification.md
**Role Focus**: System Architecture and Technical Design
## Core Requirements Analysis
[Address framework requirements from architecture perspective]
## Technical Considerations
[Detailed architectural analysis]
## User Experience Factors
[Technical aspects of UX implementation]
## Implementation Challenges
[Architecture risks and mitigation strategies]
## Success Metrics
[Technical metrics and system monitoring]
## Architecture-Specific Recommendations
[Detailed technical recommendations]
```",
description="Generate system architect framework-based analysis")
```
### Phase 4: Update Mechanism
**Analysis Update Process**:
```bash
# For existing analysis updates
IF update_mode = "incremental":
Task(subagent_type="conceptual-planning-agent",
prompt="Update existing system architect analysis
## Current Analysis Context
**Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md
**Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
## Update Requirements
1. **Preserve Structure**: Maintain existing analysis structure
2. **Add New Insights**: Integrate new technical insights and recommendations
3. **Framework Alignment**: Ensure continued alignment with topic framework
4. **Technical Updates**: Add new architecture patterns, technology considerations
5. **Maintain References**: Keep @../guidance-specification.md reference
## Update Instructions
- Read existing analysis completely
- Identify areas for enhancement or new insights
- Add technical depth while preserving original structure
- Update recommendations with new architectural approaches
- Maintain framework discussion point addressing",
description="Update system architect analysis incrementally")
```
## Document Structure
### Output Files
```
.workflow/WFS-[topic]/.brainstorming/
├── guidance-specification.md # Input: Framework (if exists)
└── system-architect/
└── analysis.md # ★ OUTPUT: Framework-based analysis
```
### Analysis Structure
**Required Elements**:
- **Framework Reference**: @../guidance-specification.md (if framework exists)
- **Role Focus**: System Architecture and Technical Design perspective
- **5 Framework Sections**: Address each framework discussion point
- **Technical Recommendations**: Architecture-specific insights and solutions
- How should we design APIs and manage versioning?
**4. Performance and Scalability**
- Where are the current system performance bottlenecks?
- How should we handle traffic growth and scaling demands?
- What database scaling and optimization strategies are needed?
## ⚡ **Two-Step Execution Flow**
### ⚠️ Session Management - FIRST STEP
Session detection and selection:
```bash
# Check for active sessions
active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
if [ multiple_sessions ]; then
prompt_user_to_select_session()
else
use_existing_or_create_new()
fi
```
### Step 1: Context Gathering Phase
**System Architect Perspective Questioning**
Before agent assignment, gather comprehensive system architecture context:
#### 📋 Role-Specific Questions
1. **Scale & Performance Requirements**
- Expected user load and traffic patterns?
- Performance requirements (latency, throughput)?
- Data volume and growth projections?
2. **Technical Constraints & Environment**
- Existing technology stack and constraints?
- Integration requirements with external systems?
- Infrastructure and deployment environment?
3. **Architecture Complexity & Patterns**
- Microservices vs monolithic considerations?
- Data consistency and transaction requirements?
- Event-driven vs request-response patterns?
4. **Non-Functional Requirements**
- High availability and disaster recovery needs?
- Security and compliance requirements?
- Monitoring and observability expectations?
#### Context Validation
- **Minimum Response**: Each answer must be ≥50 characters
- **Re-prompting**: Insufficient detail triggers follow-up questions
- **Context Storage**: Save responses to `.brainstorming/system-architect-context.md`
### Step 2: Agent Assignment with Flow Control
**Dedicated Agent Execution**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute dedicated system-architect conceptual analysis for: {topic}
ASSIGNED_ROLE: system-architect
OUTPUT_LOCATION: .brainstorming/system-architect/
USER_CONTEXT: {validated_responses_from_context_gathering}
Flow Control Steps:
[
{
\"step\": \"load_role_template\",
\"action\": \"Load system-architect planning template\",
\"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/system-architect.md))\",
\"output_to\": \"role_template\"
}
]
Conceptual Analysis Requirements:
- Apply system-architect perspective to topic analysis
- Focus on architectural patterns, scalability, and integration points
- Use loaded role template framework for analysis structure
- Generate role-specific deliverables in designated output location
- Address all user context from questioning phase
Deliverables:
- analysis.md: Main system architecture analysis
- recommendations.md: Architecture recommendations
- deliverables/: Architecture-specific outputs as defined in role template
Embody system-architect role expertise for comprehensive conceptual planning."
```
### Progress Tracking
TodoWrite tracking for two-step process:
```json
[
{"content": "Gather system architect context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
{"content": "Validate context responses and save to system-architect-context.md", "status": "pending", "activeForm": "Validating context"},
{"content": "Load system-architect planning template via flow control", "status": "pending", "activeForm": "Loading template"},
{"content": "Execute dedicated conceptual-planning-agent for system-architect role", "status": "pending", "activeForm": "Executing agent"}
]
```
## 📊 **Output Specification**
### Output Location
```
.workflow/WFS-{topic-slug}/.brainstorming/system-architect/
├── analysis.md # Primary architecture analysis
├── architecture-design.md # Detailed system design and diagrams
├── technology-stack.md # Technology stack recommendations and justifications
└── integration-plan.md # System integration and API strategies
```
### Document Templates
#### analysis.md Structure
```markdown
# System Architecture Analysis: {Topic}
*Generated: {timestamp}*
## Executive Summary
[Key architectural findings and recommendations overview]
## Current State Assessment
### Existing Architecture Overview
### Technical Stack Analysis
### Performance Bottlenecks
### Technical Debt Assessment
## Requirements Analysis
### Functional Requirements
### Non-Functional Requirements
- Performance: [Response time, throughput requirements]
- Scalability: [User growth, data volume expectations]
- Availability: [Uptime requirements]
- Security: [Security requirements]
## Proposed Architecture
### High-Level Architecture Design
### Component Breakdown
### Data Flow Diagrams
### Technology Stack Recommendations
## Implementation Strategy
### Migration Planning
### Risk Mitigation
### Performance Optimization
### Security Considerations
## Scalability and Maintenance
### Horizontal Scaling Strategy
### Monitoring and Observability
### Deployment Strategy
### Long-term Maintenance Plan
```
## 🔄 **Session Integration**
### Status Synchronization
Upon completion, update `workflow-session.json`:
```json
{
"phases": {
"BRAINSTORM": {
"system_architect": {
"status": "completed",
"completed_at": "timestamp",
"output_directory": ".workflow/WFS-{topic}/.brainstorming/system-architect/",
"key_insights": ["scalability_bottleneck", "architecture_pattern", "technology_recommendation"]
}
}
}
}
```
### Cross-Role Collaboration
System architect perspective provides:
- **Technical Constraints and Possibilities** → Product Manager
- **Architecture Requirements and Limitations** → UI Designer
- **Data Architecture Requirements** → Data Architect
- **Security Architecture Framework** → Security Expert
- **Technical Implementation Framework** → Feature Planner
## ✅ **Quality Assurance**
### Required Analysis Elements
- [ ] Clear architecture diagrams and component designs
- [ ] Detailed technology stack evaluation and recommendations
- [ ] Scalability and performance analysis with metrics
- [ ] System integration and API design specifications
- [ ] Comprehensive risk assessment and mitigation strategies
### Architecture Design Principles
- [ ] **Scalability**: System can handle growth in users and data
- [ ] **Maintainability**: Clear code structure, easy to modify and extend
- [ ] **Reliability**: Built-in fault tolerance and recovery mechanisms
- [ ] **Security**: Integrated security controls and protection measures
- [ ] **Performance**: Meets response time and throughput requirements
### Technical Decision Validation
- [ ] Technology choices have thorough justification and comparison analysis
- [ ] Architectural patterns align with business requirements and constraints
- [ ] Integration solutions consider compatibility and maintenance costs
- [ ] Deployment strategies are feasible with acceptable risk levels
- [ ] Monitoring and operations strategies are comprehensive and actionable
### Implementation Readiness
- [ ] **Technical Feasibility**: All proposed solutions are technically achievable
- [ ] **Resource Planning**: Resource requirements clearly defined and realistic
- [ ] **Risk Management**: Technical risks identified with mitigation plans
- [ ] **Performance Validation**: Architecture can meet performance requirements
- [ ] **Evolution Strategy**: Design allows for future growth and changes

221
.claude/skills/command-guide/reference/commands/workflow/brainstorm/ui-designer.md Normal file
View File

@@ -0,0 +1,221 @@
---
name: ui-designer
description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points for UI design perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🎨 **UI Designer Analysis Generator**
### Purpose
**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **UI/UX Focus**: User experience, interface design, and accessibility perspective
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **Visual Design**: Color palettes, typography, spacing, and visual hierarchy implementation
- **High-Fidelity Mockups**: Polished, pixel-perfect interface designs
- **Design System Implementation**: Component libraries, design tokens, and style guides
- **Micro-Interactions & Animations**: Transition effects, loading states, and interactive feedback
- **Responsive Design**: Layout adaptations for different screen sizes and devices
### Role Boundaries & Responsibilities
#### **What This Role OWNS (Concrete Visual Interface Implementation)**
- **Visual Design Language**: Colors, typography, iconography, spacing, and overall aesthetic
- **High-Fidelity Mockups**: Polished designs showing exactly how the interface will look
- **Design System Components**: Building and documenting reusable UI components (buttons, inputs, cards, etc.)
- **Design Tokens**: Defining variables for colors, spacing, typography that can be used in code
- **Micro-Interactions**: Hover states, transitions, animations, and interactive feedback details
- **Responsive Layouts**: Adapting designs for mobile, tablet, and desktop breakpoints
#### **What This Role DOES NOT Own (Defers to Other Roles)**
- **User Research & Personas**: User behavior analysis and needs assessment → Defers to **UX Expert**
- **Information Architecture**: Content structure and navigation strategy → Defers to **UX Expert**
- **Low-Fidelity Wireframes**: Structural layouts without visual design → Defers to **UX Expert**
#### **Handoff Points**
- **FROM UX Expert**: Receives wireframes, user flows, and information architecture as the foundation for visual design
- **TO Frontend Developers**: Provides design specifications, component libraries, and design tokens for implementation
- **WITH API Designer**: Coordinates on data presentation and form validation feedback (visual aspects only)
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute ui-designer analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: ui-designer
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ui-designer/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load ui-designer planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/ui-designer.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective
**Role Focus**: User experience design, interface optimization, accessibility compliance
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with UI/UX design expertise
- Provide actionable design recommendations and interface solutions
- Include accessibility considerations and WCAG compliance planning
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute ui-designer analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing ui-designer framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured ui-designer analysis"
},
{
content: "Update workflow-session.json with ui-designer completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/ui-designer/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# UI Designer Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: UI/UX Design perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with UI/UX expertise]
### Core Requirements (from framework)
[UI/UX perspective on requirements]
### Technical Considerations (from framework)
[Interface and design system considerations]
### User Experience Factors (from framework)
[Detailed UX analysis and recommendations]
### Implementation Challenges (from framework)
[Design implementation and accessibility considerations]
### Success Metrics (from framework)
[UX metrics and usability success criteria]
## UI/UX Specific Recommendations
[Role-specific design recommendations and solutions]
---
*Generated by ui-designer analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"ui_designer": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

221
.claude/skills/command-guide/reference/commands/workflow/brainstorm/ux-expert.md Normal file
View File

@@ -0,0 +1,221 @@
---
name: ux-expert
description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective
argument-hint: "optional topic - uses existing framework if available"
allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
---
## 🎯 **UX Expert Analysis Generator**
### Purpose
**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
### Core Function
- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
- **UX Design Focus**: User interface, interaction patterns, and usability optimization
- **Update Mechanism**: Create new or update existing analysis.md
- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
### Analysis Scope
- **User Research**: User personas, behavioral analysis, and needs assessment
- **Information Architecture**: Content structure, navigation hierarchy, and mental models
- **User Journey Mapping**: User flows, task analysis, and interaction models
- **Usability Strategy**: Accessibility planning, cognitive load reduction, and user testing frameworks
- **Wireframing**: Low-fidelity layouts and structural prototypes (not visual design)
### Role Boundaries & Responsibilities
#### **What This Role OWNS (Abstract User Experience & Research)**
- **User Research & Personas**: Understanding target users, their goals, pain points, and behaviors
- **Information Architecture**: Organizing content and defining navigation structures at a conceptual level
- **User Journey Mapping**: Defining user flows, task sequences, and interaction models
- **Wireframes & Low-Fidelity Prototypes**: Structural layouts showing information hierarchy (boxes and arrows, not colors/fonts)
- **Usability Testing Strategy**: Planning user testing, A/B tests, and validation methods
- **Accessibility Planning**: WCAG compliance strategy and inclusive design principles
#### **What This Role DOES NOT Own (Defers to Other Roles)**
- **Visual Design**: Colors, typography, spacing, visual style → Defers to **UI Designer**
- **High-Fidelity Mockups**: Polished, pixel-perfect designs → Defers to **UI Designer**
- **Component Implementation**: Design system components, CSS, animations → Defers to **UI Designer**
#### **Handoff Points**
- **TO UI Designer**: Provides wireframes, user flows, and information architecture that UI Designer will transform into high-fidelity visual designs
- **FROM User Research**: May receive external research data to inform UX decisions
- **TO Product Owner**: Provides user insights and validation results to inform feature prioritization
## ⚙️ **Execution Protocol**
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
framework_mode = true
load_framework = true
ELSE:
IF topic_provided:
framework_mode = false # Create analysis without framework
ELSE:
ERROR: "No framework found and no topic provided"
```
### Phase 2: Analysis Mode Detection
```bash
# Determine execution mode
IF framework_mode == true:
mode = "framework_based_analysis"
topic_ref = load_framework_topic()
discussion_points = extract_framework_points()
ELSE:
mode = "standalone_analysis"
topic_ref = provided_topic
discussion_points = generate_basic_structure()
```
### Phase 3: Agent Execution with Flow Control
**Framework-Based Analysis Generation**
```bash
Task(conceptual-planning-agent): "
[FLOW_CONTROL]
Execute ux-expert analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: ux-expert
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ux-expert/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
- Action: Load ux-expert planning template
- Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/ux-expert.md))
- Output: role_template_guidelines
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective
**Role Focus**: UI design, interaction patterns, usability optimization, design systems
**Structured Approach**: Create analysis.md addressing framework discussion points
**Template Integration**: Apply role template guidelines within framework structure
## Expected Deliverables
1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points
2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
## Completion Criteria
- Address each discussion point from guidance-specification.md with UX design expertise
- Provide actionable interface design and usability optimization strategies
- Include accessibility considerations and interaction pattern recommendations
- Reference framework document using @ notation for integration
"
```
## 📋 **TodoWrite Integration**
### Workflow Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Detect active session and locate topic framework",
status: "in_progress",
activeForm: "Detecting session and framework"
},
{
content: "Load guidance-specification.md and session metadata for context",
status: "pending",
activeForm: "Loading framework and session context"
},
{
content: "Execute ux-expert analysis using conceptual-planning-agent with FLOW_CONTROL",
status: "pending",
activeForm: "Executing ux-expert framework analysis"
},
{
content: "Generate analysis.md addressing all framework discussion points",
status: "pending",
activeForm: "Generating structured ux-expert analysis"
},
{
content: "Update workflow-session.json with ux-expert completion status",
status: "pending",
activeForm: "Updating session metadata"
}
]
});
```
## 📊 **Output Structure**
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/ux-expert/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
### Analysis Document Structure
```markdown
# UX Expert Analysis: [Topic from Framework]
## Framework Reference
**Topic Framework**: @../guidance-specification.md
**Role Focus**: User Experience & Interface Design perspective
## Discussion Points Analysis
[Address each point from guidance-specification.md with UX design expertise]
### Core Requirements (from framework)
[User interface and interaction design requirements perspective]
### Technical Considerations (from framework)
[Design system implementation and technical feasibility considerations]
### User Experience Factors (from framework)
[Usability optimization, accessibility, and user-centered design analysis]
### Implementation Challenges (from framework)
[Design implementation challenges and progressive enhancement strategies]
### Success Metrics (from framework)
[UX metrics including usability testing, user satisfaction, and design KPIs]
## UX Expert Specific Recommendations
[Role-specific interface design patterns and usability optimization strategies]
---
*Generated by ux-expert analysis addressing structured framework*
```
## 🔄 **Session Integration**
### Completion Status Update
```json
{
"ux_expert": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}
```
### Integration Points
- **Framework Reference**: @../guidance-specification.md for structured discussion points
- **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration
- **Agent Autonomy**: Independent execution with framework guidance

738
.claude/skills/command-guide/reference/commands/workflow/execute.md Normal file
View File

@@ -0,0 +1,738 @@
---
name: execute
description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking
argument-hint: "[--resume-session=\"session-id\"]"
---
# Workflow Execute Command
## Overview
Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption**, providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
**Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
## Performance Optimization Strategy
**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **Initial Load** | All task JSONs (~2,300 lines) | TODO_LIST.md only (~650 lines) | **72% reduction** |
| **Startup Time** | Seconds | Milliseconds | **~90% faster** |
| **Memory** | All tasks | 1-2 tasks | **90% less** |
| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
## Core Rules
**Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
**Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
**Auto-complete session when all tasks finished: Call `/workflow:session:complete` upon workflow completion.**
## Core Responsibilities
- **Session Discovery**: Identify and select active workflow sessions
- **Task Dependency Resolution**: Analyze task relationships and execution order
- **TodoWrite Progress Tracking**: Maintain real-time execution status throughout entire workflow
- **Agent Orchestration**: Coordinate specialized agents with complete context
- **Flow Control Execution**: Execute pre-analysis steps and context accumulation
- **Status Synchronization**: Update task JSON files and workflow state
- **Autonomous Completion**: Continue execution until all tasks complete or reach blocking state
- **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
## Execution Philosophy
- **Discovery-first**: Auto-discover existing plans and tasks
- **Status-aware**: Execute only ready tasks with resolved dependencies
- **Context-rich**: Provide complete task JSON and accumulated context to agents
- **Progress tracking**: **Continuous TodoWrite updates throughout entire workflow execution**
- **Flow control**: Sequential step execution with variable passing
- **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
## Flow Control Execution
**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
### Orchestrator Responsibility
- Pass complete task JSON to agent (including `flow_control` block)
- Provide session paths for artifact access
- Monitor agent completion
### Agent Responsibility
- Parse `flow_control.pre_analysis` array from JSON
- Execute steps sequentially with variable substitution
- Accumulate context from artifacts and dependencies
- Follow error handling per `step.on_error`
- Complete implementation using accumulated context
**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
## Execution Lifecycle
### Resume Mode Detection
**Special Flag Processing**: When `--resume-session="session-id"` is provided:
1. **Skip Discovery Phase**: Use provided session ID directly
2. **Load Specified Session**: Read session state from `.workflow/{session-id}/`
3. **Direct TodoWrite Generation**: Skip to Phase 3 (Planning) immediately
4. **Accelerated Execution**: Enter agent coordination without validation delays
### Phase 1: Discovery (Normal Mode Only)
1. **Check Active Sessions**: Find `.workflow/.active-*` markers
2. **Select Session**: If multiple found, prompt user selection
3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
4. **DO NOT read task JSONs yet** - defer until execution phase
**Note**: In resume mode, this phase is completely skipped.
### Phase 2: Planning Document Analysis (Normal Mode Only)
**Optimized to avoid reading all task JSONs upfront**
1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
2. **Read TODO_LIST.md**: Get current task statuses and execution progress
3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
**Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
**This is where resume mode directly enters after skipping Phases 1 & 2**
1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
- Parse TODO_LIST.md to extract all tasks with current statuses
- Identify first pending task with met dependencies
- Generate comprehensive TodoWrite covering entire workflow
2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
**Resume Mode Behavior**:
- Load existing TODO_LIST.md directly from `.workflow/{session-id}/`
- Extract current progress from TODO_LIST.md
- Generate TodoWrite from TODO_LIST.md state
- Proceed immediately to agent execution (Phase 4)
### Phase 4: Execution (Lazy Task Loading)
**Key Optimization**: Read task JSON **only when needed** for execution
1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
6. **Monitor Progress**: Track agent execution and handle errors without user interruption
7. **Collect Results**: Gather implementation results and outputs
8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
**Execution Loop Pattern**:
```
while (TODO_LIST.md has pending tasks) {
next_task_id = getTodoWriteInProgressTask()
task_json = Read(.workflow/{session}/.task/{next_task_id}.json) // Lazy load
executeTaskWithAgent(task_json)
updateTodoListMarkCompleted(next_task_id)
advanceTodoWriteToNextTask()
}
```
**Benefits**:
- Reduces initial context loading by ~90%
- Only reads task JSON when actually executing
- Scales better for workflows with many tasks
- Faster startup time for workflow execution
### Phase 5: Completion
1. **Update Task Status**: Mark completed tasks in JSON files
2. **Generate Summary**: Create task summary in `.summaries/`
3. **Update TodoWrite**: Mark current task complete, advance to next
4. **Synchronize State**: Update session state and workflow status
5. **Check Workflow Complete**: Verify all tasks are completed
6. **Auto-Complete Session**: Call `/workflow:session:complete` when all tasks finished
## Task Discovery & Queue Building
### Session Discovery Process (Normal Mode - Optimized)
```
├── Check for .active-* markers in .workflow/
├── If multiple active sessions found → Prompt user to select
├── Locate selected session's workflow folder
├── Load session metadata: workflow-session.json (minimal context)
├── Read IMPL_PLAN.md (strategy overview and task summary)
├── Read TODO_LIST.md (current task statuses and dependencies)
├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
├── Build execution queue from TODO_LIST.md
└── Generate TodoWrite from TODO_LIST.md state
```
**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
### Resume Mode Process (--resume-session flag - Optimized)
```
├── Use provided session-id directly (skip discovery)
├── Validate .workflow/{session-id}/ directory exists
├── Read TODO_LIST.md for current progress
├── Parse TODO_LIST.md to extract task IDs and statuses
├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
└── Enter Phase 4 (Execution) with lazy task JSON loading
```
**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
### Task Status Logic
```
pending + dependencies_met → executable
completed → skip
blocked → skip until dependencies clear
```
## Batch Execution with Dependency Graph
### Parallel Execution Algorithm
**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
#### Algorithm Steps (Optimized with Lazy Loading)
```javascript
function executeBatchWorkflow(sessionId) {
// 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
// 2. Process batches until graph is empty
while (!graph.isEmpty()) {
// 3. Identify current batch (tasks with in-degree = 0)
const batch = graph.getNodesWithInDegreeZero();
// 4. Load task JSONs ONLY for current batch (lazy loading)
const batchTaskJsons = batch.map(taskId =>
Read(`.workflow/${sessionId}/.task/${taskId}.json`)
);
// 5. Check for parallel execution opportunities
const parallelGroups = groupByExecutionGroup(batchTaskJsons);
// 6. Execute batch concurrently
await Promise.all(
parallelGroups.map(group => executeBatch(group))
);
// 7. Update graph: remove completed tasks and their edges
graph.removeNodes(batch);
// 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
updateTodoListAfterBatch(batch);
updateTodoWriteAfterBatch(batch);
}
// 9. All tasks complete - auto-complete session
SlashCommand("/workflow:session:complete");
}
function buildDependencyGraphFromTodoList(todoListPath) {
const todoContent = Read(todoListPath);
const tasks = parseTodoListTasks(todoContent);
const graph = new DirectedGraph();
tasks.forEach(task => {
graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
});
return graph;
}
function parseTodoListTasks(todoContent) {
// Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
const tasks = [];
let match;
while ((match = taskPattern.exec(todoContent)) !== null) {
tasks.push({
status: match[1] === 'x' ? 'completed' : 'pending',
id: match[2],
title: match[3]
});
}
return tasks;
}
function groupByExecutionGroup(tasks) {
const groups = {};
tasks.forEach(task => {
const groupId = task.meta.execution_group || task.id;
if (!groups[groupId]) groups[groupId] = [];
groups[groupId].push(task);
});
return Object.values(groups);
}
async function executeBatch(tasks) {
// Execute all tasks in batch concurrently
return Promise.all(
tasks.map(task => executeTask(task))
);
}
```
#### Execution Group Rules
1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
4. **Same `context_signature`** → Should have been merged (warning if not)
#### Parallel Execution Example
```
Batch 1 (no dependencies):
- IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
- IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
- IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
Wait for Batch 1 completion...
Batch 2 (depends on Batch 1):
- IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
Wait for Batch 2 completion...
Batch 3 (independent of Batch 2):
- IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
- IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
```
## TodoWrite Coordination
**Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
#### TodoWrite Workflow Rules
1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
- **Normal Mode**: Create from discovery results
- **Resume Mode**: Create from existing session state and current progress
2. **Parallel Task Support**:
- **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
- **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
3. **Immediate Updates**: Update status after each task/batch completion without user interruption
4. **Status Synchronization**: Sync with JSON task files after updates
5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
#### Resume Mode TodoWrite Generation
**Special behavior when `--resume-session` flag is present**:
- Load existing session progress from `.workflow/{session-id}/TODO_LIST.md`
- Identify currently in-progress or next pending task
- Generate TodoWrite starting from interruption point
- Preserve completed task history in TodoWrite display
- Focus on remaining pending tasks for execution
#### TodoWrite Tool Usage
**Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
```javascript
// Example 1: Sequential execution (traditional)
TodoWrite({
todos: [
{
content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
status: "in_progress", // Single task in progress
activeForm: "Executing IMPL-1.1: Design auth schema"
},
{
content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]",
status: "pending",
activeForm: "Executing IMPL-1.2: Implement auth logic"
}
]
});
// Example 2: Batch execution (parallel tasks with execution_group)
TodoWrite({
todos: [
{
content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
status: "in_progress", // Batch task 1
activeForm: "Executing IMPL-1.1: Build Auth API"
},
{
content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
status: "in_progress", // Batch task 2 (running concurrently)
activeForm: "Executing IMPL-1.2: Build User UI"
},
{
content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
status: "in_progress", // Batch task 3 (running concurrently)
activeForm: "Executing IMPL-1.3: Setup Database"
},
{
content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]",
status: "pending", // Next batch (waits for current batch completion)
activeForm: "Executing IMPL-2.1: Integration Tests"
}
]
});
// Example 3: After batch completion
TodoWrite({
todos: [
{
content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
status: "completed", // Batch completed
activeForm: "Executing IMPL-1.1: Build Auth API"
},
{
content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
status: "completed", // Batch completed
activeForm: "Executing IMPL-1.2: Build User UI"
},
{
content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
status: "completed", // Batch completed
activeForm: "Executing IMPL-1.3: Setup Database"
},
{
content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
status: "in_progress", // Next batch started
activeForm: "Executing IMPL-2.1: Integration Tests"
}
]
});
```
**TodoWrite Integration Rules**:
- **Continuous Workflow Tracking**: Use TodoWrite tool throughout entire workflow execution
- **Real-time Updates**: Immediate progress tracking without user interruption
- **Single Active Task**: Only ONE task marked as `in_progress` at any time
- **Immediate Completion**: Mark tasks `completed` immediately after finishing
- **Status Sync**: Sync TodoWrite status with JSON task files after each update
- **Full Execution**: Continue TodoWrite tracking until all workflow tasks complete
- **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
#### TODO_LIST.md Update Timing
**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
- **Before Agent Launch**: Mark task as `in_progress`
- **After Task Complete**: Mark as `completed`, advance to next
- **On Error**: Keep as `in_progress`, add error note
- **Workflow Complete**: Call `/workflow:session:complete`
### 3. Agent Context Management
**Comprehensive context preparation** for autonomous agent execution:
#### Context Sources (Priority Order)
1. **Complete Task JSON**: Full task definition including all fields and artifacts
2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
4. **Dependency Summaries**: Previous task completion summaries
5. **Session Context**: Workflow paths and session metadata
6. **Inherited Context**: Parent task context and shared variables
#### Context Assembly Process
```
1. Load Task JSON → Base context (including artifacts array)
2. Load Artifacts → Synthesis specifications and brainstorming outputs
3. Execute Flow Control → Accumulated context (with artifact loading steps)
4. Load Dependencies → Dependency context
5. Prepare Session Paths → Session context
6. Combine All → Complete agent context with artifact integration
```
#### Agent Context Package Structure
```json
{
"task": { /* Complete task JSON with artifacts array */ },
"artifacts": {
"synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
"guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
"role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
"conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
},
"flow_context": {
"step_outputs": {
"synthesis_specification": "...",
"individual_artifacts": "...",
"pattern_analysis": "...",
"dependency_context": "..."
}
},
"session": {
"workflow_dir": ".workflow/WFS-session/",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
"summaries_dir": ".workflow/WFS-session/.summaries/",
"task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
},
"dependencies": [ /* Task summaries from depends_on */ ],
"inherited": { /* Parent task context */ }
}
```
#### Context Validation Rules
- **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
- **Artifacts Available**: All artifacts loaded from context-package.json
- **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
- **Dependencies Loaded**: All depends_on summaries available
- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
- **Agent Assignment**: Valid agent type specified in meta.agent
### 4. Agent Execution Pattern
**Structured agent invocation** with complete context and clear instructions:
#### Agent Prompt Template
```bash
Task(subagent_type="{meta.agent}",
prompt="**EXECUTE TASK FROM JSON**
## Task JSON Location
{session.task_json_path}
## Instructions
1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control)
2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially:
- Load artifacts (role analysis documents, role analyses) using commands in each step
- Accumulate context from step outputs using variable substitution [variable_name]
- Handle errors per step.on_error (skip_optional | fail | retry_once)
3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context
4. **Complete Task**:
- Update task status: `jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}`
- Update TODO_LIST.md: Mark task as [x] completed in {session.todo_list_path}
- Generate summary: {session.summaries_dir}/{task.id}-summary.md
- Check workflow completion and call `/workflow:session:complete` if all tasks done
## Context Sources (All from JSON)
- Requirements: `context.requirements`
- Focus Paths: `context.focus_paths`
- Acceptance: `context.acceptance`
- Artifacts: `context.artifacts` (synthesis specs, brainstorming outputs)
- Dependencies: `context.depends_on`
- Target Files: `flow_control.target_files`
## Session Paths
- Workflow Dir: {session.workflow_dir}
- TODO List: {session.todo_list_path}
- Summaries: {session.summaries_dir}
- Flow Context: {flow_context.step_outputs}
**Complete JSON structure is authoritative - load and follow it exactly.**"),
description="Execute task: {task.id}")
```
#### Agent JSON Loading Specification
**MANDATORY AGENT PROTOCOL**: All agents must follow this exact loading sequence:
1. **JSON Loading**: First action must be `cat {session.task_json_path}`
2. **Field Validation**: Verify all 5 required fields exist: `id`, `title`, `status`, `meta`, `context`, `flow_control`
3. **Structure Parsing**: Parse nested fields correctly:
- `meta.type` and `meta.agent` (NOT flat `task_type`)
- `context.requirements`, `context.focus_paths`, `context.acceptance`
- `context.depends_on`, `context.inherited`
- `flow_control.pre_analysis` array, `flow_control.target_files`
4. **Flow Control Execution**: If `flow_control.pre_analysis` exists, execute steps sequentially
5. **Status Management**: Update JSON status upon completion
**JSON Field Reference**:
```json
{
"id": "IMPL-1.2",
"title": "Task title",
"status": "pending|active|completed|blocked",
"meta": {
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
"agent": "@code-developer|@test-fix-agent|@universal-executor"
},
"context": {
"requirements": ["req1", "req2"],
"focus_paths": ["src/path1", "src/path2"],
"acceptance": ["criteria1", "criteria2"],
"depends_on": ["IMPL-1.1"],
"inherited": { "from": "parent", "context": ["info"] },
"artifacts": [
{
"type": "synthesis_specification",
"source": "context-package.json → brainstorm_artifacts.synthesis_output",
"path": "{{loaded dynamically from context-package.json}}",
"priority": "highest",
"contains": "complete_integrated_specification"
},
{
"type": "individual_role_analysis",
"source": "context-package.json → brainstorm_artifacts.role_analyses[]",
"path": "{{loaded dynamically from context-package.json}}",
"note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
"priority": "low",
"contains": "role_specific_analysis_fallback"
}
]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_synthesis_specification",
"action": "Load synthesis specification from context-package.json",
"commands": [
"Read(.workflow/WFS-[session]/.process/context-package.json)",
"Extract(brainstorm_artifacts.synthesis_output.path)",
"Read(extracted path)"
],
"output_to": "synthesis_specification",
"on_error": "skip_optional"
},
{
"step": "step_name",
"command": "bash_command",
"output_to": "variable",
"on_error": "skip_optional|fail|retry_once"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement task following role analyses",
"description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
"modification_points": [
"Apply consolidated requirements from role analysis documents",
"Follow technical guidelines from synthesis",
"Consult artifacts for implementation details when needed",
"Integrate with existing patterns"
],
"logic_flow": [
"Load role analyses",
"Parse architecture and requirements",
"Implement following specification",
"Consult artifacts for technical details when needed",
"Validate against acceptance criteria"
],
"depends_on": [],
"output": "implementation"
}
],
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
}
}
```
#### Execution Flow
1. **Load Task JSON**: Agent reads and validates complete JSON structure
2. **Execute Flow Control**: Agent runs pre_analysis steps if present
3. **Prepare Implementation**: Agent uses implementation_approach from JSON
4. **Launch Implementation**: Agent follows focus_paths and target_files
5. **Update Status**: Agent marks JSON status as completed
6. **Generate Summary**: Agent creates completion summary
#### Agent Assignment Rules
```
meta.agent specified → Use specified agent
meta.agent missing → Infer from meta.type:
- "feature" → @code-developer
- "test-gen" → @code-developer
- "test-fix" → @test-fix-agent
- "review" → @universal-executor
- "docs" → @doc-generator
```
#### Error Handling During Execution
- **Agent Failure**: Retry once with adjusted context
- **Flow Control Error**: Skip optional steps, fail on critical
- **Context Missing**: Reload from JSON files and retry
- **Timeout**: Mark as blocked, continue with next task
## Workflow File Structure Reference
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Session state and metadata
├── IMPL_PLAN.md # Planning document and requirements
├── TODO_LIST.md # Progress tracking (auto-updated)
├── .task/ # Task definitions (JSON only)
│ ├── IMPL-1.json # Main task definitions
│ └── IMPL-1.1.json # Subtask definitions
├── .summaries/ # Task completion summaries
│ ├── IMPL-1-summary.md # Task completion details
│ └── IMPL-1.1-summary.md # Subtask completion details
└── .process/ # Planning artifacts
└── ANALYSIS_RESULTS.md # Planning analysis results
```
## Error Handling & Recovery
### Discovery Phase Errors
| Error | Cause | Resolution | Command |
|-------|-------|------------|---------|
| No active session | No `.active-*` markers found | Create or resume session | `/workflow:plan "project"` |
| Multiple sessions | Multiple `.active-*` markers | Select specific session | Manual choice prompt |
| Corrupted session | Invalid JSON files | Recreate session structure | `/workflow:session:status --validate` |
| Missing task files | Broken task references | Regenerate tasks | `/task:create` or repair |
### Execution Phase Errors
| Error | Cause | Recovery Strategy | Max Attempts |
|-------|-------|------------------|--------------|
| Agent failure | Agent crash/timeout | Retry with simplified context | 2 |
| Flow control error | Command failure | Skip optional, fail critical | 1 per step |
| Context loading error | Missing dependencies | Reload from JSON, use defaults | 3 |
| JSON file corruption | File system issues | Restore from backup/recreate | 1 |
### Recovery Procedures
#### Session Recovery
```bash
# Check session integrity
find .workflow -name ".active-*" | while read marker; do
session=$(basename "$marker" | sed 's/^\.active-//')
if [ ! -d ".workflow/$session" ]; then
echo "Removing orphaned marker: $marker"
rm "$marker"
fi
done
# Recreate corrupted session files
if [ ! -f ".workflow/$session/workflow-session.json" ]; then
echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
fi
```
#### Task Recovery
```bash
# Validate task JSON integrity
for task_file in .workflow/$session/.task/*.json; do
if ! jq empty "$task_file" 2>/dev/null; then
echo "Corrupted task file: $task_file"
# Backup and regenerate or restore from backup
fi
done
# Fix missing dependencies
missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
for dep in $missing_deps; do
if [ ! -f ".workflow/$session/.task/$dep.json" ]; then
echo "Missing dependency: $dep - creating placeholder"
fi
done
```
#### Context Recovery
```bash
# Reload context from available sources
if [ -f ".workflow/$session/.process/ANALYSIS_RESULTS.md" ]; then
echo "Reloading planning context..."
fi
# Restore from documentation if available
if [ -d ".workflow/docs/" ]; then
echo "Using documentation context as fallback..."
fi
```
### Error Prevention
- **Pre-flight Checks**: Validate session integrity before execution
- **Backup Strategy**: Create task snapshots before major operations
- **Atomic Updates**: Update JSON files atomically to prevent corruption
- **Dependency Validation**: Check all depends_on references exist
- **Context Verification**: Ensure all required context is available
## Usage Examples
### Basic Usage
```bash
/workflow:execute # Execute all pending tasks autonomously
/workflow:session:status # Check progress
/task:execute IMPL-1.2 # Execute specific task
```
### Integration
- **Planning**: `/workflow:plan` → `/workflow:execute` → `/workflow:review`
- **Recovery**: `/workflow:status --validate` → `/workflow:execute`

389
.claude/skills/command-guide/reference/commands/workflow/plan.md Normal file
View File

@@ -0,0 +1,389 @@
---
name: plan
description: 5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# Workflow Plan Command (/workflow:plan)
## Coordinator Role
**This command is a pure orchestrator**: Execute 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
**Execution Model - Auto-Continue Workflow with Quality Gate**:
This workflow runs **fully autonomously** once triggered. Phase 3 (conflict resolution) and Phase 4 (task generation) are delegated to specialized agents.
1. **User triggers**: `/workflow:plan "task"`
2. **Phase 1 executes** → Session discovery → Auto-continues
3. **Phase 2 executes** → Context gathering → Auto-continues
4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
**Auto-Continue Mechanism**:
- TodoList tracks current phase status
- After each phase completion, automatically executes next pending phase
- All phases run autonomously without user interaction (clarification handled in brainstorm phase)
- Progress updates shown at each phase for visibility
**Execution Modes**:
- **Manual Mode** (default): Use `/workflow:tools:task-generate`
- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
## Core Rules
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1
3. **Parse Every Output**: Extract required data from each command/agent output for next phase
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
5. **Track Progress**: Update TodoWrite after every phase completion
6. **Agent Delegation**: Phase 3 uses cli-execution-agent for autonomous intelligent analysis
## 5-Phase Execution
### Phase 1: Session Discovery
**Command**: `SlashCommand(command="/workflow:session:start --auto \"[structured-task-description]\"")`
**Task Description Structure**:
```
GOAL: [Clear, concise objective]
SCOPE: [What's included/excluded]
CONTEXT: [Relevant background or constraints]
```
**Example**:
```
GOAL: Build JWT-based authentication system
SCOPE: User registration, login, token validation
CONTEXT: Existing user database schema, REST API endpoints
```
**Parse Output**:
- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`)
**Validation**:
- Session ID successfully extracted
- Session directory `.workflow/[sessionId]/` exists
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
---
### Phase 2: Context Gathering
**Command**: `SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[structured-task-description]\"")`
**Use Same Structured Description**: Pass the same structured format from Phase 1
**Input**: `sessionId` from Phase 1
**Parse Output**:
- Extract: context-package.json path (store as `contextPath`)
- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
**Validation**:
- Context package path extracted
- File exists and is valid JSON
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
---
### Phase 3: Conflict Resolution (Optional - auto-triggered by conflict risk)
**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
**Input**:
- sessionId from Phase 1
- contextPath from Phase 2
- conflict_risk from context-package.json
**Parse Output**:
- Extract: Execution status (success/skipped/failed)
- Verify: CONFLICT_RESOLUTION.md file path (if executed)
**Validation**:
- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
**Skip Behavior**:
- If conflict_risk is "none" or "low", skip directly to Phase 3.5
- Display: "No significant conflicts detected, proceeding to clarification"
**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
**After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
**Memory State Check**:
- Evaluate current context window usage and memory state
- If memory usage is high (>110K tokens or approaching context limits):
- **Command**: `SlashCommand(command="/compact")`
- This optimizes memory before proceeding to Phase 3.5
- Memory compaction is particularly important after analysis phase which may generate extensive documentation
- Ensures optimal performance and prevents context overflow
---
### Phase 3.5: Pre-Task Generation Validation (Optional Quality Gate)
**Purpose**: Optional quality gate before task generation - primarily handled by brainstorm synthesis phase
**Current Behavior**: Auto-skip to Phase 4 (Task Generation)
**Future Enhancement**: Could add additional validation steps like:
- Cross-reference checks between conflict resolution and brainstorm analyses
- Final sanity checks before task generation
- User confirmation prompt for proceeding
**TodoWrite**: Mark phase 3.5 completed (auto-skip), phase 4 in_progress
**After Phase 3.5**: Auto-continue to Phase 4 immediately
---
### Phase 4: Task Generation
**Relationship with Brainstorm Phase**:
- If brainstorm role analyses exist ([role]/analysis.md files), Phase 3 analysis incorporates them as input
- **User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations
- **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights
- **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
- Task generation translates high-level role analyses into concrete, actionable work items
- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
**Command Selection**:
- Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
- Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
- CLI Execute: Add `--cli-execute` flag to either command
**Flag Combination**:
- `--cli-execute` alone: Manual task generation with CLI execution
- `--agent --cli-execute`: Agent task generation with CLI execution
**Command Examples**:
```bash
# Manual with CLI execution
/workflow:tools:task-generate --session WFS-auth --cli-execute
# Agent with CLI execution
/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
```
**Input**: `sessionId` from Phase 1
**Validation**:
- `.workflow/[sessionId]/IMPL_PLAN.md` exists
- `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
- `.workflow/[sessionId]/TODO_LIST.md` exists
**TodoWrite**: Mark phase 4 completed
**Return to User**:
```
Planning complete for session: [sessionId]
Tasks generated: [count]
Plan: .workflow/[sessionId]/IMPL_PLAN.md
Recommended Next Steps:
1. /workflow:action-plan-verify --session [sessionId] # Verify plan quality before execution
2. /workflow:status # Review task breakdown
3. /workflow:execute # Start implementation (after verification)
Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
```
## TodoWrite Pattern
```javascript
// Initialize (before Phase 1)
// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
// Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
{"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})
// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
{"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})
// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
]})
// After Phase 3 (if executed), continue to Phase 4
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
{"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
]})
```
## Input Processing
**Convert User Input to Structured Format**:
1. **Simple Text** → Structure it:
```
User: "Build authentication system"
Structured:
GOAL: Build authentication system
SCOPE: Core authentication features
CONTEXT: New implementation
```
2. **Detailed Text** → Extract components:
```
User: "Add JWT authentication with email/password login and token refresh"
Structured:
GOAL: Implement JWT-based authentication
SCOPE: Email/password login, token generation, token refresh endpoints
CONTEXT: JWT token-based security, refresh token rotation
```
3. **File Reference** (e.g., `requirements.md`) → Read and structure:
- Read file content
- Extract goal, scope, requirements
- Format into structured description
## Data Flow
```
User Input (task description)
↓
[Convert to Structured Format]
↓ Structured Description:
↓ GOAL: [objective]
↓ SCOPE: [boundaries]
↓ CONTEXT: [background]
↓
Phase 1: session:start --auto "structured-description"
↓ Output: sessionId
↓ Session Memory: Previous tasks, context, artifacts
↓
Phase 2: context-gather --session sessionId "structured-description"
↓ Input: sessionId + session memory + structured description
↓ Output: contextPath (context-package.json) + conflict_risk
↓
Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
↓ Input: sessionId + contextPath + conflict_risk
↓ CLI-powered conflict detection (JSON output)
↓ AskUserQuestion: Present conflicts + resolution strategies
↓ User selects strategies (or skip)
↓ Apply modifications via Edit tool:
↓ - Update guidance-specification.md
↓ - Update role analyses (*.md)
↓ - Mark context-package.json as "resolved"
↓ Output: Modified brainstorm artifacts (NO report file)
↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
↓
Phase 4: task-generate[--agent] --session sessionId
↓ Input: sessionId + resolved brainstorm artifacts + session memory
↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
↓
Return summary to user
```
**Session Memory Flow**: Each phase receives session ID, which provides access to:
- Previous task summaries
- Existing context and analysis
- Brainstorming artifacts (potentially modified by Phase 3)
- Session-specific configuration
**Structured Description Benefits**:
- **Clarity**: Clear separation of goal, scope, and context
- **Consistency**: Same format across all phases
- **Traceability**: Easy to track what was requested
- **Precision**: Better context gathering and analysis
## Error Handling
- **Parsing Failure**: If output parsing fails, retry command once, then report error
- **Validation Failure**: If validation fails, report which file/data is missing
- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed to next phase
## Coordinator Checklist
- **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
- Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
- Execute Phase 1 immediately with structured description
- Parse session ID from Phase 1 output, store in memory
- Pass session ID and structured description to Phase 2 command
- Parse context path from Phase 2 output, store in memory
- **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
- Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
- **Build Phase 4 command** based on flags:
- Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
- Add `--session [sessionId]`
- Add `--cli-execute` if flag present
- Pass session ID to Phase 4 command
- Verify all Phase 4 outputs
- Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
- After each phase, automatically continue to next phase based on TodoList status
## Structure Template Reference
**Minimal Structure**:
```
GOAL: [What to achieve]
SCOPE: [What's included]
CONTEXT: [Relevant info]
```
**Detailed Structure** (optional, when more context available):
```
GOAL: [Primary objective]
SCOPE: [Included features/components]
CONTEXT: [Existing system, constraints, dependencies]
REQUIREMENTS: [Specific technical requirements]
CONSTRAINTS: [Limitations or boundaries]
```
**Usage in Commands**:
```bash
# Phase 1
/workflow:session:start --auto "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
# Phase 2
/workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
```
## Related Commands
**Prerequisite Commands**:
- `/workflow:brainstorm:artifacts` - Optional: Generate role-based analyses before planning (if complex requirements need multiple perspectives)
- `/workflow:brainstorm:synthesis` - Optional: Refine brainstorm analyses with clarifications
**Called by This Command** (5 phases):
- `/workflow:session:start` - Phase 1: Create or discover workflow session
- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
- `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
- `/compact` - Phase 3: Memory optimization (if context approaching limits)
- `/workflow:tools:task-generate` - Phase 4: Generate task JSON files with manual approach
- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach (when `--agent` flag used)
**Follow-up Commands**:
- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution
- `/workflow:status` - Review task breakdown and current progress
- `/workflow:execute` - Begin implementation of generated tasks

105
.claude/skills/command-guide/reference/commands/workflow/resume.md Normal file
View File

@@ -0,0 +1,105 @@
---
name: resume
description: Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection
argument-hint: "session-id for workflow session to resume"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# Sequential Workflow Resume Command
## Usage
```bash
/workflow:resume "<session-id>"
```
## Purpose
**Sequential command coordination for workflow resumption** by first analyzing current session status, then continuing execution with special resume context. This command orchestrates intelligent session resumption through two-step process.
## Command Coordination Workflow
### Phase 1: Status Analysis
1. **Call status command**: Execute `/workflow:status` to analyze current session state
2. **Verify session information**: Check session ID, progress, and current task status
3. **Identify resume point**: Determine where workflow was interrupted
### Phase 2: Resume Execution
1. **Call execute with resume flag**: Execute `/workflow:execute --resume-session="{session-id}"`
2. **Pass session context**: Provide analyzed session information to execute command
3. **Direct agent execution**: Skip discovery phase, directly enter TodoWrite and agent execution
## Implementation Protocol
### Sequential Command Execution
```bash
# Phase 1: Analyze current session status
SlashCommand(command="/workflow:status")
# Phase 2: Resume execution with special flag
SlashCommand(command="/workflow:execute --resume-session=\"{session-id}\"")
```
### Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Analyze current session status and progress",
status: "in_progress",
activeForm: "Analyzing session status"
},
{
content: "Resume workflow execution with session context",
status: "pending",
activeForm: "Resuming workflow execution"
}
]
});
```
## Resume Information Flow
### Status Analysis Results
The `/workflow:status` command provides:
- **Session ID**: Current active session identifier
- **Current Progress**: Completed, in-progress, and pending tasks
- **Interruption Point**: Last executed task and next pending task
- **Session State**: Overall workflow status
### Execute Command Context
The special `--resume-session` flag tells `/workflow:execute`:
- **Skip Discovery**: Don't search for sessions, use provided session ID
- **Direct Execution**: Go straight to TodoWrite generation and agent launching
- **Context Restoration**: Use existing session state and summaries
- **Resume Point**: Continue from identified interruption point
## Error Handling
### Session Validation Failures
- **Session not found**: Report missing session, suggest available sessions
- **Session inactive**: Recommend activating session first
- **Status command fails**: Retry once, then report analysis failure
### Execute Resumption Failures
- **No pending tasks**: Report workflow completion status
- **Execute command fails**: Report resumption failure, suggest manual intervention
## Success Criteria
1. **Status analysis complete**: Session state properly analyzed and reported
2. **Execute command launched**: Resume execution started with proper context
3. **Agent coordination**: TodoWrite and agent execution initiated successfully
4. **Context preservation**: Session state and progress properly maintained
## Related Commands
**Prerequisite Commands**:
- `/workflow:plan` or `/workflow:execute` - Workflow must be in progress or paused
**Called by This Command** (2 phases):
- `/workflow:status` - Phase 1: Analyze current session status and identify resume point
- `/workflow:execute` - Phase 2: Resume execution with `--resume-session` flag
**Follow-up Commands**:
- None - Workflow continues automatically via `/workflow:execute`
---
*Sequential command coordination for workflow session resumption*

258
.claude/skills/command-guide/reference/commands/workflow/review.md Normal file
View File

@@ -0,0 +1,258 @@
---
name: review
description: Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini
argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
---
## Command Overview: /workflow:review
**Optional specialized review** for completed implementations. In the standard workflow, **passing tests = approved code**. Use this command only when specialized review is required (security, architecture, compliance, docs).
## Philosophy: "Tests Are the Review"
- **Default**: All tests pass -> Code approved
- **Optional**: Specialized reviews for:
- Security audits (vulnerabilities, auth/authz)
- Architecture compliance (patterns, technical debt)
- Action items verification (requirements met, acceptance criteria)
## Review Types
| Type | Focus | Use Case |
|------|-------|----------|
| `quality` | Code quality, best practices, maintainability | Default general review |
| `security` | Security vulnerabilities, data handling, access control | Security audits |
| `architecture` | Architectural patterns, technical debt, design decisions | Architecture compliance |
| `action-items` | Requirements met, acceptance criteria verified, action items completed | Pre-deployment verification |
**Notes**:
- For documentation generation, use `/workflow:tools:docs`
- For CLAUDE.md updates, use `/update-memory-related`
## Execution Template
```bash
#!/bin/bash
# Optional specialized review for completed implementation
# Step 1: Session ID resolution
if [ -n "$SESSION_ARG" ]; then
sessionId="$SESSION_ARG"
else
sessionId=$(find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//')
fi
# Step 2: Validation
if [ ! -d ".workflow/${sessionId}" ]; then
echo "Session ${sessionId} not found"
exit 1
fi
# Check for completed tasks
if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
echo "No completed implementation found. Complete implementation first"
exit 1
fi
# Step 3: Determine review type (default: quality)
review_type="${TYPE_ARG:-quality}"
# Redirect docs review to specialized command
if [ "$review_type" = "docs" ]; then
echo "For documentation generation, please use:"
echo " /workflow:tools:docs"
echo ""
echo "The docs command provides:"
echo " - Hierarchical architecture documentation"
echo " - API documentation generation"
echo " - Documentation structure analysis"
exit 0
fi
# Step 4: Analysis handover → Model takes control
# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
```
### Model Analysis Phase
After bash validation, the model takes control to:
1. **Load Context**: Read completed task summaries and changed files
```bash
# Load implementation summaries
cat .workflow/${sessionId}/.summaries/IMPL-*.md
# Load test results (if available)
cat .workflow/${sessionId}/.summaries/TEST-FIX-*.md 2>/dev/null
# Get changed files
git log --since="$(cat .workflow/${sessionId}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
```
2. **Perform Specialized Review**: Based on `review_type`
**Security Review** (`--type=security`):
- Use ripgrep for security patterns:
```bash
rg "password|token|secret|auth" -g "*.{ts,js,py}"
rg "eval|exec|innerHTML|dangerouslySetInnerHTML" -g "*.{ts,js,tsx}"
```
- Use Gemini for security analysis:
```bash
cd .workflow/${sessionId} && gemini -p "
PURPOSE: Security audit of completed implementation
TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: Security findings report with severity levels
RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
" --approval-mode yolo
```
**Architecture Review** (`--type=architecture`):
- Use Qwen for architecture analysis:
```bash
cd .workflow/${sessionId} && qwen -p "
PURPOSE: Architecture compliance review
TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: Architecture assessment with recommendations
RULES: Check for patterns, separation of concerns, modularity, scalability
" --approval-mode yolo
```
**Quality Review** (`--type=quality`):
- Use Gemini for code quality:
```bash
cd .workflow/${sessionId} && gemini -p "
PURPOSE: Code quality and best practices review
TASK: Assess code readability, maintainability, adherence to best practices
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED: Quality assessment with improvement suggestions
RULES: Check for code smells, duplication, complexity, naming conventions
" --approval-mode yolo
```
**Action Items Review** (`--type=action-items`):
- Verify all requirements and acceptance criteria met:
```bash
# Load task requirements and acceptance criteria
find .workflow/${sessionId}/.task -name "IMPL-*.json" -exec jq -r '
"Task: " + .id + "\n" +
"Requirements: " + (.context.requirements | join(", ")) + "\n" +
"Acceptance: " + (.context.acceptance | join(", "))
' {} \;
# Check implementation summaries against requirements
cd .workflow/${sessionId} && gemini -p "
PURPOSE: Verify all requirements and acceptance criteria are met
TASK: Cross-check implementation summaries against original requirements
CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
EXPECTED:
- Requirements coverage matrix
- Acceptance criteria verification
- Missing/incomplete action items
- Pre-deployment readiness assessment
RULES:
- Check each requirement has corresponding implementation
- Verify all acceptance criteria are met
- Flag any incomplete or missing action items
- Assess deployment readiness
" --approval-mode yolo
```
3. **Generate Review Report**: Create structured report
```markdown
# Review Report: ${review_type}
**Session**: ${sessionId}
**Date**: $(date)
**Type**: ${review_type}
## Summary
- Tasks Reviewed: [count IMPL tasks]
- Files Changed: [count files]
- Severity: [High/Medium/Low]
## Findings
### Critical Issues
- [Issue 1 with file:line reference]
- [Issue 2 with file:line reference]
### Recommendations
- [Recommendation 1]
- [Recommendation 2]
### Positive Observations
- [Good pattern observed]
## Action Items
- [ ] [Action 1]
- [ ] [Action 2]
```
4. **Output Files**:
```bash
# Save review report
Write(.workflow/${sessionId}/REVIEW-${review_type}.md)
# Update session metadata
# (optional) Update workflow-session.json with review status
```
5. **Optional: Update Memory** (if docs review or significant findings):
```bash
# If architecture or quality issues found, suggest memory update
if [ "$review_type" = "architecture" ] || [ "$review_type" = "quality" ]; then
echo "Consider updating project documentation:"
echo " /update-memory-related"
fi
```
## Usage Examples
```bash
# General quality review after implementation
/workflow:review
# Security audit before deployment
/workflow:review --type=security
# Architecture review for specific session
/workflow:review --type=architecture WFS-payment-integration
# Documentation review
/workflow:review --type=docs
```
## Features
- **Simple Validation**: Check session exists and has completed tasks
- **No Complex Orchestration**: Direct analysis, no multi-phase pipeline
- **Specialized Reviews**: Different prompts and tools for different review types
- **MCP Integration**: Fast code search for security and architecture patterns
- **CLI Tool Integration**: Gemini for analysis, Qwen for architecture
- **Structured Output**: Markdown reports with severity levels and action items
- **Optional Memory Update**: Suggests documentation updates for significant findings
## Integration with Workflow
```
Standard Workflow:
plan -> execute -> test-gen -> execute (complete)
Optional Review (when needed):
plan -> execute -> test-gen -> execute -> review (security/architecture/docs)
```
**When to Use**:
- Before production deployment (security review + action-items review)
- After major feature (architecture review)
- Before code freeze (quality review)
- Pre-deployment verification (action-items review)
**When NOT to Use**:
- Regular development (tests are sufficient)
- Simple bug fixes (test-fix-agent handles it)
- Minor changes (update-memory-related is enough)

147
.claude/skills/command-guide/reference/commands/workflow/session/complete.md Normal file
View File

@@ -0,0 +1,147 @@
---
name: complete
description: Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag
examples:
- /workflow:session:complete
- /workflow:session:complete --detailed
---
# Complete Workflow Session (/workflow:session:complete)
## Overview
Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
## Usage
```bash
/workflow:session:complete # Complete current active session
/workflow:session:complete --detailed # Show detailed completion summary
```
## Implementation Flow
### Phase 1: Prepare for Archival (Minimal Manual Operations)
**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
#### Step 1.1: Find Active Session and Get Name
```bash
# Find active marker
bash(find .workflow/ -name ".active-*" -type f | head -1)
# Extract session name from marker path
bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
```
**Output**: Session name `WFS-session-name`
#### Step 1.2: Move Session to Archive
```bash
# Create archive directory if needed
bash(mkdir -p .workflow/.archives/)
# Move session to archive location
bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
```
**Result**: Session now at `.workflow/.archives/WFS-session-name/`
### Phase 2: Agent-Orchestrated Completion (All Data Processing)
**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
#### Agent Invocation
Invoke `universal-executor` agent to complete the archival process.
**Agent Task**:
```
Task(
subagent_type="universal-executor",
description="Complete session archival",
prompt=`
Complete workflow session archival. Session already moved to archive location.
## Context
- Session: .workflow/.archives/WFS-session-name/
- Active marker: .workflow/.active-WFS-session-name
## Tasks
1. **Extract session data** from workflow-session.json (session_id, description/topic, started_at/timestamp, completed_at, status)
- If status != "completed", update it with timestamp
2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt (fallback: analyze files directly)
- Return: {successes, challenges, watch_patterns}
4. **Build archive entry**:
- Calculate: duration_hours, success_rate, tags (3-5 keywords)
- Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons
5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
6. **Remove active marker**
7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
## Error Handling
- On failure: return {"status": "error", "task": "...", "message": "..."}
- Do NOT remove marker if failed
`
)
```
**Expected Output**:
- Agent returns JSON result confirming successful archival
- Display completion summary to user based on agent response
## Workflow Execution Strategy
### Two-Phase Approach (Optimized)
**Phase 1: Minimal Manual Setup** (2 simple operations)
- Find active session and extract name
- Move session to archive location
- **No data extraction** - agent handles all data processing
- **No counting** - agent does this from archive location
- **Total**: 2 bash commands (find + move)
**Phase 2: Agent-Driven Completion** (1 agent invocation)
- Extract all session data from archived location
- Count tasks and summaries
- Generate lessons learned analysis
- Build complete archive metadata
- Update manifest
- Remove active marker
- Return success/error result
## Quick Commands
```bash
# Phase 1: Find and move
bash(find .workflow/ -name ".active-*" -type f | head -1)
bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
bash(mkdir -p .workflow/.archives/)
bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
# Phase 2: Agent completes archival
Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
```
## Archive Query Commands
After archival, you can query the manifest:
```bash
# List all archived sessions
jq '.archives[].session_id' .workflow/.archives/manifest.json
# Find sessions by keyword
jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
# Get specific session details
jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
# List all watch patterns across sessions
jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
```

99
.claude/skills/command-guide/reference/commands/workflow/session/list.md Normal file
View File

@@ -0,0 +1,99 @@
---
name: list
description: List all workflow sessions with status filtering, shows session metadata and progress information
examples:
- /workflow:session:list
---
# List Workflow Sessions (/workflow:session:list)
## Overview
Display all workflow sessions with their current status, progress, and metadata.
## Usage
```bash
/workflow:session:list # Show all sessions with status
```
## Implementation Flow
### Step 1: Find All Sessions
```bash
ls .workflow/WFS-* 2>/dev/null
```
### Step 2: Check Active Session
```bash
ls .workflow/.active-* 2>/dev/null | head -1
```
### Step 3: Read Session Metadata
```bash
jq -r '.session_id, .status, .project' .workflow/WFS-session/workflow-session.json
```
### Step 4: Count Task Progress
```bash
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
```
### Step 5: Get Creation Time
```bash
jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
```
## Simple Bash Commands
### Basic Operations
- **List sessions**: `find .workflow/ -maxdepth 1 -type d -name "WFS-*"`
- **Find active**: `find .workflow/ -name ".active-*" -type f`
- **Read session data**: `jq -r '.session_id, .status' session.json`
- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
- **Get timestamp**: `jq -r '.created_at' session.json`
## Simple Output Format
### Session List Display
```
Workflow Sessions:
[ACTIVE] WFS-oauth-integration
Project: OAuth2 authentication system
Status: active
Progress: 3/8 tasks completed
Created: 2025-09-15T10:30:00Z
[PAUSED] WFS-user-profile
Project: User profile management
Status: paused
Progress: 1/5 tasks completed
Created: 2025-09-14T14:15:00Z
[COMPLETED] WFS-database-migration
Project: Database schema migration
Status: completed
Progress: 4/4 tasks completed
Created: 2025-09-13T09:00:00Z
Total: 3 sessions (1 active, 1 paused, 1 completed)
```
### Status Indicators
- **[ACTIVE]**: Active session
- **[PAUSED]**: Paused session
- **[COMPLETED]**: Completed session
- **[ERROR]**: Error/corrupted session
### Quick Commands
```bash
# Count all sessions
ls .workflow/WFS-* | wc -l
# Show only active
ls .workflow/.active-* | basename | sed 's/^\.active-//'
# Show recent sessions
ls -t .workflow/WFS-*/workflow-session.json | head -3
```

67
.claude/skills/command-guide/reference/commands/workflow/session/resume.md Normal file
View File

@@ -0,0 +1,67 @@
---
name: resume
description: Resume the most recently paused workflow session with automatic session discovery and status update
---
# Resume Workflow Session (/workflow:session:resume)
## Overview
Resume the most recently paused workflow session, restoring all context and state.
## Usage
```bash
/workflow:session:resume # Resume most recent paused session
```
## Implementation Flow
### Step 1: Find Paused Sessions
```bash
ls .workflow/WFS-* 2>/dev/null
```
### Step 2: Check Session Status
```bash
jq -r '.status' .workflow/WFS-session/workflow-session.json
```
### Step 3: Find Most Recent Paused
```bash
ls -t .workflow/WFS-*/workflow-session.json | head -1
```
### Step 4: Update Session Status
```bash
jq '.status = "active"' .workflow/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/WFS-session/workflow-session.json
```
### Step 5: Add Resume Timestamp
```bash
jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/WFS-session/workflow-session.json
```
### Step 6: Create Active Marker
```bash
touch .workflow/.active-WFS-session-name
```
## Simple Bash Commands
### Basic Operations
- **List sessions**: `ls .workflow/WFS-*`
- **Check status**: `jq -r '.status' session.json`
- **Find recent**: `ls -t .workflow/*/workflow-session.json | head -1`
- **Update status**: `jq '.status = "active"' session.json > temp.json`
- **Add timestamp**: `jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
- **Create marker**: `touch .workflow/.active-session`
### Resume Result
```
Session WFS-user-auth resumed
- Status: active
- Paused at: 2025-09-15T14:30:00Z
- Resumed at: 2025-09-15T15:45:00Z
- Ready for: /workflow:execute
```

215
.claude/skills/command-guide/reference/commands/workflow/session/start.md Normal file
View File

@@ -0,0 +1,215 @@
---
name: start
description: Discover existing sessions or start new workflow session with intelligent session management and conflict detection
argument-hint: [--auto|--new] [optional: task description for new session]
examples:
- /workflow:session:start
- /workflow:session:start --auto "implement OAuth2 authentication"
- /workflow:session:start --new "fix login bug"
---
# Start Workflow Session (/workflow:session:start)
## Overview
Manages workflow sessions with three operation modes: discovery (manual), auto (intelligent), and force-new.
## Mode 1: Discovery Mode (Default)
### Usage
```bash
/workflow:session:start
```
### Step 1: Check Active Sessions
```bash
bash(ls .workflow/.active-* 2>/dev/null)
```
### Step 2: List All Sessions
```bash
bash(ls -1 .workflow/WFS-* 2>/dev/null | head -5)
```
### Step 3: Display Session Metadata
```bash
bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json)
```
### Step 4: User Decision
Present session information and wait for user to select or create session.
**Output**: `SESSION_ID: WFS-[user-selected-id]`
## Mode 2: Auto Mode (Intelligent)
### Usage
```bash
/workflow:session:start --auto "task description"
```
### Step 1: Check Active Sessions Count
```bash
bash(ls .workflow/.active-* 2>/dev/null | wc -l)
```
### Step 2a: No Active Sessions → Create New
```bash
# Generate session slug
bash(echo "implement OAuth2 auth" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
# Create directory structure
bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.process)
bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.task)
bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.summaries)
# Create metadata
bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/WFS-implement-oauth2-auth/workflow-session.json)
# Mark as active
bash(touch .workflow/.active-WFS-implement-oauth2-auth)
```
**Output**: `SESSION_ID: WFS-implement-oauth2-auth`
### Step 2b: Single Active Session → Check Relevance
```bash
# Extract session ID
bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.active-//')
# Read project name from metadata
bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
# Check keyword match (manual comparison)
# If task contains project keywords → Reuse session
# If task unrelated → Create new session (use Step 2a)
```
**Output (reuse)**: `SESSION_ID: WFS-promptmaster-platform`
**Output (new)**: `SESSION_ID: WFS-[new-slug]`
### Step 2c: Multiple Active Sessions → Use First
```bash
# Get first active session
bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.active-//')
# Output warning and session ID
# WARNING: Multiple active sessions detected
# SESSION_ID: WFS-first-session
```
## Mode 3: Force New Mode
### Usage
```bash
/workflow:session:start --new "task description"
```
### Step 1: Generate Unique Session Slug
```bash
# Convert to slug
bash(echo "fix login bug" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
# Check if exists, add counter if needed
bash(ls .workflow/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
```
### Step 2: Create Session Structure
```bash
bash(mkdir -p .workflow/WFS-fix-login-bug/.process)
bash(mkdir -p .workflow/WFS-fix-login-bug/.task)
bash(mkdir -p .workflow/WFS-fix-login-bug/.summaries)
```
### Step 3: Create Metadata
```bash
bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/WFS-fix-login-bug/workflow-session.json)
```
### Step 4: Mark Active and Clean Old Markers
```bash
bash(rm .workflow/.active-* 2>/dev/null)
bash(touch .workflow/.active-WFS-fix-login-bug)
```
**Output**: `SESSION_ID: WFS-fix-login-bug`
## Output Format Specification
### Success
```
SESSION_ID: WFS-session-slug
```
### Error
```
ERROR: --auto mode requires task description
ERROR: Failed to create session directory
```
### Analysis (Auto Mode)
```
ANALYSIS: Task relevance = high
DECISION: Reusing existing session
SESSION_ID: WFS-promptmaster-platform
```
## Command Integration
### For /workflow:plan (Use Auto Mode)
```bash
SlashCommand(command="/workflow:session:start --auto \"implement OAuth2 authentication\"")
# Parse session ID from output
grep "^SESSION_ID:" | awk '{print $2}'
```
### For Interactive Workflows (Use Discovery Mode)
```bash
SlashCommand(command="/workflow:session:start")
```
### For New Isolated Work (Use Force New Mode)
```bash
SlashCommand(command="/workflow:session:start --new \"experimental feature\"")
```
## Simple Bash Commands
### Basic Operations
```bash
# Check active sessions
bash(ls .workflow/.active-*)
# List all sessions
bash(ls .workflow/WFS-*)
# Read session metadata
bash(cat .workflow/WFS-[session-id]/workflow-session.json)
# Create session directories
bash(mkdir -p .workflow/WFS-[session-id]/.process)
bash(mkdir -p .workflow/WFS-[session-id]/.task)
bash(mkdir -p .workflow/WFS-[session-id]/.summaries)
# Mark session as active
bash(touch .workflow/.active-WFS-[session-id])
# Clean active markers
bash(rm .workflow/.active-*)
```
### Generate Session Slug
```bash
bash(echo "Task Description" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
```
### Create Metadata JSON
```bash
bash(echo '{"session_id":"WFS-test","project":"test project","status":"planning"}' > .workflow/WFS-test/workflow-session.json)
```
## Session ID Format
- Pattern: `WFS-[lowercase-slug]`
- Characters: `a-z`, `0-9`, `-` only
- Max length: 50 characters
- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)

119
.claude/skills/command-guide/reference/commands/workflow/status.md Normal file
View File

@@ -0,0 +1,119 @@
---
name: workflow:status
description: Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view
argument-hint: "[optional: task-id]"
---
# Workflow Status Command (/workflow:status)
## Overview
Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files.
## Usage
```bash
/workflow:status # Show current workflow overview
/workflow:status impl-1 # Show specific task details
/workflow:status --validate # Validate workflow integrity
```
## Implementation Flow
### Step 1: Find Active Session
```bash
find .workflow/ -name ".active-*" -type f 2>/dev/null | head -1
```
### Step 2: Load Session Data
```bash
cat .workflow/WFS-session/workflow-session.json
```
### Step 3: Scan Task Files
```bash
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
```
### Step 4: Generate Task Status
```bash
cat .workflow/WFS-session/.task/impl-1.json | jq -r '.status'
```
### Step 5: Count Task Progress
```bash
find .workflow/WFS-session/.task/ -name "*.json" -type f | wc -l
find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
```
### Step 6: Display Overview
```markdown
# Workflow Overview
**Session**: WFS-session-name
**Progress**: 3/8 tasks completed
## Active Tasks
- [IN PROGRESS] impl-1: Current task in progress
- [ ] impl-2: Next pending task
## Completed Tasks
- [COMPLETED] impl-0: Setup completed
```
## Simple Bash Commands
### Basic Operations
- **Find active session**: `find .workflow/ -name ".active-*" -type f`
- **Read session info**: `cat .workflow/session/workflow-session.json`
- **List tasks**: `find .workflow/session/.task/ -name "*.json" -type f`
- **Check task status**: `cat task.json | jq -r '.status'`
- **Count completed**: `find .summaries/ -name "*.md" -type f | wc -l`
### Task Status Check
- **pending**: Not started yet
- **active**: Currently in progress
- **completed**: Finished with summary
- **blocked**: Waiting for dependencies
### Validation Commands
```bash
# Check session exists
test -f .workflow/.active-* && echo "Session active"
# Validate task files
for f in .workflow/session/.task/*.json; do jq empty "$f" && echo "Valid: $f"; done
# Check summaries match
find .task/ -name "*.json" -type f | wc -l
find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l
```
## Simple Output Format
### Default Overview
```
Session: WFS-user-auth
Status: ACTIVE
Progress: 5/12 tasks
Current: impl-3 (Building API endpoints)
Next: impl-4 (Adding authentication)
Completed: impl-1, impl-2
```
### Task Details
```
Task: impl-1
Title: Build authentication module
Status: completed
Agent: code-developer
Created: 2025-09-15
Completed: 2025-09-15
Summary: .summaries/impl-1-summary.md
```
### Validation Results
```
Session file valid
8 task files found
3 summaries found
5 tasks pending completion
```

384
.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md Normal file
View File

@@ -0,0 +1,384 @@
---
name: tdd-plan
description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
argument-hint: "[--agent] \"feature description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# TDD Workflow Plan Command (/workflow:tdd-plan)
## Coordinator Role
**This command is a pure orchestrator**: Execute 5 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation.
**Execution Modes**:
- **Manual Mode** (default): Use `/workflow:tools:task-generate-tdd`
- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-tdd --agent`
## Core Rules
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
2. **No Preliminary Analysis**: Do not read files before Phase 1
3. **Parse Every Output**: Extract required data for next phase
4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
5. **Track Progress**: Update TodoWrite after every phase completion
6. **TDD Context**: All descriptions include "TDD:" prefix
7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
## 6-Phase Execution (with Conflict Resolution)
### Phase 1: Session Discovery
**Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
**TDD Structured Format**:
```
TDD: [Feature Name]
GOAL: [Objective]
SCOPE: [Included/excluded]
CONTEXT: [Background]
TEST_FOCUS: [Test scenarios]
```
**Parse**: Extract sessionId
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
---
### Phase 2: Context Gathering
**Command**: `/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"`
**Use Same Structured Description**: Pass the same structured format from Phase 1
**Input**: `sessionId` from Phase 1
**Parse Output**:
- Extract: context-package.json path (store as `contextPath`)
- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
**Validation**:
- Context package path extracted
- File exists and is valid JSON
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
---
### Phase 3: Test Coverage Analysis
**Command**: `/workflow:tools:test-context-gather --session [sessionId]`
**Purpose**: Analyze existing codebase for:
- Existing test patterns and conventions
- Current test coverage
- Related components and integration points
- Test framework detection
**Parse**: Extract testContextPath (`.workflow/[sessionId]/.process/test-context-package.json`)
**Benefits**:
- Makes TDD aware of existing environment
- Identifies reusable test patterns
- Prevents duplicate test creation
- Enables integration with existing tests
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
---
### Phase 4: Conflict Resolution (Optional - auto-triggered by conflict risk)
**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
**Input**:
- sessionId from Phase 1
- contextPath from Phase 2
- conflict_risk from context-package.json
**Parse Output**:
- Extract: Execution status (success/skipped/failed)
- Verify: CONFLICT_RESOLUTION.md file path (if executed)
**Validation**:
- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
**Skip Behavior**:
- If conflict_risk is "none" or "low", skip directly to Phase 5
- Display: "No significant conflicts detected, proceeding to TDD task generation"
**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
**After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
**Memory State Check**:
- Evaluate current context window usage and memory state
- If memory usage is high (>110K tokens or approaching context limits):
- **Command**: `SlashCommand(command="/compact")`
- This optimizes memory before proceeding to Phase 5
- Memory compaction is particularly important after analysis phase which may generate extensive documentation
- Ensures optimal performance and prevents context overflow
---
### Phase 5: TDD Task Generation
**Command**:
- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
**Validate**:
- IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
- IMPL-*.json files exist (one per feature, or container + subtasks for complex features)
- TODO_LIST.md exists with internal TDD phase indicators
- Each IMPL task includes:
- `meta.tdd_workflow: true`
- `flow_control.implementation_approach` with 3 steps (red/green/refactor)
- Green phase includes test-fix-cycle configuration
- IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
- Task count ≤10 (compliance with task limit)
### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
**Internal validation first, then recommend external verification**
**Internal Validation**:
1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
2. Task structure validation:
- `meta.tdd_workflow: true` in all IMPL tasks
- `flow_control.implementation_approach` has exactly 3 steps
- Each step has correct `tdd_phase`: "red", "green", "refactor"
3. Dependency validation:
- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
- Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
4. Agent assignment: All IMPL tasks use @code-developer
5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
6. Task count: Total tasks ≤10 (simple + subtasks)
**Return Summary**:
```
TDD Planning complete for session: [sessionId]
Features analyzed: [N]
Total tasks: [M] (1 task per simple feature + subtasks for complex features)
Task breakdown:
- Simple features: [K] tasks (IMPL-1 to IMPL-K)
- Complex features: [L] features with [P] subtasks
- Total task count: [M] (within 10-task limit)
Structure:
- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
- IMPL-2: {Feature 2 Name} (Internal: Red → Green → Refactor)
- IMPL-3: {Complex Feature} (Container)
- IMPL-3.1: {Sub-feature A} (Internal: Red → Green → Refactor)
- IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor)
[...]
Plans generated:
- Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
(includes TDD Implementation Tasks section with workflow_type: "tdd")
- Task List: .workflow/[sessionId]/TODO_LIST.md
(with internal TDD phase indicators)
TDD Configuration:
- Each task contains complete Red-Green-Refactor cycle
- Green phase includes test-fix cycle (max 3 iterations)
- Auto-revert on max iterations reached
Recommended Next Steps:
1. /workflow:action-plan-verify --session [sessionId] # Verify TDD plan quality and dependencies
2. /workflow:execute --session [sessionId] # Start TDD execution
3. /workflow:tdd-verify [sessionId] # Post-execution TDD compliance check
Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
```
## TodoWrite Pattern
```javascript
// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
{"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
// Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
{"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
{"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]})
// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
{"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
{"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
{"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]})
// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
{"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
{"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]})
// After Phase 4 (if executed), continue to Phase 5
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
{"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
{"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
{"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]})
```
## Input Processing
Convert user input to TDD-structured format:
**Simple text** → Add TDD context
**Detailed text** → Extract components with TEST_FOCUS
**File/Issue** → Read and structure with TDD
## Error Handling
- **Parsing failure**: Retry once, then report
- **Validation failure**: Report missing/invalid data
- **Command failure**: Keep phase in_progress, report error
- **TDD validation failure**: Report incomplete chains or wrong dependencies
## TDD Workflow Enhancements
### Overview
The TDD workflow has been significantly enhanced by integrating best practices from both traditional `plan --agent` and `test-gen` workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.
### Key Improvements
#### 1. Test Coverage Analysis (Phase 3)
**Adopted from test-gen workflow**
Before planning TDD tasks, the workflow now analyzes the existing codebase:
- Detects existing test patterns and conventions
- Identifies current test coverage
- Discovers related components and integration points
- Detects test framework automatically
**Benefits**:
- Context-aware TDD planning
- Avoids duplicate test creation
- Enables integration with existing tests
- No longer assumes greenfield scenarios
#### 2. Iterative Green Phase with Test-Fix Cycle
**Adopted from test-gen workflow**
IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:
**Enhanced IMPL Task Flow**:
```
1. Write minimal implementation code
2. Execute test suite
3. IF tests pass → Complete task
4. IF tests fail → Enter fix cycle:
a. Gemini diagnoses with bug-fix template
b. Apply fix (manual or Codex)
c. Retest
d. Repeat (max 3 iterations)
5. IF max iterations → Auto-revert changes 🔄
```
**Benefits**:
- Faster feedback within Green phase
- Autonomous recovery from implementation errors
- Systematic debugging with Gemini
- Safe rollback prevents broken state
#### 3. Agent-Driven Planning
**From plan --agent workflow**
Supports action-planning-agent for more autonomous TDD planning with:
- MCP tool integration (code-index, exa)
- Memory-first principles
- Brainstorming artifact integration
- Task merging over decomposition
### Workflow Comparison
| Aspect | Previous | Current (Optimized) |
|--------|----------|---------------------|
| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
| **Context** | Greenfield assumption | Existing codebase aware |
| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
| **Green Phase** | Single implementation | Iterative with fix cycle |
| **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
| **Test Analysis** | None | Deep coverage analysis |
| **Feedback Loop** | Post-execution | During Green phase |
| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
### Migration Notes
**Backward Compatibility**: Fully compatible
- Existing TDD workflows continue to work
- New features are additive, not breaking
- Phase 3 can be skipped if test-context-gather not available
**Session Structure**:
```
.workflow/WFS-xxx/
├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
├── TODO_LIST.md (with internal TDD phase indicators)
├── .process/
│ ├── context-package.json
│ ├── test-context-package.json
│ ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
│ └── green-fix-iteration-*.md (fix logs from Green phase cycles)
└── .task/
├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
├── IMPL-2.json (Complete TDD task)
├── IMPL-3.json (Complex feature container, if needed)
├── IMPL-3.1.json (Complex feature subtask, if needed)
└── IMPL-3.2.json (Complex feature subtask, if needed)
```
**File Count Comparison**:
- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
- **New structure**: 5 features = 5 task files (IMPL-N × 5)
- **Complex features**: Add container + subtasks only when necessary
**Configuration Options** (in IMPL tasks):
- `meta.max_iterations`: Fix attempts (default: 3)
- `meta.use_codex`: Auto-fix mode (default: false)
## Related Commands
**Prerequisite Commands**:
- None - TDD planning is self-contained (can optionally run brainstorm commands before)
**Called by This Command** (6 phases):
- `/workflow:session:start` - Phase 1: Create or discover TDD workflow session
- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
- `/compact` - Phase 4: Memory optimization (if context approaching limits)
- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD task chains with Red-Green-Refactor cycles
- `/workflow:tools:task-generate-tdd --agent` - Phase 5: Generate TDD tasks with agent-driven approach (when `--agent` flag used)
**Follow-up Commands**:
- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
- `/workflow:status` - Review TDD task breakdown
- `/workflow:execute` - Begin TDD implementation
- `/workflow:tdd-verify` - Post-execution: Verify TDD compliance and generate quality report

353
.claude/skills/command-guide/reference/commands/workflow/tdd-verify.md Normal file
View File

@@ -0,0 +1,353 @@
---
name: tdd-verify
description: Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis
argument-hint: "[optional: WFS-session-id]"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
---
# TDD Verification Command (/workflow:tdd-verify)
## Coordinator Role
**This command is a pure orchestrator**: Execute 4 phases to verify TDD workflow compliance, test coverage, and Red-Green-Refactor cycle execution.
## Core Responsibilities
- Verify TDD task chain structure
- Analyze test coverage
- Validate TDD cycle execution
- Generate compliance report
## 4-Phase Execution
### Phase 1: Session Discovery
**Auto-detect or use provided session**
```bash
# If session-id provided
sessionId = argument
# Else auto-detect active session
find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
```
**Extract**: sessionId
**Validation**: Session directory exists
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
---
### Phase 2: Task Chain Validation
**Validate TDD structure using bash commands**
```bash
# Load all task JSONs
find .workflow/{sessionId}/.task/ -name '*.json'
# Extract task IDs
find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.id' {} \;
# Check dependencies
find .workflow/{sessionId}/.task/ -name 'IMPL-*.json' -exec jq -r '.context.depends_on[]?' {} \;
find .workflow/{sessionId}/.task/ -name 'REFACTOR-*.json' -exec jq -r '.context.depends_on[]?' {} \;
# Check meta fields
find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;
find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
```
**Validation**:
- For each feature N, verify TEST-N.M → IMPL-N.M → REFACTOR-N.M exists
- IMPL-N.M.context.depends_on includes TEST-N.M
- REFACTOR-N.M.context.depends_on includes IMPL-N.M
- TEST tasks have tdd_phase="red" and agent="@code-review-test-agent"
- IMPL/REFACTOR tasks have tdd_phase="green"/"refactor" and agent="@code-developer"
**Extract**: Chain validation report
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
---
### Phase 3: Test Execution Analysis
**Command**: `SlashCommand(command="/workflow:tools:tdd-coverage-analysis --session [sessionId]")`
**Input**: sessionId from Phase 1
**Parse Output**:
- Coverage metrics (line, branch, function percentages)
- TDD cycle verification results
- Compliance score
**Validation**:
- `.workflow/{sessionId}/.process/test-results.json` exists
- `.workflow/{sessionId}/.process/coverage-report.json` exists
- `.workflow/{sessionId}/.process/tdd-cycle-report.md` exists
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
---
### Phase 4: Compliance Report Generation
**Gemini analysis for comprehensive TDD compliance report**
```bash
cd project-root && gemini -p "
PURPOSE: Generate TDD compliance report
TASK: Analyze TDD workflow execution and generate quality report
CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
EXPECTED:
- TDD compliance score (0-100)
- Chain completeness verification
- Test coverage analysis summary
- Quality recommendations
- Red-Green-Refactor cycle validation
- Best practices adherence assessment
RULES: Focus on TDD best practices and workflow adherence. Be specific about violations and improvements.
" > .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
```
**Output**: TDD_COMPLIANCE_REPORT.md
**TodoWrite**: Mark phase 4 completed
**Return to User**:
```
TDD Verification Report - Session: {sessionId}
## Chain Validation
[COMPLETE] Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
[COMPLETE] Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
[INCOMPLETE] Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
## Test Execution
All TEST tasks produced failing tests
All IMPL tasks made tests pass
All REFACTOR tasks maintained green tests
## Coverage Metrics
Line Coverage: {percentage}%
Branch Coverage: {percentage}%
Function Coverage: {percentage}%
## Compliance Score: {score}/100
Detailed report: .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
Recommendations:
- Complete missing REFACTOR-3.1 task
- Consider additional edge case tests for Feature 2
- Improve test failure message clarity in Feature 1
```
## TodoWrite Pattern
```javascript
// Initialize (before Phase 1)
TodoWrite({todos: [
{"content": "Identify target session", "status": "in_progress", "activeForm": "Identifying target session"},
{"content": "Validate task chain structure", "status": "pending", "activeForm": "Validating task chain structure"},
{"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
{"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
]})
// After Phase 1
TodoWrite({todos: [
{"content": "Identify target session", "status": "completed", "activeForm": "Identifying target session"},
{"content": "Validate task chain structure", "status": "in_progress", "activeForm": "Validating task chain structure"},
{"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
{"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
]})
// Continue pattern for Phase 2, 3, 4...
```
## Validation Logic
### Chain Validation Algorithm
```
1. Load all task JSONs from .workflow/{sessionId}/.task/
2. Extract task IDs and group by feature number
3. For each feature:
- Check TEST-N.M exists
- Check IMPL-N.M exists
- Check REFACTOR-N.M exists (optional but recommended)
- Verify IMPL-N.M depends_on TEST-N.M
- Verify REFACTOR-N.M depends_on IMPL-N.M
- Verify meta.tdd_phase values
- Verify meta.agent assignments
4. Calculate chain completeness score
5. Report incomplete or invalid chains
```
### Compliance Scoring
```
Base Score: 100 points
Deductions:
- Missing TEST task: -30 points per feature
- Missing IMPL task: -30 points per feature
- Missing REFACTOR task: -10 points per feature
- Wrong dependency: -15 points per error
- Wrong agent: -5 points per error
- Wrong tdd_phase: -5 points per error
- Test didn't fail initially: -10 points per feature
- Tests didn't pass after IMPL: -20 points per feature
- Tests broke during REFACTOR: -15 points per feature
Final Score: Max(0, Base Score - Deductions)
```
## Output Files
```
.workflow/{session-id}/
├── TDD_COMPLIANCE_REPORT.md # Comprehensive compliance report ⭐
└── .process/
├── test-results.json # From tdd-coverage-analysis
├── coverage-report.json # From tdd-coverage-analysis
└── tdd-cycle-report.md # From tdd-coverage-analysis
```
## Error Handling
### Session Discovery Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| No active session | No .active-* file | Provide session-id explicitly |
| Multiple active sessions | Multiple .active-* files | Provide session-id explicitly |
| Session not found | Invalid session-id | Check available sessions |
### Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Task files missing | Incomplete planning | Run tdd-plan first |
| Invalid JSON | Corrupted task files | Regenerate tasks |
| Missing summaries | Tasks not executed | Execute tasks before verify |
### Analysis Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Coverage tool missing | No test framework | Configure testing first |
| Tests fail to run | Code errors | Fix errors before verify |
| Gemini analysis fails | Token limit / API error | Retry or reduce context |
## Integration & Usage
### Command Chain
- **Called After**: `/workflow:execute` (when TDD tasks completed)
- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini CLI
- **Related**: `/workflow:tdd-plan`, `/workflow:status`
### Basic Usage
```bash
# Auto-detect active session
/workflow:tdd-verify
# Specify session
/workflow:tdd-verify WFS-auth
```
### When to Use
- After completing all TDD tasks in a workflow
- Before merging TDD workflow branch
- For TDD process quality assessment
- To identify missing TDD steps
## TDD Compliance Report Structure
```markdown
# TDD Compliance Report - {Session ID}
**Generated**: {timestamp}
**Session**: {sessionId}
**Workflow Type**: TDD
## Executive Summary
Overall Compliance Score: {score}/100
Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
## Chain Analysis
### Feature 1: {Feature Name}
**Status**: Complete
**Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
- **Red Phase**: Test created and failed with clear message
- **Green Phase**: Minimal implementation made test pass
- **Refactor Phase**: Code improved, tests remained green
### Feature 2: {Feature Name}
**Status**: Incomplete
**Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1)
- **Red Phase**: Test created and failed
- **Green Phase**: Implementation seems over-engineered
- **Refactor Phase**: Missing
**Issues**:
- REFACTOR-2.1 task not completed
- IMPL-2.1 implementation exceeded minimal scope
[Repeat for all features]
## Test Coverage Analysis
### Coverage Metrics
- Line Coverage: {percentage}% {status}
- Branch Coverage: {percentage}% {status}
- Function Coverage: {percentage}% {status}
### Coverage Gaps
- {file}:{lines} - Uncovered error handling
- {file}:{lines} - Uncovered edge case
## TDD Cycle Validation
### Red Phase (Write Failing Test)
- {N}/{total} features had failing tests initially
- Feature 3: No evidence of initial test failure
### Green Phase (Make Test Pass)
- {N}/{total} implementations made tests pass
- All implementations minimal and focused
### Refactor Phase (Improve Quality)
- {N}/{total} features completed refactoring
- Feature 2, 4: Refactoring step skipped
## Best Practices Assessment
### Strengths
- Clear test descriptions
- Good test coverage
- Consistent naming conventions
- Well-structured code
### Areas for Improvement
- Some implementations over-engineered in Green phase
- Missing refactoring steps
- Test failure messages could be more descriptive
## Recommendations
### High Priority
1. Complete missing REFACTOR tasks (Features 2, 4)
2. Verify initial test failures for Feature 3
3. Simplify over-engineered implementations
### Medium Priority
1. Add edge case tests for Features 1, 3
2. Improve test failure message clarity
3. Increase branch coverage to >85%
### Low Priority
1. Add more descriptive test names
2. Consider parameterized tests for similar scenarios
3. Document TDD process learnings
## Conclusion
{Summary of compliance status and next steps}
```

655
.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md Normal file
View File

@@ -0,0 +1,655 @@
---
name: test-cycle-execute
description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached
argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
---
# Workflow Test-Cycle-Execute Command
## Overview
Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
**CRITICAL - Orchestrator Boundary**:
- This command is the **ONLY place** where test failures are handled
- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
- Agents (@test-fix-agent) only execute single tasks and return results
- **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
**Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
## Core Philosophy
### Dynamic vs Static Execution
**Standard Execute**: Pre-defined task queue → Sequential execution → Complete
**Test Execute**: Initial tasks → Test → Analyze → Generate fix tasks → Execute → Re-test → Repeat
### Iteration Loop Pattern
```
1. Execute current task (test/implement)
2. Run tests and collect results
3. If failures: CLI analysis → Generate fix tasks → Execute → Back to 2
4. If success: Mark complete → Next task
5. Repeat until all tests pass or max iterations reached
```
### Agent Coordination
- **@code-developer**: Understands requirements, generates implementations
- **@test-fix-agent**: Executes tests, applies fixes, validates results
- **CLI Tools (Gemini/Qwen)**: Analyzes failures, suggests fix strategies
## Core Rules
1. **Dynamic Task Generation**: Create intermediate fix tasks based on test failures
2. **Iterative Execution**: Repeat test-fix cycles until success or max iterations
3. **CLI-Driven Analysis**: Use Gemini/Qwen to analyze failures and plan fixes
4. **Agent Delegation**: All execution delegated to specialized agents
5. **Context Accumulation**: Each iteration builds on previous attempt context
6. **Autonomous Completion**: Continue until all tests pass without user interruption
## Core Responsibilities
- **Session Discovery**: Identify test-fix workflow sessions
- **Task Queue Management**: Maintain dynamic task queue with runtime additions
- **Test Execution**: Run tests through @test-fix-agent
- **Failure Analysis**: Use CLI tools to diagnose test failures
- **Fix Task Generation**: Create intermediate fix tasks dynamically
- **Iteration Control**: Manage fix cycles with max iteration limits
- **Context Propagation**: Pass failure context and fix history between iterations
- **Progress Tracking**: TodoWrite updates for entire iteration cycle
- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
## Responsibility Matrix
**CRITICAL - Clear division of labor between orchestrator and agents:**
| Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
|----------------|----------------------------|---------------------------|
| Manage iteration loop | Yes - Controls loop flow | No - Executes single task |
| Run CLI analysis (Gemini/Qwen) | Yes - Runs between agent tasks | No - Not involved |
| Generate IMPL-fix-N.json | Yes - Creates task files | No - Not involved |
| Run tests | No - Delegates to agent | Yes - Executes test command |
| Apply fixes | No - Delegates to agent | Yes - Modifies code |
| Detect test failures | Yes - Analyzes results and decides next action | Yes - Executes tests and reports outcomes |
| Add tasks to queue | Yes - Manages queue | No - Not involved |
| Update iteration state | Yes - Maintains overall iteration state | Yes - Updates individual task status only |
**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
**ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
## Execution Lifecycle
### Phase 1: Discovery & Initialization
1. **Detect Session Type**: Identify test-fix session from `workflow_type: "test_session"`
2. **Load Session State**: Read `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`
3. **Scan Initial Tasks**: Analyze `.task/*.json` files
4. **Initialize TodoWrite**: Create task list including initial tasks
5. **Prepare Iteration Context**: Setup iteration counter and max limits
**Resume Mode**: Load existing iteration context from `.process/iteration-state.json`
### Phase 2: Task Execution Loop
**Main execution loop with dynamic task generation (executed by test-cycle-execute orchestrator):**
**Execution Order**: The workflow begins by executing IMPL-001 (test generation) first. Upon successful completion, IMPL-002 (test-fix cycle) is initiated, starting the iterative test-fix loop.
```
For each task in queue:
1. [Orchestrator] Load task JSON and context
2. [Orchestrator] Determine task type (test-gen, test-fix, fix-iteration)
3. [Orchestrator] Execute task through appropriate agent
4. [Orchestrator] Collect agent results and check exit conditions
5. If test failures detected:
a. [Orchestrator] Run CLI analysis (Gemini/Qwen)
b. [Orchestrator] Generate fix task JSON (IMPL-fix-N.json)
c. [Orchestrator] Insert fix task at front of queue
d. [Orchestrator] Continue loop
6. If test success:
a. [Orchestrator] Mark task complete
b. [Orchestrator] Update TodoWrite
c. [Orchestrator] Continue to next task
7. [Orchestrator] Check max iterations limit
```
**Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
### Phase 3: Iteration Cycle (Test-Fix Loop)
**Orchestrator-controlled iteration with agent delegation:**
#### Iteration Structure
```
Iteration N (managed by test-cycle-execute orchestrator):
├── 1. Test Execution
│ ├── [Orchestrator] Launch @test-fix-agent with test task
│ ├── [Agent] Run test suite
│ ├── [Agent] Collect failures and report back
│ └── [Orchestrator] Receive failure report
├── 2. Failure Analysis
│ ├── [Orchestrator] Run CLI tool (Gemini/Qwen)
│ ├── [CLI Tool] Analyze error messages and failure context
│ ├── [CLI Tool] Identify root causes
│ └── [CLI Tool] Generate fix strategy → saved to iteration-N-analysis.md
├── 3. Fix Task Generation
│ ├── [Orchestrator] Parse CLI analysis results
│ ├── [Orchestrator] Create IMPL-fix-N.json with:
│ │ ├── meta.agent: "@test-fix-agent"
│ │ ├── Failure context (content, not just path)
│ │ └── Fix strategy from CLI analysis
│ └── [Orchestrator] Insert into task queue (front position)
├── 4. Fix Execution
│ ├── [Orchestrator] Launch @test-fix-agent with fix task
│ ├── [Agent] Load fix strategy from task context
│ ├── [Agent] Apply fixes to code/tests
│ └── [Agent] Report completion
└── 5. Re-test
└── [Orchestrator] Return to step 1 with updated code
```
**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
#### Iteration Task JSON Template
```json
{
"id": "IMPL-fix-{iteration}",
"title": "Fix test failures - Iteration {N}",
"status": "pending",
"meta": {
"type": "test-fix-iteration",
"agent": "@test-fix-agent",
"iteration": N,
"parent_task": "IMPL-002",
"max_iterations": 5
},
"context": {
"requirements": [
"Fix identified test failures",
"Address root causes from analysis"
],
"failure_context": {
"failed_tests": ["test1", "test2"],
"error_messages": ["error1", "error2"],
"failure_analysis": "Raw test output and error messages",
"previous_attempts": ["iteration-1 context"]
},
"fix_strategy": {
"approach": "Generated by CLI tool (Gemini/Qwen) analysis",
"modification_points": ["file1:func1", "file2:func2"],
"expected_outcome": "All tests pass"
},
"depends_on": ["IMPL-fix-{N-1}"],
"inherited": {
"iteration_history": [...]
}
},
"flow_control": {
"pre_analysis": [
{
"step": "load_failure_context",
"command": "Read(.workflow/{session}/.process/iteration-{N-1}-failures.json)",
"output_to": "previous_failures",
"on_error": "skip_optional"
},
{
"step": "load_fix_strategy",
"command": "Read(.workflow/{session}/.process/iteration-{N}-strategy.md)",
"output_to": "fix_strategy",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Apply fixes from strategy",
"description": "Implement fixes identified by CLI analysis",
"modification_points": "From fix_strategy",
"logic_flow": [
"Load failure context and strategy",
"Apply surgical fixes",
"Run tests",
"Validate fixes"
]
}
],
"target_files": ["from fix_strategy"],
"exit_conditions": {
"success": "all_tests_pass",
"failure": "max_iterations_reached",
"max_iterations": 5
}
}
}
```
### Phase 4: CLI Analysis Integration
**Orchestrator executes CLI analysis between agent tasks:**
#### When Test Failures Occur
1. **[Orchestrator]** Detects failures from agent test execution output
2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
4. **[Orchestrator]** Interprets CLI tool output to extract fix strategy
5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
#### CLI Analysis Command (executed by orchestrator)
```bash
cd {project_root} && gemini -p "
PURPOSE: Analyze test failures and generate fix strategy
TASK: Review test failures and identify root causes
MODE: analysis
CONTEXT: @test files @ implementation files
[Test failure context and requirements...]
EXPECTED: Detailed fix strategy in markdown format
RULES: Focus on minimal changes, avoid over-engineering
"
```
#### Analysis Output Structure
```markdown
# Test Failure Analysis - Iteration {N}
## Root Cause Analysis
1. **Test: test_auth_flow**
- Error: `Expected 200, got 401`
- Root Cause: Missing authentication token in request headers
- Affected Code: `src/auth/client.ts:45`
2. **Test: test_data_validation**
- Error: `TypeError: Cannot read property 'name' of undefined`
- Root Cause: Null check missing before property access
- Affected Code: `src/validators/user.ts:23`
## Fix Strategy
### Priority 1: Authentication Issue
- **File**: src/auth/client.ts
- **Function**: sendRequest (line 45)
- **Change**: Add token header: `headers['Authorization'] = 'Bearer ' + token`
- **Verification**: Run test_auth_flow
### Priority 2: Null Check
- **File**: src/validators/user.ts
- **Function**: validateUser (line 23)
- **Change**: Add check: `if (!user?.name) return false`
- **Verification**: Run test_data_validation
## Verification Plan
1. Apply fixes in order
2. Run test suite after each fix
3. Check for regressions
4. Validate all tests pass
## Risk Assessment
- Low risk: Changes are surgical and isolated
- No breaking changes expected
- Existing tests should remain green
```
### Phase 5: Task Queue Management
**Orchestrator maintains dynamic task queue with runtime insertions:**
#### Dynamic Queue Operations
```
Initial Queue: [IMPL-001, IMPL-002]
After IMPL-002 execution (test failures detected by orchestrator):
[Orchestrator] Generates IMPL-fix-1.json
[Orchestrator] Inserts at front: [IMPL-fix-1, IMPL-002-retest, ...]
After IMPL-fix-1 execution (still failures):
[Orchestrator] Generates IMPL-fix-2.json
[Orchestrator] Inserts at front: [IMPL-fix-2, IMPL-002-retest, ...]
After IMPL-fix-2 execution (success):
[Orchestrator] Continues to: [IMPL-002-complete, ...]
```
#### Queue Priority Rules (orchestrator-managed)
1. **Fix tasks**: Inserted at queue front for immediate execution
2. **Retest tasks**: Automatically scheduled after fix tasks
3. **Regular tasks**: Standard dependency order preserved
4. **Iteration limit**: Max 5 fix iterations per test task (orchestrator enforces)
### Phase 6: Completion & Session Management
#### Success Conditions
- All initial tasks completed
- All generated fix tasks completed
- All tests passing
- No pending tasks in queue
#### Completion Steps
1. **Final Validation**: Run full test suite one more time
2. **Update Session State**: Mark all tasks completed
3. **Generate Summary**: Create session completion summary
4. **Update TodoWrite**: Mark all items completed
5. **Auto-Complete**: Call `/workflow:session:complete`
#### Failure Conditions
- Max iterations reached without success
- Unrecoverable test failures
- Agent execution errors
#### Failure Handling
1. **Document State**: Save current iteration context
2. **Generate Report**: Create failure analysis report
3. **Preserve Context**: Keep all iteration logs
4. **Mark Blocked**: Update task status to blocked
5. **Return Control**: Return to user with detailed report
## TodoWrite Coordination
### TodoWrite Structure for Test-Execute
```javascript
TodoWrite({
todos: [
{
content: "Execute IMPL-001: Generate tests [code-developer]",
status: "completed",
activeForm: "Executing test generation"
},
{
content: "Execute IMPL-002: Test & Fix Cycle [test-fix-agent] [ITERATION]",
status: "in_progress",
activeForm: "Running test-fix iteration cycle"
},
{
content: " → Iteration 1: Initial test run",
status: "completed",
activeForm: "Running initial tests"
},
{
content: " → Iteration 2: Fix auth issues",
status: "in_progress",
activeForm: "Fixing authentication issues"
},
{
content: " → Iteration 3: Re-test and validate",
status: "pending",
activeForm: "Re-testing after fixes"
}
]
});
```
### TodoWrite Update Rules
1. **Initial Tasks**: Standard task list
2. **Iteration Start**: Add nested iteration item
3. **Fix Task Added**: Add fix task as nested item
4. **Iteration Complete**: Mark iteration item completed
5. **All Complete**: Mark parent task completed
## Agent Context Package
**Generated by test-cycle-execute orchestrator before launching agents.**
The orchestrator assembles this context package from:
- Task JSON file (IMPL-*.json)
- Iteration state files
- Test results and failure context
- Session metadata
This package is passed to agents via the Task tool's prompt context.
### Enhanced Context for Test-Fix Agent
```json
{
"task": { /* IMPL-fix-N.json */ },
"iteration_context": {
"current_iteration": N,
"max_iterations": 5,
"previous_attempts": [
{
"iteration": N-1,
"failures": ["test1", "test2"],
"fixes_attempted": ["fix1", "fix2"],
"result": "partial_success"
}
],
"failure_analysis": {
"source": "gemini_cli",
"analysis_file": ".process/iteration-N-analysis.md",
"fix_strategy": { /* from CLI */ }
}
},
"test_context": {
"test_framework": "jest|pytest|...",
"test_files": ["path/to/test1.test.ts"],
"test_command": "npm test",
"coverage_target": 80
},
"session": {
"workflow_dir": ".workflow/WFS-test-{session}/",
"iteration_state_file": ".process/iteration-state.json",
"test_results_file": ".process/test-results.json",
"fix_history_file": ".process/fix-history.json"
}
}
```
## File Structure
### Test-Fix Session Files
```
.workflow/WFS-test-{session}/
├── workflow-session.json # Session metadata with workflow_type
├── IMPL_PLAN.md # Test plan
├── TODO_LIST.md # Progress tracking
├── .task/
│ ├── IMPL-001.json # Test generation task
│ ├── IMPL-002.json # Initial test-fix task
│ ├── IMPL-fix-1.json # Generated: Iteration 1 fix
│ ├── IMPL-fix-2.json # Generated: Iteration 2 fix
│ └── ...
├── .summaries/
│ ├── IMPL-001-summary.md
│ ├── IMPL-002-summary.md
│ └── iteration-summaries/
│ ├── iteration-1.md
│ ├── iteration-2.md
│ └── ...
└── .process/
├── TEST_ANALYSIS_RESULTS.md # From planning phase
├── iteration-state.json # Current iteration state
├── test-results.json # Latest test results
├── test-output.log # Full test output
├── fix-history.json # All fix attempts
├── iteration-1-analysis.md # CLI analysis for iteration 1
├── iteration-1-failures.json # Failures from iteration 1
├── iteration-1-strategy.md # Fix strategy for iteration 1
├── iteration-2-analysis.md
└── ...
```
### Iteration State JSON
```json
{
"session_id": "WFS-test-user-auth",
"current_task": "IMPL-002",
"current_iteration": 2,
"max_iterations": 5,
"started_at": "2025-10-17T10:00:00Z",
"iterations": [
{
"iteration": 1,
"started_at": "2025-10-17T10:05:00Z",
"completed_at": "2025-10-17T10:15:00Z",
"test_results": {
"total": 10,
"passed": 7,
"failed": 3,
"failures": ["test1", "test2", "test3"]
},
"analysis_file": ".process/iteration-1-analysis.md",
"fix_task": "IMPL-fix-1",
"result": "partial_success"
}
],
"status": "active",
"next_action": "execute_fix_task"
}
```
## Agent Prompt Template
**Unified template for all agent tasks (orchestrator invokes with Task tool):**
```bash
Task(subagent_type="{meta.agent}",
prompt="**TASK EXECUTION: {task.title}**
## STEP 1: Load Complete Task JSON
**MANDATORY**: First load the complete task JSON from: {session.task_json_path}
cat {session.task_json_path}
**CRITICAL**: Validate all required fields present
## STEP 2: Task Context (From Loaded JSON)
**ID**: {task.id}
**Type**: {task.meta.type}
**Agent**: {task.meta.agent}
## STEP 3: Execute Task Based on Type
### For test-gen (IMPL-001):
- Generate tests based on TEST_ANALYSIS_RESULTS.md
- Follow test framework conventions
- Create test files in target_files
### For test-fix (IMPL-002):
- Run test suite: {test_command}
- Collect results to .process/test-results.json
- Report results to orchestrator (do NOT analyze failures)
- Orchestrator will handle failure detection and iteration decisions
- If success: Mark complete
### For test-fix-iteration (IMPL-fix-N):
- Load fix strategy from context.fix_strategy (CONTENT, not path)
- Apply surgical fixes to identified files
- Return results to orchestrator
- Do NOT run tests independently - orchestrator manages all test execution
- Do NOT handle failures - orchestrator analyzes and decides next iteration
## STEP 4: Implementation Context (From JSON)
**Requirements**: {context.requirements}
**Fix Strategy**: {context.fix_strategy} (full content provided in task JSON)
**Failure Context**: {context.failure_context}
**Iteration History**: {context.inherited.iteration_history}
## STEP 5: Flow Control Execution
If flow_control.pre_analysis exists, execute steps sequentially
## STEP 6: Agent Completion
1. Execute task following implementation_approach
2. Update task status in JSON
3. Update TODO_LIST.md
4. Generate summary in .summaries/
5. **CRITICAL**: Save results for orchestrator to analyze
**Output Requirements**:
- test-results.json: Structured test results
- test-output.log: Full test output
- iteration-state.json: Current iteration state (if applicable)
- task-summary.md: Completion summary
**Return to Orchestrator**: Agent completes and returns. Orchestrator decides next action.
"),
description="Execute {task.type} task with JSON validation")
```
**Key Points**:
- Agent executes single task and returns
- Orchestrator analyzes results and decides next step
- Fix strategy content (not path) embedded in task JSON by orchestrator
- Agent does not manage iteration loop
## Error Handling & Recovery
### Iteration Failure Scenarios
| Scenario | Handling | Recovery |
|----------|----------|----------|
| Test execution error | Log error, save context | Retry with error context |
| CLI analysis failure | Fallback to Qwen, or manual analysis | Retry analysis with different tool |
| Agent execution error | Save iteration state | Retry agent with simplified context |
| Max iterations reached | Generate failure report | Mark blocked, return to user |
| Unexpected test regression | Rollback last fix | Analyze regression, add to fix strategy |
### Recovery Procedures
#### Resume from Interruption
```bash
# Load iteration state
iteration_state=$(cat .workflow/{session}/.process/iteration-state.json)
current_iteration=$(jq -r '.current_iteration' <<< "$iteration_state")
# Determine resume point
if [[ "$(jq -r '.next_action' <<< "$iteration_state")" == "execute_fix_task" ]]; then
# Resume fix task execution
task_id="IMPL-fix-${current_iteration}"
else
# Resume test execution
task_id="IMPL-002"
fi
```
#### Rollback Failed Fix
```bash
# Revert last commit (if fixes were committed)
git revert HEAD
# Remove failed fix task
rm .workflow/{session}/.task/IMPL-fix-{N}.json
# Restore iteration state
jq '.current_iteration -= 1' iteration-state.json > temp.json
mv temp.json iteration-state.json
# Re-run analysis with additional context
# Include failure reason in next analysis
```
## Usage Examples
### Basic Usage
```bash
# Execute test-fix workflow
/workflow:test-cycle-execute
# Resume interrupted session
/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
# Set custom iteration limit
/workflow:test-cycle-execute --max-iterations=10
```
### Integration with Planning
```bash
# 1. Plan test workflow
/workflow:test-fix-gen WFS-user-auth
# 2. Execute with dynamic iteration
/workflow:test-cycle-execute
# 3. Monitor progress
/workflow:status
# 4. Resume if interrupted
/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
```
## Best Practices
1. **Set Realistic Iteration Limits**: Default 5, increase for complex fixes
2. **Commit Between Iterations**: Easier rollback if needed
3. **Monitor Iteration Logs**: Review CLI analysis for insights
4. **Incremental Fixes**: Prefer multiple small iterations over large changes
5. **Verify No Regressions**: Check all tests pass, not just previously failing ones
6. **Preserve Context**: All iteration artifacts saved for debugging

484
.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md Normal file
View File

@@ -0,0 +1,484 @@
---
name: test-fix-gen
description: Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning
argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# Workflow Test-Fix Generation Command (/workflow:test-fix-gen)
## Overview
### What It Does
This command creates an independent test-fix workflow session for existing code. It orchestrates a 5-phase process to analyze implementation, generate test requirements, and create executable test generation and fix tasks.
**CRITICAL - Command Scope**:
- **This command ONLY generates task JSON files** (IMPL-001.json, IMPL-002.json)
- **Does NOT execute tests or apply fixes** - all execution happens in separate orchestrator
- **Must call `/workflow:test-cycle-execute`** after this command to actually run tests and fixes
- **Test failure handling happens in test-cycle-execute**, not here
### Dual-Mode Support
**Automatic mode detection** based on input pattern:
| Mode | Input Pattern | Context Source | Use Case |
|------|--------------|----------------|----------|
| **Session Mode** | `WFS-xxx` | Source session summaries | Test validation for completed workflow |
| **Prompt Mode** | Text or file path | Direct codebase analysis | Test generation from description |
**Detection Logic**:
```bash
if [[ "$input" == WFS-* ]]; then
MODE="session" # Use test-context-gather
else
MODE="prompt" # Use context-gather
fi
```
### Core Principles
- **Dual Input Support**: Accepts session ID (WFS-xxx) or feature description/file path
- **Session Isolation**: Creates independent `WFS-test-[slug]` session
- **Context-First**: Gathers implementation context via appropriate method
- **Format Reuse**: Creates standard `IMPL-*.json` tasks with `meta.type: "test-fix"`
- **Manual First**: Default to manual fixes, use `--use-codex` for automation
- **Automatic Detection**: Input pattern determines execution mode
### Coordinator Role
This command is a **pure planning coordinator**:
- Does NOT analyze code directly
- Does NOT generate tests or documentation
- Does NOT execute tests or apply fixes
- Does NOT handle test failures or iterations
- ONLY coordinates slash commands to generate task JSON files
- Parses outputs to pass data between phases
- Creates independent test workflow session
- **All execution delegated to `/workflow:test-cycle-execute`**
---
## Usage
### Command Syntax
```bash
# Basic syntax
/workflow:test-fix-gen [FLAGS] <INPUT>
# Flags (optional)
--use-codex # Enable Codex automated fixes in IMPL-002
--cli-execute # Enable CLI execution in IMPL-001
# Input
<INPUT> # Session ID, description, or file path
```
### Usage Examples
#### Session Mode
```bash
# Test validation for completed implementation
/workflow:test-fix-gen WFS-user-auth-v2
# With automated fixes
/workflow:test-fix-gen --use-codex WFS-api-endpoints
# With CLI execution
/workflow:test-fix-gen --cli-execute --use-codex WFS-payment-flow
```
#### Prompt Mode - Text Description
```bash
# Generate tests from feature description
/workflow:test-fix-gen "Test the user authentication API endpoints in src/auth/api.ts"
# With automated fixes
/workflow:test-fix-gen --use-codex "Test user registration and login flows"
```
#### Prompt Mode - File Reference
```bash
# Generate tests from requirements file
/workflow:test-fix-gen ./docs/api-requirements.md
# With flags
/workflow:test-fix-gen --use-codex --cli-execute ./specs/feature.md
```
### Mode Comparison
| Aspect | Session Mode | Prompt Mode |
|--------|-------------|-------------|
| **Phase 1** | Create `WFS-test-[source]` with `source_session_id` | Create `WFS-test-[slug]` without `source_session_id` |
| **Phase 2** | `/workflow:tools:test-context-gather` | `/workflow:tools:context-gather` |
| **Phase 3-5** | Identical | Identical |
| **Context** | Source session summaries + artifacts | Direct codebase analysis |
---
## Execution Flow
### Core Execution Rules
1. **Start Immediately**: First action is TodoWrite, second is Phase 1 session creation
2. **No Preliminary Analysis**: Do not read files before Phase 1
3. **Parse Every Output**: Extract required data from each phase for next phase
4. **Sequential Execution**: Each phase depends on previous phase's output
5. **Complete All Phases**: Do not return until Phase 5 completes
6. **Track Progress**: Update TodoWrite after every phase
7. **Automatic Detection**: Mode auto-detected from input pattern
8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
### 5-Phase Execution
#### Phase 1: Create Test Session
**Command**:
- **Session Mode**: `SlashCommand("/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
- **Prompt Mode**: `SlashCommand("/workflow:session:start --new \"Test generation for: [description]\"")`
**Input**: User argument (session ID, description, or file path)
**Expected Behavior**:
- Creates new session: `WFS-test-[slug]`
- Writes `workflow-session.json` metadata:
- **Session Mode**: Includes `workflow_type: "test_session"`, `source_session_id: "[sourceId]"`
- **Prompt Mode**: Includes `workflow_type: "test_session"` only
- Returns new session ID
**Parse Output**:
- Extract: `testSessionId` (pattern: `WFS-test-[slug]`)
**Validation**:
- **Session Mode**: Source session exists with completed IMPL tasks
- **Both Modes**: New test session directory created with metadata
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
---
#### Phase 2: Gather Test Context
**Command**:
- **Session Mode**: `SlashCommand("/workflow:tools:test-context-gather --session [testSessionId]")`
- **Prompt Mode**: `SlashCommand("/workflow:tools:context-gather --session [testSessionId] \"[task_description]\"")`
**Input**: `testSessionId` from Phase 1
**Expected Behavior**:
- **Session Mode**:
- Load source session implementation context and summaries
- Analyze test coverage using MCP tools
- Identify files requiring tests
- **Prompt Mode**:
- Analyze codebase based on description
- Identify relevant files and dependencies
- Detect test framework and conventions
- Generate context package JSON
**Parse Output**:
- Extract: `contextPath` (pattern: `.workflow/[testSessionId]/.process/[test-]context-package.json`)
**Validation**:
- Context package created with coverage analysis
- Test framework detected
- Test conventions documented
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
---
#### Phase 3: Test Generation Analysis
**Command**: `SlashCommand("/workflow:tools:test-concept-enhanced --session [testSessionId] --context [contextPath]")`
**Input**:
- `testSessionId` from Phase 1
- `contextPath` from Phase 2
**Expected Behavior**:
- Use Gemini to analyze coverage gaps and implementation
- Study existing test patterns and conventions
- Generate test requirements for missing test files
- Design test generation strategy
- Generate `TEST_ANALYSIS_RESULTS.md`
**Parse Output**:
- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
**Validation**:
- TEST_ANALYSIS_RESULTS.md exists with complete sections:
- Coverage Assessment
- Test Framework & Conventions
- Test Requirements by File
- Test Generation Strategy
- Implementation Targets
- Success Criteria
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
---
#### Phase 4: Generate Test Tasks
**Command**: `SlashCommand("/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
**Input**:
- `testSessionId` from Phase 1
- `--use-codex` flag (if present) - Controls IMPL-002 fix mode
- `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
**Expected Behavior**:
- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
- Generate **minimum 2 task JSON files** (expandable based on complexity):
- **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
- **IMPL-002.json**: Test Execution & Fix Cycle (`@test-fix-agent`)
- **IMPL-003+**: Additional tasks if needed for complex projects
- Generate `IMPL_PLAN.md` with test strategy
- Generate `TODO_LIST.md` with task checklist
**Parse Output**:
- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
- Verify additional `.task/IMPL-*.json` if applicable
- Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
---
#### Phase 5: Return Summary
**Return to User**:
```
Independent test-fix workflow created successfully!
Input: [original input]
Mode: [Session|Prompt]
Test Session: [testSessionId]
Tasks Created:
- IMPL-001: Test Understanding & Generation (@code-developer)
- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
[- IMPL-003+: Additional tasks if applicable]
Test Framework: [detected framework]
Test Files to Generate: [count]
Max Fix Iterations: 5
Fix Mode: [Manual|Codex Automated]
Review artifacts:
- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
- Task list: .workflow/[testSessionId]/TODO_LIST.md
CRITICAL - Next Steps:
1. Review IMPL_PLAN.md
2. **MUST execute: /workflow:test-cycle-execute**
- This command only generated task JSON files
- Test execution and fix iterations happen in test-cycle-execute
- Do NOT attempt to run tests or fixes in main workflow
```
**TodoWrite**: Mark phase 5 completed
**BOUNDARY NOTE**:
- Command completes here - only task JSON files generated
- All test execution, failure detection, CLI analysis, fix generation happens in `/workflow:test-cycle-execute`
- This command does NOT handle test failures or apply fixes
---
### TodoWrite Progress Tracking
Track all 5 phases:
```javascript
TodoWrite({todos: [
{"content": "Create independent test session", "status": "in_progress|completed", "activeForm": "Creating test session"},
{"content": "Gather test coverage context", "status": "pending|in_progress|completed", "activeForm": "Gathering test coverage context"},
{"content": "Analyze test requirements with Gemini", "status": "pending|in_progress|completed", "activeForm": "Analyzing test requirements"},
{"content": "Generate test generation and execution tasks", "status": "pending|in_progress|completed", "activeForm": "Generating test tasks"},
{"content": "Return workflow summary", "status": "pending|in_progress|completed", "activeForm": "Returning workflow summary"}
]})
```
Update status to `in_progress` when starting each phase, `completed` when done.
---
## Task Specifications
Generates minimum 2 tasks (expandable for complex projects):
### IMPL-001: Test Understanding & Generation
**Agent**: `@code-developer`
**Purpose**: Understand source implementation and generate test files
**Task Configuration**:
- Task ID: `IMPL-001`
- `meta.type: "test-gen"`
- `meta.agent: "@code-developer"`
- `context.requirements`: Understand source implementation and generate tests
- `flow_control.target_files`: Test files to create from TEST_ANALYSIS_RESULTS.md section 5
**Execution Flow**:
1. **Understand Phase**:
- Load TEST_ANALYSIS_RESULTS.md and test context
- Understand source code implementation patterns
- Analyze test requirements and conventions
- Identify test scenarios and edge cases
2. **Generation Phase**:
- Generate test files following existing patterns
- Ensure test coverage aligns with requirements
3. **Verification Phase**:
- Verify test completeness and correctness
### IMPL-002: Test Execution & Fix Cycle
**Agent**: `@test-fix-agent`
**Purpose**: Execute initial tests and trigger orchestrator-managed fix cycles
**Note**: This task executes tests and reports results. The test-cycle-execute orchestrator manages all fix iterations, CLI analysis, and fix task generation.
**Task Configuration**:
- Task ID: `IMPL-002`
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
- `meta.use_codex: true|false` (based on `--use-codex` flag)
- `context.depends_on: ["IMPL-001"]`
- `context.requirements`: Execute and fix tests
**Test-Fix Cycle Specification**:
**Note**: This specification describes what test-cycle-execute orchestrator will do. The agent only executes single tasks.
- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → manual_fix (or codex) → retest
- **Tools Configuration** (orchestrator-controlled):
- Gemini for analysis with bug-fix template → surgical fix suggestions
- Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
- **Exit Conditions** (orchestrator-enforced):
- Success: All tests pass
- Failure: Max iterations reached (5)
**Execution Flow**:
1. **Phase 1**: Initial test execution
2. **Phase 2**: Iterative Gemini diagnosis + manual/Codex fixes
3. **Phase 3**: Final validation and certification
### IMPL-003+: Additional Tasks (Optional)
**Scenarios for Multiple Tasks**:
- Large projects requiring per-module test generation
- Separate integration vs unit test tasks
- Specialized test types (performance, security, etc.)
**Agent**: `@code-developer` or specialized agents based on requirements
---
## Artifacts & Output
### Output Files Structure
Created in `.workflow/WFS-test-[session]/`:
```
WFS-test-[session]/
├── workflow-session.json # Session metadata
├── IMPL_PLAN.md # Test generation and execution strategy
├── TODO_LIST.md # Task checklist
├── .task/
│ ├── IMPL-001.json # Test understanding & generation
│ ├── IMPL-002.json # Test execution & fix cycle
│ └── IMPL-*.json # Additional tasks (if applicable)
└── .process/
├── [test-]context-package.json # Context and coverage analysis
└── TEST_ANALYSIS_RESULTS.md # Test requirements and strategy
```
### Session Metadata
**File**: `workflow-session.json`
**Session Mode** includes:
- `workflow_type: "test_session"`
- `source_session_id: "[sourceSessionId]"` (enables automatic cross-session context)
**Prompt Mode** includes:
- `workflow_type: "test_session"`
- No `source_session_id` field
### Complete Data Flow
**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
**Phase Execution Chain**:
1. Phase 1: `session-start` → `WFS-test-user-auth`
2. Phase 2: `test-context-gather` → `test-context-package.json`
3. Phase 3: `test-concept-enhanced` → `TEST_ANALYSIS_RESULTS.md`
4. Phase 4: `test-task-generate` → `IMPL-001.json` + `IMPL-002.json` (+ additional if needed)
5. Phase 5: Return summary
**Command completes after Phase 5**
---
## Reference
### Error Handling
| Phase | Error Condition | Action |
|-------|----------------|--------|
| 1 | Source session not found (session mode) | Return error with source session ID |
| 1 | No completed IMPL tasks (session mode) | Return error, source incomplete |
| 2 | Context gathering failed | Return error, check source artifacts |
| 3 | Gemini analysis failed | Return error, check context package |
| 4 | Task generation failed | Retry once, then return error with details |
### Best Practices
1. **Before Running**:
- Ensure implementation is complete (session mode: check summaries exist)
- Commit all implementation changes
- Review source code quality
2. **After Running**:
- Review generated `IMPL_PLAN.md` before execution
- Check `TEST_ANALYSIS_RESULTS.md` for completeness
- Verify task dependencies in `TODO_LIST.md`
3. **During Execution**:
- Monitor iteration logs in `.process/fix-iteration-*`
- Track progress with `/workflow:status`
- Review Gemini diagnostic outputs
4. **Mode Selection**:
- Use **Session Mode** for completed workflow validation
- Use **Prompt Mode** for ad-hoc test generation
- Use `--use-codex` for autonomous fix application
- Use `--cli-execute` for enhanced generation capabilities
## Related Commands
**Prerequisite Commands**:
- `/workflow:plan` or `/workflow:execute` - Complete implementation session (for Session Mode)
- None for Prompt Mode (ad-hoc test generation)
**Called by This Command** (5 phases):
- `/workflow:session:start` - Phase 1: Create independent test workflow session
- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs with fix cycle specification
- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks
- `/workflow:test-cycle-execute` - Execute test generation and iterative fix cycles
- `/workflow:execute` - Standard execution of generated test tasks

347
.claude/skills/command-guide/reference/commands/workflow/test-gen.md Normal file
View File

@@ -0,0 +1,347 @@
---
name: test-gen
description: Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks
argument-hint: "[--use-codex] [--cli-execute] source-session-id"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# Workflow Test Generation Command (/workflow:test-gen)
## Coordinator Role
**This command is a pure orchestrator**: Creates an independent test-fix workflow session for validating a completed implementation. It reuses the standard planning toolchain with automatic cross-session context gathering.
**Core Principles**:
- **Session Isolation**: Creates new `WFS-test-[source]` session to keep verification separate from implementation
- **Context-First**: Prioritizes gathering code changes and summaries from source session
- **Format Reuse**: Creates standard `IMPL-*.json` task, using `meta.type: "test-fix"` for agent assignment
- **Parameter Simplification**: Tools auto-detect test session type via metadata, no manual cross-session parameters needed
- **Manual First**: Default to manual fixes, use `--use-codex` flag for automated Codex fix application
**Execution Flow**:
1. Initialize TodoWrite → Create test session → Parse session ID
2. Gather cross-session context (automatic) → Parse context path
3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
4. Generate test task from analysis → Return summary
**Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
## Core Rules
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 test session creation
2. **No Preliminary Analysis**: Do not read files or analyze before Phase 1
3. **Parse Every Output**: Extract required data from each phase for next phase
4. **Sequential Execution**: Each phase depends on previous phase's output
5. **Complete All Phases**: Do not return to user until Phase 5 completes (summary returned)
6. **Track Progress**: Update TodoWrite after every phase completion
7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
9. **Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
## 5-Phase Execution
### Phase 1: Create Test Session
**Command**: `SlashCommand(command="/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
**Input**: `sourceSessionId` from user argument (e.g., `WFS-user-auth`)
**Expected Behavior**:
- Creates new session with pattern `WFS-test-[source-slug]` (e.g., `WFS-test-user-auth`)
- Writes metadata to `workflow-session.json`:
- `workflow_type: "test_session"`
- `source_session_id: "[sourceSessionId]"`
- Returns new session ID for subsequent phases
**Parse Output**:
- Extract: new test session ID (store as `testSessionId`)
- Pattern: `WFS-test-[slug]`
**Validation**:
- Source session `.workflow/[sourceSessionId]/` exists
- Source session has completed IMPL tasks (`.summaries/IMPL-*-summary.md`)
- New test session directory created
- Metadata includes `workflow_type` and `source_session_id`
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
---
### Phase 2: Gather Test Context
**Command**: `SlashCommand(command="/workflow:tools:test-context-gather --session [testSessionId]")`
**Input**: `testSessionId` from Phase 1 (e.g., `WFS-test-user-auth`)
**Expected Behavior**:
- Load source session implementation context and summaries
- Analyze test coverage using MCP tools (find existing tests)
- Identify files requiring tests (coverage gaps)
- Detect test framework and conventions
- Generate `test-context-package.json`
**Parse Output**:
- Extract: test context package path (store as `testContextPath`)
- Pattern: `.workflow/[testSessionId]/.process/test-context-package.json`
**Validation**:
- Test context package created
- Contains source session summaries
- Includes coverage gap analysis
- Test framework detected
- Test conventions documented
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
---
### Phase 3: Test Generation Analysis
**Command**: `SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessionId] --context [testContextPath]")`
**Input**:
- `testSessionId` from Phase 1
- `testContextPath` from Phase 2
**Expected Behavior**:
- Use Gemini to analyze coverage gaps and implementation context
- Study existing test patterns and conventions
- Generate test requirements for each missing test file
- Design test generation strategy
- Generate `TEST_ANALYSIS_RESULTS.md`
**Parse Output**:
- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
- Contains test requirements and generation strategy
- Lists test files to create with specifications
**Validation**:
- TEST_ANALYSIS_RESULTS.md exists with complete sections:
- Coverage Assessment
- Test Framework & Conventions
- Test Requirements by File
- Test Generation Strategy
- Implementation Targets (test files to create)
- Success Criteria
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
---
### Phase 4: Generate Test Tasks
**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
**Input**:
- `testSessionId` from Phase 1
- `--use-codex` flag (if present in original command) - Controls IMPL-002 fix mode
- `--cli-execute` flag (if present in original command) - Controls IMPL-001 generation mode
**Expected Behavior**:
- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
- Extract test requirements and generation strategy
- Generate **TWO task JSON files**:
- **IMPL-001.json**: Test Generation task (calls @code-developer)
- **IMPL-002.json**: Test Execution and Fix Cycle task (calls @test-fix-agent)
- Generate IMPL_PLAN.md with test generation and execution strategy
- Generate TODO_LIST.md with both tasks
**Parse Output**:
- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists (test generation)
- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists (test execution & fix)
- Verify `.workflow/[testSessionId]/IMPL_PLAN.md` created
- Verify `.workflow/[testSessionId]/TODO_LIST.md` created
**Validation - IMPL-001.json (Test Generation)**:
- Task ID: `IMPL-001`
- `meta.type: "test-gen"`
- `meta.agent: "@code-developer"`
- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
- `flow_control.pre_analysis`: Load TEST_ANALYSIS_RESULTS.md and test context
- `flow_control.implementation_approach`: Test generation steps
- `flow_control.target_files`: Test files to create from analysis section 5
**Validation - IMPL-002.json (Test Execution & Fix)**:
- Task ID: `IMPL-002`
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
- `meta.use_codex: true|false` (based on --use-codex flag)
- `context.depends_on: ["IMPL-001"]`
- `context.requirements`: Execute and fix tests
- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
- **Cycle pattern**: test → gemini_diagnose → manual_fix (or codex if --use-codex) → retest
- **Tools configuration**: Gemini for analysis with bug-fix template, manual or Codex for fixes
- **Exit conditions**: Success (all pass) or failure (max iterations)
- `flow_control.implementation_approach.modification_points`: 3-phase execution flow
- Phase 1: Initial test execution
- Phase 2: Iterative Gemini diagnosis + manual/Codex fixes (based on flag)
- Phase 3: Final validation and certification
**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
---
### Phase 5: Return Summary (Command Ends Here)
**Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
**Return to User**:
```
Test workflow preparation complete!
Source Session: [sourceSessionId]
Test Session: [testSessionId]
Artifacts Created:
- Test context analysis
- Test generation strategy
- Task definitions (IMPL-001, IMPL-002)
- Implementation plan
Test Framework: [detected framework]
Test Files to Generate: [count]
Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
Review Generated Artifacts:
- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
- Task list: .workflow/[testSessionId]/TODO_LIST.md
- Analysis: .workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
Ready for execution. Use appropriate workflow commands to proceed.
```
**TodoWrite**: Mark phase 5 completed
**Command Boundary**: After this phase, the command terminates and returns to user prompt.
---
## TodoWrite Pattern
Track progress through 5 phases:
```javascript
TodoWrite({todos: [
{"content": "Create independent test session", "status": "in_progress|completed", "activeForm": "Creating test session"},
{"content": "Gather test coverage context", "status": "pending|in_progress|completed", "activeForm": "Gathering test coverage context"},
{"content": "Analyze test requirements with Gemini", "status": "pending|in_progress|completed", "activeForm": "Analyzing test requirements"},
{"content": "Generate test generation and execution tasks", "status": "pending|in_progress|completed", "activeForm": "Generating test tasks"},
{"content": "Return workflow summary", "status": "pending|in_progress|completed", "activeForm": "Returning workflow summary"}
]})
```
Update status to `in_progress` when starting each phase, mark `completed` when done.
## Data Flow
```
┌─────────────────────────────────────────────────────────┐
│ /workflow:test-gen WFS-user-auth │
├─────────────────────────────────────────────────────────┤
│ Phase 1: session-start → WFS-test-user-auth │
│ ↓ │
│ Phase 2: test-context-gather → test-context-package.json│
│ ↓ │
│ Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md│
│ ↓ │
│ Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json│
│ ↓ │
│ Phase 5: Return summary │
└─────────────────────────────────────────────────────────┘
COMMAND ENDS - Control returns to user
Artifacts Created:
├── .workflow/WFS-test-[session]/
│ ├── workflow-session.json
│ ├── IMPL_PLAN.md
│ ├── TODO_LIST.md
│ ├── .task/
│ │ ├── IMPL-001.json (test generation task)
│ │ └── IMPL-002.json (test execution task)
│ └── .process/
│ ├── test-context-package.json
│ └── TEST_ANALYSIS_RESULTS.md
```
## Session Metadata
Test session includes `workflow_type: "test_session"` and `source_session_id` for automatic context gathering.
## Task Output
Generates two task definition files:
- **IMPL-001.json**: Test generation task specification
- Agent: @code-developer
- Input: TEST_ANALYSIS_RESULTS.md
- Output: Test files based on analysis
- **IMPL-002.json**: Test execution and fix cycle specification
- Agent: @test-fix-agent
- Dependency: IMPL-001 must complete first
- Max iterations: 5
- Fix mode: Manual or Codex (based on --use-codex flag)
See `/workflow:tools:test-task-generate` for complete task JSON schemas.
## Error Handling
| Phase | Error | Action |
|-------|-------|--------|
| 1 | Source session not found | Return error with source session ID |
| 1 | No completed IMPL tasks | Return error, source incomplete |
| 2 | Context gathering failed | Return error, check source artifacts |
| 3 | Analysis failed | Return error, check context package |
| 4 | Task generation failed | Retry once, then error with details |
## Output Files
Created in `.workflow/WFS-test-[session]/`:
- `workflow-session.json` - Session metadata
- `.process/test-context-package.json` - Coverage analysis
- `.process/TEST_ANALYSIS_RESULTS.md` - Test requirements
- `.task/IMPL-001.json` - Test generation task
- `.task/IMPL-002.json` - Test execution & fix task
- `IMPL_PLAN.md` - Test plan
- `TODO_LIST.md` - Task checklist
## Task Specifications
**IMPL-001.json Structure**:
- `meta.type: "test-gen"`
- `meta.agent: "@code-developer"`
- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
- `flow_control.target_files`: Test files to create
- `flow_control.implementation_approach`: Test generation strategy
**IMPL-002.json Structure**:
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
- `meta.use_codex`: true/false (based on --use-codex flag)
- `context.depends_on: ["IMPL-001"]`
- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
- Gemini diagnosis template
- Fix application mode (manual/codex)
- Max iterations: 5
- `flow_control.implementation_approach.modification_points`: 3-phase flow
See `/workflow:tools:test-task-generate` for complete JSON schemas.
## Best Practices
1. **Prerequisites**: Ensure source session has completed IMPL tasks with summaries
2. **Clean State**: Commit implementation changes before running test-gen
3. **Review Artifacts**: Check generated IMPL_PLAN.md and TODO_LIST.md before proceeding
4. **Understand Scope**: This command only prepares artifacts; it does not execute tests
## Related Commands
**Prerequisite Commands**:
- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
**Called by This Command** (5 phases):
- `/workflow:session:start` - Phase 1: Create independent test workflow session
- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
- `/workflow:tools:test-task-generate` - Phase 4: Generate test generation and execution task JSONs
- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks
- `/workflow:test-cycle-execute` - Execute test generation and fix cycles
- `/workflow:execute` - Execute generated test tasks

471
.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md Normal file
View File

@@ -0,0 +1,471 @@
---
name: conflict-resolution
description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
argument-hint: "--session WFS-session-id --context path/to/context-package.json"
examples:
- /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
- /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
---
# Conflict Resolution Command
## Purpose
Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
**Scope**: Detection and strategy generation only - NO code modification or task creation.
**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`.
## Core Responsibilities
| Responsibility | Description |
|---------------|-------------|
| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
| **Generate Strategies** | Provide 2-4 resolution options per conflict |
| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
| **User Decision** | Present options, never auto-apply |
| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
## Conflict Categories
### 1. Architecture Conflicts
- Incompatible design patterns
- Module structure changes
- Pattern migration requirements
### 2. API Conflicts
- Breaking contract changes
- Signature modifications
- Public interface impacts
### 3. Data Model Conflicts
- Schema modifications
- Type breaking changes
- Data migration needs
### 4. Dependency Conflicts
- Version incompatibilities
- Setup conflicts
- Breaking updates
## Execution Flow
### Phase 1: Validation
```
1. Verify session directory exists
2. Load context-package.json
3. Check conflict_risk (skip if none/low)
4. Prepare agent task prompt
```
### Phase 2: CLI-Powered Analysis
**Agent Delegation**:
```javascript
Task(subagent_type="cli-execution-agent", prompt=`
## Context
- Session: {session_id}
- Risk: {conflict_risk}
- Files: {existing_files_list}
## Analysis Steps
### 1. Load Context
- Read existing files from conflict_detection.existing_files
- Load plan from .workflow/{session_id}/.process/context-package.json
- Extract role analyses and requirements
### 2. Execute CLI Analysis
Primary (Gemini):
cd {project_root} && gemini -p "
PURPOSE: Detect conflicts between plan and codebase
TASK:
• Compare architectures
• Identify breaking API changes
• Detect data model incompatibilities
• Assess dependency conflicts
MODE: analysis
CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
EXPECTED: Conflict list with severity ratings
RULES: Focus on breaking changes and migration needs
"
Fallback: Qwen (same prompt) → Claude (manual analysis)
### 3. Generate Strategies (2-4 per conflict)
Template per conflict:
- Severity: Critical/High/Medium
- Category: Architecture/API/Data/Dependency
- Affected files + impact
- Options with pros/cons, effort, risk
- Recommended strategy + rationale
### 4. Return Structured Conflict Data
⚠️ DO NOT generate CONFLICT_RESOLUTION.md file
Return JSON format for programmatic processing:
\`\`\`json
{
"conflicts": [
{
"id": "CON-001",
"brief": "一行中文冲突摘要",
"severity": "Critical|High|Medium",
"category": "Architecture|API|Data|Dependency",
"affected_files": [
".workflow/{session}/.brainstorm/guidance-specification.md",
".workflow/{session}/.brainstorm/system-architect/analysis.md"
],
"description": "详细描述冲突 - 什么不兼容",
"impact": {
"scope": "影响的模块/组件",
"compatibility": "Yes|No|Partial",
"migration_required": true|false,
"estimated_effort": "人天估计"
},
"strategies": [
{
"name": "策略名称（中文）",
"approach": "实现方法简述",
"complexity": "Low|Medium|High",
"risk": "Low|Medium|High",
"effort": "时间估计",
"pros": ["优点1", "优点2"],
"cons": ["缺点1", "缺点2"],
"modifications": [
{
"file": ".workflow/{session}/.brainstorm/guidance-specification.md",
"section": "## 2. System Architect Decisions",
"change_type": "update",
"old_content": "原始内容片段（用于定位）",
"new_content": "修改后的内容",
"rationale": "为什么这样改"
},
{
"file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
"section": "## Design Decisions",
"change_type": "update",
"old_content": "原始内容片段",
"new_content": "修改后的内容",
"rationale": "修改理由"
}
]
},
{
"name": "策略2名称",
"approach": "...",
"complexity": "Medium",
"risk": "Low",
"effort": "1-2天",
"pros": ["优点"],
"cons": ["缺点"],
"modifications": [...]
}
],
"recommended": 0,
"modification_suggestions": [
"建议1：具体的修改方向或注意事项",
"建议2：可能需要考虑的边界情况",
"建议3：相关的最佳实践或模式"
]
}
],
"summary": {
"total": 2,
"critical": 1,
"high": 1,
"medium": 0
}
}
\`\`\`
⚠️ CRITICAL Requirements for modifications field:
- old_content: Must be exact text from target file (20-100 chars for unique match)
- new_content: Complete replacement text (maintains formatting)
- change_type: "update" (replace), "add" (insert), "remove" (delete)
- file: Full path relative to project root
- section: Markdown heading for context (helps locate position)
- Minimum 2 strategies per conflict, max 4
- All text in Chinese for user-facing fields (brief, name, pros, cons)
- modification_suggestions: 2-5 actionable suggestions for custom handling (Chinese)
Quality Standards:
- Each strategy must have actionable modifications
- old_content must be precise enough for Edit tool matching
- new_content preserves markdown formatting and structure
- Recommended strategy (index) based on lowest complexity + risk
- modification_suggestions must be specific, actionable, and context-aware
- Each suggestion should address a specific aspect (compatibility, migration, testing, etc.)
`)
```
**Agent Internal Flow**:
```
1. Load context package
2. Check conflict_risk (exit if none/low)
3. Read existing files + plan artifacts
4. Run CLI analysis (Gemini→Qwen→Claude)
5. Parse conflict findings
6. Generate 2-4 strategies per conflict with modifications
7. Return JSON to stdout (NOT file write)
8. Return execution log path
```
### Phase 3: User Confirmation via Text Interaction
**Command parses agent JSON output and presents conflicts to user via text**:
```javascript
// 1. Parse agent JSON output
const conflictData = JSON.parse(agentOutput);
const conflicts = conflictData.conflicts; // No 4-conflict limit
// 2. Format conflicts as text output (max 10 per round)
const batchSize = 10;
const batches = chunkArray(conflicts, batchSize);
for (const [batchIdx, batch] of batches.entries()) {
const totalBatches = batches.length;
// Output batch header
console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
// Output each conflict in batch
batch.forEach((conflict, idx) => {
const questionNum = batchIdx * batchSize + idx + 1;
console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
conflict.strategies.forEach((strategy, sIdx) => {
const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
console.log(`${optionLetter}) ${strategy.name}`);
console.log(` 说明：${strategy.approach}`);
console.log(` 复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
});
// Add custom option
const customLetter = String.fromCharCode(97 + conflict.strategies.length);
console.log(`${customLetter}) 自定义修改`);
console.log(` 说明：根据修改建议自行处理，不应用预设策略`);
// Show modification suggestions
if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
console.log(` 修改建议：`);
conflict.modification_suggestions.forEach(suggestion => {
console.log(` - ${suggestion}`);
});
}
console.log();
});
console.log(`请回答 (格式: 1a 2b 3c...)：`);
// Wait for user input
const userInput = await readUserInput();
// Parse answers
const answers = parseUserAnswers(userInput, batch);
}
// 3. Build selected strategies (exclude custom selections)
const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
const customConflicts = answers.filter(a => a.isCustom).map(a => ({
id: a.conflict.id,
brief: a.conflict.brief,
suggestions: a.conflict.modification_suggestions
}));
```
**Text Output Example**:
```markdown
===== 冲突解决 (第 1/1 轮) =====
【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
a) 渐进式迁移
说明：保留现有系统，逐步迁移到新方案
复杂度: Medium | 风险: Low | 工作量: 3-5天
b) 完全重写
说明：废弃旧系统，从零实现新认证
复杂度: High | 风险: Medium | 工作量: 7-10天
c) 自定义修改
说明：根据修改建议自行处理，不应用预设策略
修改建议：
- 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
- 检查JWT token格式和验证逻辑是否需要调整
- 确保用户会话管理与新架构保持一致
【问题2 - Data】CON-002: 数据库 schema 冲突
a) 添加迁移脚本
说明：创建数据库迁移脚本处理 schema 变更
复杂度: Low | 风险: Low | 工作量: 1-2天
b) 自定义修改
说明：根据修改建议自行处理，不应用预设策略
修改建议：
- 检查现有表结构是否支持新增字段，避免破坏性变更
- 考虑使用数据库版本控制工具（如Flyway或Liquibase）
- 准备数据迁移和回滚策略
请回答 (格式: 1a 2b)：
```
**User Input Examples**:
- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
### Phase 4: Apply Modifications
```javascript
// 1. Extract modifications from selected strategies
const modifications = [];
selectedStrategies.forEach(strategy => {
if (strategy !== "skip") {
modifications.push(...strategy.modifications);
}
});
// 2. Apply each modification using Edit tool
modifications.forEach(mod => {
if (mod.change_type === "update") {
Edit({
file_path: mod.file,
old_string: mod.old_content,
new_string: mod.new_content
});
}
// Handle "add" and "remove" similarly
});
// 3. Update context-package.json
const contextPackage = JSON.parse(Read(contextPath));
contextPackage.conflict_detection.conflict_risk = "resolved";
contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
contextPackage.conflict_detection.resolved_at = new Date().toISOString();
Write(contextPath, JSON.stringify(contextPackage, null, 2));
// 4. Output custom conflict summary (if any)
if (customConflicts.length > 0) {
console.log("\n===== 需要自定义处理的冲突 =====\n");
customConflicts.forEach(conflict => {
console.log(`【${conflict.id}】${conflict.brief}`);
console.log("修改建议：");
conflict.suggestions.forEach(suggestion => {
console.log(` - ${suggestion}`);
});
console.log();
});
}
// 5. Return summary
return {
resolved: modifications.length,
custom: customConflicts.length,
modified_files: [...new Set(modifications.map(m => m.file))],
custom_conflicts: customConflicts
};
```
**Validation**:
```
✓ Agent returns valid JSON structure
✓ Text output displays all conflicts (max 10 per round)
✓ User selections captured correctly
✓ Edit tool successfully applies modifications
✓ guidance-specification.md updated
✓ Role analyses (*.md) updated
✓ context-package.json marked as resolved
✓ Agent log saved to .workflow/{session_id}/.chat/
```
## Output Format: Agent JSON Response
**Focus**: Structured conflict data with actionable modifications for programmatic processing.
**Format**: JSON to stdout (NO file generation)
**Structure**: Defined in Phase 2, Step 4 (agent prompt)
### Key Requirements
| Requirement | Details |
|------------|---------|
| **Conflict batching** | Max 10 conflicts per round (no total limit) |
| **Strategy count** | 2-4 strategies per conflict |
| **Modifications** | Each strategy includes file paths, old_content, new_content |
| **User-facing text** | Chinese (brief, strategy names, pros/cons) |
| **Technical fields** | English (severity, category, complexity, risk) |
| **old_content precision** | 20-100 chars for unique Edit tool matching |
| **File targets** | guidance-specification.md, role analyses (*.md) |
## Error Handling
### Recovery Strategy
```
1. Pre-check: Verify conflict_risk ≥ medium
2. Monitor: Track agent via Task tool
3. Validate: Parse agent JSON output
4. Recover:
- Agent failure → check logs + report error
- Invalid JSON → retry once with Claude fallback
- CLI failure → fallback to Claude analysis
- Edit tool failure → report affected files + rollback option
- User cancels → mark as "unresolved", continue to task-generate
5. Degrade: If all fail, generate minimal conflict report and skip modifications
```
### Rollback Handling
```
If Edit tool fails mid-application:
1. Log all successfully applied modifications
2. Output rollback option via text interaction
3. If rollback selected: restore files from git or backups
4. If continue: mark partial resolution in context-package.json
```
## Integration
### Interface
**Input**:
- `--session` (required): WFS-{session-id}
- `--context` (required): context-package.json path
- Requires: `conflict_risk ≥ medium`
**Output**:
- Modified files:
- `.workflow/{session_id}/.brainstorm/guidance-specification.md`
- `.workflow/{session_id}/.brainstorm/{role}/analysis.md`
- `.workflow/{session_id}/.process/context-package.json` (conflict_risk → resolved)
- NO report file generation
**User Interaction**:
- Text-based strategy selection (max 10 conflicts per round)
- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
### Success Criteria
```
✓ CLI analysis returns valid JSON structure
✓ Conflicts presented in batches (max 10 per round)
✓ Min 2 strategies per conflict with modifications
✓ Each conflict includes 2-5 modification_suggestions
✓ Text output displays all conflicts correctly with suggestions
✓ User selections captured and processed
✓ Edit tool applies modifications successfully
✓ Custom conflicts displayed with suggestions for manual handling
✓ guidance-specification.md updated with resolved conflicts
✓ Role analyses (*.md) updated with resolved conflicts
✓ context-package.json marked as "resolved"
✓ No CONFLICT_RESOLUTION.md file generated
✓ Modification summary includes custom conflict count
✓ Agent log saved to .workflow/{session_id}/.chat/
✓ Error handling robust (validate/retry/degrade)
```
## Related Commands
| Command | Relationship |
|---------|--------------|
| `/workflow:tools:context-gather` | Generates input conflict_detection data |
| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

282
.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md Normal file
View File

@@ -0,0 +1,282 @@
---
name: gather
description: Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON
argument-hint: "--session WFS-session-id \"task description\""
examples:
- /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
- /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
- /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
allowed-tools: Task(*), Read(*), Glob(*)
---
# Context Gather Command (/workflow:tools:context-gather)
## Overview
Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
**Agent**: `context-search-agent` (`.claude/agents/context-search-agent.md`)
## Core Philosophy
- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
- **Detection-First**: Check for existing context-package before executing
- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
- **Standardized Output**: Generate `.workflow/{session}/.process/context-package.json`
## Execution Flow
### Step 1: Context-Package Detection
**Execute First** - Check if valid package already exists:
```javascript
const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
if (file_exists(contextPackagePath)) {
const existing = Read(contextPackagePath);
// Validate package belongs to current session
if (existing?.metadata?.session_id === session_id) {
console.log("✅ Valid context-package found for session:", session_id);
console.log("📊 Stats:", existing.statistics);
console.log("⚠️ Conflict Risk:", existing.conflict_detection.risk_level);
return existing; // Skip execution, return existing
} else {
console.warn("⚠️ Invalid session_id in existing package, re-generating...");
}
}
```
### Step 2: Invoke Context-Search Agent
**Only execute if Step 1 finds no valid package**
```javascript
Task(
subagent_type="context-search-agent",
description="Gather comprehensive context for plan",
prompt=`
You are executing as context-search-agent (.claude/agents/context-search-agent.md).
## Execution Mode
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
## Session Information
- **Session ID**: ${session_id}
- **Task Description**: ${task_description}
- **Output Path**: .workflow/${session_id}/.process/context-package.json
## Mission
Execute complete context-search-agent workflow for implementation planning:
### Phase 1: Initialization & Pre-Analysis
1. **Detection**: Check for existing context-package (early exit if valid)
2. **Foundation**: Initialize code-index, get project structure, load docs
3. **Analysis**: Extract keywords, determine scope, classify complexity
### Phase 2: Multi-Source Context Discovery
Execute all 4 discovery tracks:
- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
### Phase 3: Synthesis, Assessment & Packaging
1. Apply relevance scoring and build dependency graph
2. Synthesize 4-source data (archive > docs > code > web)
3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
4. Perform conflict detection with risk assessment
5. **Inject historical conflicts** from archive analysis into conflict_detection
6. Generate and validate context-package.json
## Output Requirements
Complete context-package.json with:
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
- **project_context**: architecture_patterns, coding_conventions, tech_stack
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
- **dependencies**: {internal[], external[]} with dependency graph
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
## Quality Validation
Before completion verify:
- [ ] Valid JSON format with all required fields
- [ ] File relevance accuracy >80%
- [ ] Dependency graph complete (max 2 transitive levels)
- [ ] Conflict risk level calculated correctly
- [ ] No sensitive data exposed
- [ ] Total files ≤50 (prioritize high-relevance)
Execute autonomously following agent documentation.
Report completion with statistics.
`
)
```
### Step 3: Output Verification
After agent completes, verify output:
```javascript
// Verify file was created
const outputPath = `.workflow/${session_id}/.process/context-package.json`;
if (!file_exists(outputPath)) {
throw new Error("❌ Agent failed to generate context-package.json");
}
```
## Parameter Reference
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) |
| `task_description` | string | ✅ | Detailed task description for context extraction |
## Output Schema
Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema.
**Key Sections**:
- **metadata**: Session info, keywords, complexity, tech stack
- **project_context**: Architecture patterns, conventions, tech stack
- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
- **dependencies**: Internal and external dependency graphs
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
## Historical Archive Analysis
### Track 1: Query Archive Manifest
The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
**Step 1: Check for Archive Manifest**
```bash
# Check if archive manifest exists
if [[ -f .workflow/.archives/manifest.json ]]; then
# Manifest available for querying
fi
```
**Step 2: Extract Task Keywords**
```javascript
// From current task description, extract key entities and operations
const keywords = extractKeywords(task_description);
// Examples: ["User", "model", "authentication", "JWT", "reporting"]
```
**Step 3: Search Archive for Relevant Sessions**
```javascript
// Query manifest for sessions with matching tags or descriptions
const relevantArchives = archives.filter(archive => {
return archive.tags.some(tag => keywords.includes(tag)) ||
keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
});
```
**Step 4: Extract Watch Patterns**
```javascript
// For each relevant archive, check watch_patterns for applicability
const historicalConflicts = [];
relevantArchives.forEach(archive => {
archive.lessons.watch_patterns?.forEach(pattern => {
// Check if pattern trigger matches current task
if (isPatternRelevant(pattern.pattern, task_description)) {
historicalConflicts.push({
source_session: archive.session_id,
pattern: pattern.pattern,
action: pattern.action,
files_to_check: pattern.related_files,
archived_at: archive.archived_at
});
}
});
});
```
**Step 5: Inject into Context Package**
```json
{
"conflict_detection": {
"risk_level": "medium",
"risk_factors": ["..."],
"affected_modules": ["..."],
"mitigation_strategy": "...",
"historical_conflicts": [
{
"source_session": "WFS-auth-feature",
"pattern": "When modifying User model",
"action": "Check reporting-service and auditing-service dependencies",
"files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
"archived_at": "2025-09-16T09:00:00Z"
}
]
}
}
```
### Risk Level Escalation
If `historical_conflicts` array is not empty, minimum risk level should be "medium":
```javascript
if (historicalConflicts.length > 0 && currentRisk === "low") {
conflict_detection.risk_level = "medium";
conflict_detection.risk_factors.push(
`${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
);
}
```
### Archive Query Algorithm
```markdown
1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
2. IF manifest exists:
a. Load manifest.json
b. Extract keywords from task_description (nouns, verbs, technical terms)
c. Filter archives where:
- ANY tag matches keywords (case-insensitive) OR
- description contains keywords (case-insensitive substring match)
d. For each relevant archive:
- Read lessons.watch_patterns array
- Check if pattern.pattern keywords overlap with task_description
- If relevant: Add to historical_conflicts array
e. IF historical_conflicts.length > 0:
- Set risk_level = max(current_risk, "medium")
- Add to risk_factors
3. Continue to Track 2 (reference documentation)
```
## Usage Examples
### Basic Usage
```bash
/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
```
## Success Criteria
- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
- ✅ Contains >80% relevant files based on task keywords
- ✅ Execution completes within 2 minutes
- ✅ All required schema fields present and valid
- ✅ Conflict risk accurately assessed
- ✅ Agent reports completion with statistics
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
## Notes
- **Detection-first**: Always check for existing package before invoking agent
- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
- **No redundancy**: This command is a thin orchestrator, all logic in agent
- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call

363
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md Normal file
View File

@@ -0,0 +1,363 @@
---
name: task-generate-agent
description: Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning
argument-hint: "--session WFS-session-id [--cli-execute]"
examples:
- /workflow:tools:task-generate-agent --session WFS-auth
- /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
---
# Autonomous Task Generation Command
## Overview
Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
## Core Philosophy
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
- **Memory-First**: Reuse loaded documents from conversation memory
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
- **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
## Execution Lifecycle
### Phase 1: Discovery & Context Loading
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
**Agent Context Package**:
```javascript
{
"session_id": "WFS-[session-id]",
"execution_mode": "agent-mode" | "cli-execute-mode", // Determined by flag
"task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
| "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
// Path selected by command based on --cli-execute flag, agent reads it
"session_metadata": {
// If in memory: use cached content
// Else: Load from .workflow/{session-id}/workflow-session.json
},
"brainstorm_artifacts": {
// Loaded from context-package.json → brainstorm_artifacts section
"role_analyses": [
{
"role": "system-architect",
"files": [{"path": "...", "type": "primary|supplementary"}]
}
],
"guidance_specification": {"path": "...", "exists": true},
"synthesis_output": {"path": "...", "exists": true},
"conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium
},
"context_package_path": ".workflow/{session-id}/.process/context-package.json",
"context_package": {
// If in memory: use cached content
// Else: Load from .workflow/{session-id}/.process/context-package.json
},
"mcp_capabilities": {
"code_index": true,
"exa_code": true,
"exa_web": true
}
}
```
**Discovery Actions**:
1. **Load Session Context** (if not in memory)
```javascript
if (!memory.has("workflow-session.json")) {
Read(.workflow/{session-id}/workflow-session.json)
}
```
2. **Load Context Package** (if not in memory)
```javascript
if (!memory.has("context-package.json")) {
Read(.workflow/{session-id}/.process/context-package.json)
}
```
3. **Extract & Load Role Analyses** (from context-package.json)
```javascript
// Extract role analysis paths from context package
const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
.flatMap(role => role.files.map(f => f.path));
// Load each role analysis file
roleAnalysisPaths.forEach(path => Read(path));
```
4. **Load Conflict Resolution** (from context-package.json, if exists)
```javascript
if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
}
```
5. **Code Analysis with Native Tools** (optional - enhance understanding)
```bash
# Find relevant files for task context
find . -name "*auth*" -type f
rg "authentication|oauth" -g "*.ts"
```
6. **MCP External Research** (optional - gather best practices)
```javascript
// Get external examples for implementation
mcp__exa__get_code_context_exa(
query="TypeScript JWT authentication best practices",
tokensNum="dynamic"
)
```
### Phase 2: Agent Execution (Document Generation)
**Pre-Agent Template Selection** (Command decides path before invoking agent):
```javascript
// Command checks flag and selects template PATH (not content)
const templatePath = hasCliExecuteFlag
? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
: "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
```
**Agent Invocation**:
```javascript
Task(
subagent_type="action-planning-agent",
description="Generate task JSON and implementation plan",
prompt=`
## Execution Context
**Session ID**: WFS-{session-id}
**Execution Mode**: {agent-mode | cli-execute-mode}
**Task JSON Template Path**: {template_path}
## Phase 1: Discovery Results (Provided Context)
### Session Metadata
{session_metadata_content}
### Role Analyses (Enhanced by Synthesis)
{role_analyses_content}
- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
### Artifacts Inventory
- **Guidance Specification**: {guidance_spec_path}
- **Role Analyses**: {role_analyses_list}
### Context Package
{context_package_summary}
- Includes conflict_risk assessment
### Conflict Resolution (Conditional)
If conflict_risk was medium/high, modifications have been applied to:
- **guidance-specification.md**: Design decisions updated to resolve conflicts
- **Role analyses (*.md)**: Recommendations adjusted for compatibility
- **context-package.json**: Marked as "resolved" with conflict IDs
- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
### MCP Analysis Results (Optional)
**Code Structure**: {mcp_code_index_results}
**External Research**: {mcp_exa_research_results}
## Phase 2: Document Generation Task
### Task Decomposition Standards
**Core Principle**: Task Merging Over Decomposition
- **Merge Rule**: Execute together when possible
- **Decompose Only When**:
- Excessive workload (>2500 lines or >6 files)
- Different tech stacks or domains
- Sequential dependency blocking
- Parallel execution needed
**Task Limits**:
- **Maximum 10 tasks** (hard limit)
- **Function-based**: Complete units (logic + UI + tests + config)
- **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
### Required Outputs
#### 1. Task JSON Files (.task/IMPL-*.json)
**Location**: .workflow/{session-id}/.task/
**Template**: Read from the template path provided above
**Task JSON Template Loading**:
\`\`\`
Read({template_path})
\`\`\`
**Important**:
- Read the template from the path provided in context
- Use the template structure exactly as written
- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
- Include MCP tool integration in pre_analysis steps
- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
#### 2. IMPL_PLAN.md
**Location**: .workflow/{session-id}/IMPL_PLAN.md
**IMPL_PLAN Template**:
\`\`\`
$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
\`\`\`
**Important**:
- Use the template above for IMPL_PLAN.md generation
- Replace all {placeholder} variables with actual session-specific values
- Populate CCW Workflow Context based on actual phase progression
- Extract content from role analyses and context-package.json
- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
#### 3. TODO_LIST.md
**Location**: .workflow/{session-id}/TODO_LIST.md
**Structure**:
\`\`\`markdown
# Tasks: {Session Topic}
## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
- [ ] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json)
- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
## Status Legend
- \`▸\` = Container task (has subtasks)
- \`- [ ]\` = Pending leaf task
- \`- [x]\` = Completed leaf task
\`\`\`
### Execution Instructions for Agent
**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
**Note**: The correct task JSON template path has been pre-selected by the command based on the `--cli-execute` flag and is provided in the context as `{template_path}`.
**Step 1: Load Task JSON Template**
- Read template from the provided path: `Read({template_path})`
- This template is already the correct one based on execution mode
**Step 2: Extract and Decompose Tasks**
- Parse role analysis.md files for requirements, design specs, and task recommendations
- Review synthesis enhancements and clarifications in role analyses
- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
- Apply task merging rules (merge when possible, decompose only when necessary)
- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
- Ensure task count ≤10
**Step 3: Generate Task JSON Files**
- Use the template structure from Step 1
- Create .task/IMPL-*.json files with proper structure
- Replace all {placeholder} variables with actual session paths
- Embed artifacts array with brainstorming outputs
- Include MCP tool integration in pre_analysis steps
**Step 4: Create IMPL_PLAN.md**
- Use IMPL_PLAN template
- Populate all sections with session-specific content
- List artifacts with priorities and usage guidelines
- Document execution strategy and dependencies
**Step 5: Generate TODO_LIST.md**
- Create task progress checklist matching generated JSONs
- Use proper status indicators (▸, [ ], [x])
- Link to task JSON files
**Step 6: Update Session State**
- Update workflow-session.json with task count and artifact inventory
- Mark session ready for execution
### MCP Enhancement Examples
**Code Index Usage**:
\`\`\`javascript
// Discover authentication-related files
bash(find . -name "*auth*" -type f)
// Search for OAuth patterns
bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
// Get file summary for key components
bash(rg "^(class|function|export|interface)" src/auth/index.ts)
\`\`\`
**Exa Research Usage**:
\`\`\`javascript
// Get best practices for task implementation
mcp__exa__get_code_context_exa(
query="TypeScript OAuth2 implementation patterns",
tokensNum="dynamic"
)
// Research specific API usage
mcp__exa__get_code_context_exa(
query="Express.js JWT middleware examples",
tokensNum=5000
)
\`\`\`
### Quality Validation
Before completion, verify:
- [ ] All task JSON files created in .task/ directory
- [ ] Each task JSON has 5 required fields
- [ ] Artifact references correctly mapped
- [ ] Flow control includes artifact loading steps
- [ ] MCP tool integration added where appropriate
- [ ] IMPL_PLAN.md follows required structure
- [ ] TODO_LIST.md matches task JSONs
- [ ] Dependency graph is acyclic
- [ ] Task count within limits (≤10)
- [ ] Session state updated
## Output
Generate all three documents and report completion status:
- Task JSON files created: N files
- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
- MCP enhancements: code-index, exa-research
- Session ready for execution: /workflow:execute
`
)
```
### Agent Context Passing
**Memory-Aware Context Assembly**:
```javascript
// Assemble context package for agent
const agentContext = {
session_id: "WFS-[id]",
// Use memory if available, else load
session_metadata: memory.has("workflow-session.json")
? memory.get("workflow-session.json")
: Read(.workflow/WFS-[id]/workflow-session.json),
context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
context_package: memory.has("context-package.json")
? memory.get("context-package.json")
: Read(".workflow/WFS-[id]/.process/context-package.json"),
// Extract brainstorm artifacts from context package
brainstorm_artifacts: extractBrainstormArtifacts(context_package),
// Load role analyses using paths from context package
role_analyses: brainstorm_artifacts.role_analyses
.flatMap(role => role.files)
.map(file => Read(file.path)),
// Load conflict resolution if exists (from context package)
conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
? Read(brainstorm_artifacts.conflict_resolution.path)
: null,
// Optional MCP enhancements
mcp_analysis: executeMcpDiscovery()
}
```

555
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md Normal file
View File

@@ -0,0 +1,555 @@
---
name: task-generate-tdd
description: Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation
argument-hint: "--session WFS-session-id [--agent]"
allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
---
# TDD Task Generation Command
## Overview
Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
## Task Strategy & Philosophy
### Optimized Task Structure (Current)
- **1 feature = 1 task** containing complete TDD cycle internally
- Each task executes Red-Green-Refactor phases sequentially
- Task count = Feature count (typically 5 features = 5 tasks)
- **Benefits**:
- 70% reduction in task management overhead
- Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
- Simpler dependency management
- Maintains TDD rigor through internal phase structure
**Previous Approach** (Deprecated):
- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
- 5 features = 15 tasks with complex dependency chains
- High context switching cost between phases
### When to Use Subtasks
- Feature complexity >2500 lines or >6 files per TDD cycle
- Multiple independent sub-features needing parallel execution
- Strong technical dependency blocking (e.g., API before UI)
- Different tech stacks or domains within feature
### Task Limits
- **Maximum 10 tasks** (hard limit for TDD workflows)
- **Feature-based**: Complete functional units with internal TDD cycles
- **Hierarchy**: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features)
- **Re-scope**: If >10 tasks needed, break project into multiple TDD workflow sessions
### TDD Cycle Mapping
- **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
- **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
- **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary
### Core Principles
- **TDD-First**: Every feature starts with a failing test (Red phase)
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
- **Phase-Explicit**: Internal phases clearly marked in flow_control.implementation_approach
- **Task Merging**: Prefer single task per feature over decomposition
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
- **Artifact-Aware**: Integrates brainstorming outputs
- **Memory-First**: Reuse loaded documents from memory
- **Context-Aware**: Analyzes existing codebase and test patterns
- **Iterative Green Phase**: Auto-diagnose and fix test failures with Gemini + optional Codex
- **Safety-First**: Auto-revert on max iterations to prevent broken state
## Core Responsibilities
- Parse analysis results and identify testable features
- Generate feature-complete tasks with internal TDD cycles (1 task per simple feature)
- Apply task merging strategy by default, create subtasks only when complexity requires
- Generate IMPL_PLAN.md with TDD Implementation Tasks section
- Generate TODO_LIST.md with internal TDD phase indicators
- Update session state for TDD execution with task count compliance
## Execution Lifecycle
### Phase 1: Input Validation & Discovery
**Memory-First Rule**: Skip file loading if documents already in conversation memory
1. **Session Validation**
- If session metadata in memory → Skip loading
- Else: Load `.workflow/{session_id}/workflow-session.json`
2. **Conflict Resolution Check** (NEW - Priority Input)
- If CONFLICT_RESOLUTION.md exists → Load selected strategies
- Else: Skip to brainstorming artifacts
- Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md`
3. **Artifact Discovery**
- If artifact inventory in memory → Skip scanning
- Else: Scan `.workflow/{session_id}/.brainstorming/` directory
- Detect: role analysis documents, guidance-specification.md, role analyses
4. **Context Package Loading**
- Load `.workflow/{session_id}/.process/context-package.json`
- Load `.workflow/{session_id}/.process/test-context-package.json` (if exists)
### Phase 2: TDD Task JSON Generation
**Input Sources** (priority order):
1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies
2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.)
3. **Context Package**: `.process/context-package.json` - Project structure and requirements
4. **Test Context**: `.process/test-context-package.json` - Existing test patterns
**TDD Task Structure includes**:
- Feature list with testable requirements
- Test cases for Red phase
- Implementation requirements for Green phase (with test-fix cycle)
- Refactoring opportunities
- Task dependencies and execution order
- Conflict resolution decisions (if applicable)
### Phase 3: Task JSON & IMPL_PLAN.md Generation
#### Task Structure (Feature-Complete with Internal TDD)
For each feature, generate task(s) with ID format:
- **IMPL-N** - Single task containing complete TDD cycle (Red-Green-Refactor)
- **IMPL-N.M** - Sub-tasks only when feature is complex (>2500 lines or technical blocking)
**Task Dependency Rules**:
- **Sequential features**: IMPL-2 depends_on ["IMPL-1"] if Feature 2 needs Feature 1
- **Independent features**: No dependencies, can execute in parallel
- **Complex features**: IMPL-N.2 depends_on ["IMPL-N.1"] for subtask ordering
**Agent Assignment**:
- **All IMPL tasks** → `@code-developer` (handles full TDD cycle)
- Agent executes Red, Green, Refactor phases sequentially within task
**Meta Fields**:
- `meta.type`: "feature" (TDD-driven feature implementation)
- `meta.agent`: "@code-developer"
- `meta.tdd_workflow`: true (enables TDD-specific flow)
- `meta.tdd_phase`: Not used (phases are in flow_control.implementation_approach)
- `meta.max_iterations`: 3 (for Green phase test-fix cycle)
- `meta.use_codex`: false (manual fixes by default)
#### Task JSON Structure Reference
**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
```json
{
"id": "IMPL-N", // Task identifier
"title": "Feature description with TDD", // Human-readable title
"status": "pending", // pending | in_progress | completed | container
"context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
"meta": {
"type": "feature", // Task type
"agent": "@code-developer", // Assigned agent
"tdd_workflow": true, // REQUIRED: Enables TDD flow
"max_iterations": 3, // Green phase test-fix cycle limit
"use_codex": false // false=manual fixes, true=Codex automated fixes
},
"context": {
"requirements": [ // Feature requirements with TDD phases
"Feature description",
"Red: Test scenarios to write",
"Green: Implementation approach with test-fix cycle",
"Refactor: Code quality improvements"
],
"tdd_cycles": [ // OPTIONAL: Detailed test cycles
{
"cycle": 1,
"feature": "Specific functionality",
"test_focus": "What to test",
"expected_failure": "Why test should fail initially"
}
],
"focus_paths": ["D:\\project\\src\\path", "./tests/path"], // Absolute or clear relative paths from project root
"acceptance": [ // Success criteria
"All tests pass (Red → Green)",
"Code refactored (Refactor complete)",
"Test coverage ≥80%"
],
"depends_on": [] // Task dependencies
},
"flow_control": {
"pre_analysis": [ // OPTIONAL: Pre-execution checks
{
"step": "check_test_framework",
"action": "Verify test framework",
"command": "bash(npm list jest)",
"output_to": "test_framework_info",
"on_error": "warn"
}
],
"implementation_approach": [ // REQUIRED: 3 TDD phases
{
"step": 1,
"title": "RED Phase: Write failing tests",
"tdd_phase": "red", // REQUIRED: Phase identifier
"description": "Write comprehensive failing tests",
"modification_points": ["Files/changes to make"],
"logic_flow": ["Step-by-step process"],
"acceptance": ["Phase success criteria"],
"depends_on": [],
"output": "failing_tests"
},
{
"step": 2,
"title": "GREEN Phase: Implement to pass tests",
"tdd_phase": "green", // REQUIRED: Phase identifier
"description": "Minimal implementation with test-fix cycle",
"modification_points": ["Implementation files"],
"logic_flow": [
"Implement minimal code",
"Run tests",
"If fail → Enter iteration loop (max 3):",
" 1. Extract failure messages",
" 2. Gemini bug-fix diagnosis",
" 3. Apply fixes",
" 4. Rerun tests",
"If max_iterations → Auto-revert"
],
"acceptance": ["All tests pass"],
"command": "bash(npm test -- tests/path/)",
"depends_on": [1],
"output": "passing_implementation"
},
{
"step": 3,
"title": "REFACTOR Phase: Improve code quality",
"tdd_phase": "refactor", // REQUIRED: Phase identifier
"description": "Refactor while keeping tests green",
"modification_points": ["Quality improvements"],
"logic_flow": ["Incremental refactoring with test verification"],
"acceptance": ["Tests still pass", "Code quality improved"],
"command": "bash(npm run lint && npm test)",
"depends_on": [2],
"output": "refactored_implementation"
}
],
"post_completion": [ // OPTIONAL: Final verification
{
"step": "verify_full_tdd_cycle",
"action": "Confirm complete TDD cycle",
"command": "bash(npm test && echo 'TDD complete')",
"output_to": "final_validation",
"on_error": "fail"
}
],
"error_handling": { // OPTIONAL: Error recovery
"green_phase_max_iterations": {
"action": "revert_all_changes",
"commands": ["bash(git reset --hard HEAD)"],
"report": "Generate failure report"
}
}
}
}
```
**Key JSON Fields Summary**:
- `meta.tdd_workflow`: Must be `true`
- `meta.max_iterations`: Green phase fix cycle limit (default: 3)
- `meta.use_codex`: Automated fixes (false=manual, true=Codex)
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor"
- `context.tdd_cycles`: Optional detailed test cycle specifications
- `context.parent`: Required for subtasks (IMPL-N.M)
#### IMPL_PLAN.md Structure
Generate IMPL_PLAN.md with 8-section structure:
**Frontmatter** (required fields):
```yaml
---
identifier: WFS-{session-id}
source: "User requirements" | "File: path"
conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md # if exists
context_package: .workflow/{session-id}/.process/context-package.json
context_package_path: .workflow/{session-id}/.process/context-package.json
test_context: .workflow/{session-id}/.process/test-context-package.json # if exists
workflow_type: "tdd"
verification_history:
conflict_resolution: "executed | skipped" # based on conflict_risk
action_plan_verify: "pending"
phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
feature_count: N
task_count: N # ≤10 total
task_breakdown:
simple_features: K
complex_features: L
total_subtasks: M
tdd_workflow: true
---
```
**8 Sections Structure**:
```markdown
# Implementation Plan: {Project Title}
## 1. Summary
- Core requirements and objectives (2-3 paragraphs)
- TDD-specific technical approach
## 2. Context Analysis
- CCW Workflow Context (Phase progression, Quality gates)
- Context Package Summary (Focus paths, Test context)
- Project Profile (Type, Scale, Tech Stack, Timeline)
- Module Structure (Directory tree)
- Dependencies (Primary, Testing, Development)
- Patterns & Conventions
## 3. Brainstorming Artifacts Reference
- Artifact Usage Strategy
- CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
- role analysis documents (primary reference)
- test-context-package.json (test patterns)
- context-package.json (smart context)
- Artifact Priority in Development
## 4. Implementation Strategy
- Execution Strategy (TDD Cycles: Red-Green-Refactor)
- Architectural Approach
- Key Dependencies (Task dependency graph)
- Testing Strategy (Coverage targets, Quality gates)
## 5. TDD Implementation Tasks
- Feature-by-Feature TDD Tasks
- Each task: IMPL-N with internal Red → Green → Refactor
- Dependencies and complexity metrics
- Complex Feature Examples (when subtasks needed)
- TDD Task Breakdown Summary
## 6. Implementation Plan (Detailed Phased Breakdown)
- Execution Strategy (feature-by-feature sequential)
- Phase breakdown (Phase 1, Phase 2, etc.)
- Resource Requirements (Team, Dependencies, Infrastructure)
## 7. Risk Assessment & Mitigation
- Risk table (Risk, Impact, Probability, Mitigation, Owner)
- Critical Risks (TDD-specific)
- Monitoring Strategy
## 8. Success Criteria
- Functional Completeness
- Technical Quality (Test coverage ≥80%)
- Operational Readiness
- TDD Compliance
```
### Phase 4: TODO_LIST.md Generation
Generate task list with internal TDD phase indicators:
**For Simple Features (1 task per feature)**:
```markdown
## TDD Implementation Tasks
### Feature 1: {Feature Name}
- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
- Internal phases: Red → Green → Refactor
- Dependencies: None
### Feature 2: {Feature Name}
- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
- Internal phases: Red → Green → Refactor
- Dependencies: IMPL-1
```
**For Complex Features (with subtasks)**:
```markdown
### Feature 3: {Complex Feature Name}
▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
- [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
- Internal phases: Red → Green → Refactor
- [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
- Internal phases: Red → Green → Refactor
- Dependencies: IMPL-3.1
```
**Status Legend**:
```markdown
## Status Legend
- ▸ = Container task (has subtasks)
- [ ] = Pending task
- [x] = Completed task
- Red = Write failing tests
- Green = Implement to pass tests (with test-fix cycle)
- Refactor = Improve code quality
```
### Phase 5: Session State Update
Update workflow-session.json with TDD metadata:
```json
{
"workflow_type": "tdd",
"feature_count": 5,
"task_count": 5,
"task_breakdown": {
"simple_features": 4,
"complex_features": 1,
"total_subtasks": 2
},
"tdd_workflow": true,
"task_limit_compliance": true
}
```
**Task Count Calculation**:
- **Simple features**: 1 task each (IMPL-N with internal TDD cycle)
- **Complex features**: 1 container + M subtasks (IMPL-N + IMPL-N.M)
- **Total**: Simple feature count + Complex feature subtask count
- **Example**: 4 simple + 1 complex (with 2 subtasks) = 6 total tasks (not 15)
## Output Files Structure
```
.workflow/{session-id}/
├── IMPL_PLAN.md # Unified plan with TDD Implementation Tasks section
├── TODO_LIST.md # Progress tracking with internal TDD phase indicators
├── .task/
│ ├── IMPL-1.json # Complete TDD task (Red-Green-Refactor internally)
│ ├── IMPL-2.json # Complete TDD task
│ ├── IMPL-3.json # Complex feature container (if needed)
│ ├── IMPL-3.1.json # Complex feature subtask (if needed)
│ ├── IMPL-3.2.json # Complex feature subtask (if needed)
│ └── ...
└── .process/
├── CONFLICT_RESOLUTION.md # Conflict resolution strategies (if conflict_risk ≥ medium)
├── test-context-package.json # Test coverage analysis
├── context-package.json # Input from context-gather
├── context_package_path # Path to smart context package
└── green-fix-iteration-*.md # Fix logs from Green phase test-fix cycles
```
**File Count**:
- **Old approach**: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5)
- **New approach**: 5 features = 5 task JSON files (IMPL-N × 5)
- **Complex feature**: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M)
## Validation Rules
### Task Completeness
- Every IMPL-N must contain complete TDD workflow in `flow_control.implementation_approach`
- Each task must have 3 steps with `tdd_phase`: "red", "green", "refactor"
- Every task must have `meta.tdd_workflow: true`
### Dependency Enforcement
- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
- Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies
- No circular dependencies allowed
### Task Limits
- Maximum 10 total tasks (simple + subtasks)
- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
- Re-scope requirements if >10 tasks needed
### TDD Workflow Validation
- `meta.tdd_workflow` must be true
- `flow_control.implementation_approach` must have exactly 3 steps
- Each step must have `tdd_phase` field ("red", "green", or "refactor")
- Green phase step must include test-fix cycle logic
- `meta.max_iterations` must be present (default: 3)
## Error Handling
### Input Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Session not found | Invalid session ID | Verify session exists |
| Context missing | Incomplete planning | Run context-gather first |
### TDD Generation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features |
| Missing test framework | No test config | Configure testing first |
| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
## Integration & Usage
### Command Chain
- **Called By**: `/workflow:tdd-plan` (Phase 4)
- **Calls**: Gemini CLI for TDD breakdown
- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
### Basic Usage
```bash
# Manual mode (default)
/workflow:tools:task-generate-tdd --session WFS-auth
# Agent mode (autonomous task generation)
/workflow:tools:task-generate-tdd --session WFS-auth --agent
```
### Expected Output
```
TDD task generation complete for session: WFS-auth
Features analyzed: 5
Total tasks: 5 (1 task per feature with internal TDD cycles)
Task breakdown:
- Simple features: 4 tasks (IMPL-1 to IMPL-4)
- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
- Total task count: 6 (within 10-task limit)
Structure:
- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
- IMPL-4: Role Management (Internal: Red → Green → Refactor)
- IMPL-5: Payment System (Container)
- IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
- IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
Plans generated:
- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
TDD Configuration:
- Each task contains complete Red-Green-Refactor cycle
- Green phase includes test-fix cycle (max 3 iterations)
- Auto-revert on max iterations reached
Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
```
## Test Coverage Analysis Integration
The TDD workflow includes test coverage analysis (via `/workflow:tools:test-context-gather`) to:
- Detect existing test patterns and conventions
- Identify current test coverage gaps
- Discover test framework and configuration
- Enable integration with existing tests
This makes TDD workflow context-aware instead of assuming greenfield scenarios.
## Iterative Green Phase with Test-Fix Cycle
IMPL (Green phase) tasks include automatic test-fix cycle:
**Process Flow**:
1. **Initial Implementation**: Write minimal code to pass tests
2. **Test Execution**: Run test suite
3. **Success Path**: Tests pass → Complete task
4. **Failure Path**: Tests fail → Enter iterative fix cycle:
- **Gemini Diagnosis**: Analyze failures with bug-fix template
- **Fix Application**: Manual (default) or Codex (if meta.use_codex=true)
- **Retest**: Verify fix resolves failures
- **Repeat**: Up to max_iterations (default: 3)
5. **Safety Net**: Auto-revert all changes if max iterations reached
**Key Benefits**:
- Faster feedback loop within Green phase
- Autonomous recovery from initial implementation errors
- Systematic debugging with Gemini's bug-fix template
- Safe rollback prevents broken TDD state
## Configuration Options
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
- **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
## Related Commands
- `/workflow:tdd-plan` - Orchestrates TDD workflow planning (6 phases)
- `/workflow:tools:test-context-gather` - Analyzes test coverage
- `/workflow:execute` - Executes TDD tasks in order
- `/workflow:tdd-verify` - Verifies TDD compliance
- `/workflow:test-gen` - Post-implementation test generation

815
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md Normal file
View File

@@ -0,0 +1,815 @@
---
name: task-generate
description: Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration
argument-hint: "--session WFS-session-id [--cli-execute]"
examples:
- /workflow:tools:task-generate --session WFS-auth
- /workflow:tools:task-generate --session WFS-auth --cli-execute
---
# Task Generation Command
## 1. Overview
This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
## 2. Execution Modes
This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
### Agent Mode (Default)
In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
- **Execution**: Agent reads these fields and performs the implementation autonomously
- **Context Loading**: Agent loads context via `pre_analysis` steps
- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
- **Use Case**: Standard implementation tasks where agent capability is sufficient
### CLI Execute Mode (`--cli-execute`)
When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
- **Step Structure**: Includes all default fields PLUS a `command` field
- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
## 3. Core Principles
This command is built on a set of core principles to ensure efficient and reliable task generation.
- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
- **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
## 4. Execution Flow
The command follows a streamlined, three-step process to convert analysis into executable tasks.
### Step 1: Input & Discovery
The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
1. **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`.
2. **Context Package Loading** (primary source): Reads `.workflow/{session_id}/.process/context-package.json` for smart context and artifact catalog.
3. **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
4. **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
### Step 2: Task Decomposition & Grouping
Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
1. **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies.
2. **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`.
3. **Task Grouping**:
* Tasks with the **same signature** are candidates for merging, as they operate on the same context.
* Tasks with **different signatures** and no dependencies are grouped for parallel execution.
* Tasks with `depends_on` relationships are marked for sequential execution.
4. **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field.
### Step 3: Output Generation
Finally, the command generates all the necessary output files.
1. **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
2. **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
3. **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
4. **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
## 5. Task Decomposition Strategy
The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
### Core Principles
- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
### Context Analysis for Task Grouping
The decision to merge or decompose is based on analyzing context indicators:
1. **Shared Context Indicators (→ Merge)**:
* Identical `focus_paths` (working on the same modules/files).
* Same tech stack and dependencies.
* Identical `context.artifacts` references.
* A sequential logic flow within the same feature.
* Shared test fixtures or setup.
2. **Independent Context Indicators (→ Decompose)**:
* Different `focus_paths` (separate modules).
* Different tech stacks (e.g., frontend vs. backend).
* Different `context.artifacts` (using different brainstorming outputs).
* No shared dependencies.
* Can be tested independently.
**Decomposition is only performed when**:
- Tasks have different contexts and no shared dependencies (enabling parallel execution).
- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
### Context Signature Algorithm
To automate grouping, a `context_signature` is computed for each task.
```javascript
// Compute context signature for task grouping
function computeContextSignature(task) {
const focusPathsStr = task.context.focus_paths.sort().join('|');
const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
}
```
### Execution Group Assignment
Tasks are assigned to execution groups based on their signatures and dependencies.
```javascript
// Group tasks by context signature
function groupTasksByContext(tasks) {
const groups = {};
tasks.forEach(task => {
const signature = computeContextSignature(task);
if (!groups[signature]) {
groups[signature] = [];
}
groups[signature].push(task);
});
return groups;
}
// Assign execution groups for parallel tasks
function assignExecutionGroups(tasks) {
const contextGroups = groupTasksByContext(tasks);
Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
if (groupTasks.length === 1) {
const task = groupTasks[0];
// Single task with unique context
if (!task.context.depends_on || task.context.depends_on.length === 0) {
task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
} else {
task.meta.execution_group = null; // Sequential task
}
} else {
// Multiple tasks with same context → Should be merged
console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
// Merge tasks into single task
return mergeTasks(groupTasks);
}
});
}
```
**Task Limits**:
- **Maximum 10 tasks** (hard limit).
- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
## 6. Generated Outputs
The command produces three key documents and a directory of task files.
### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
```json
{
"id": "IMPL-N[.M]",
"title": "Descriptive task name",
"status": "pending|active|completed|blocked|container",
"context_package_path": ".workflow/WFS-[session]/.process/context-package.json",
"meta": {
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
"agent": "@code-developer|@test-fix-agent|@universal-executor",
"execution_group": "group-id|null",
"context_signature": "hash-of-focus_paths-and-artifacts"
},
"context": {
"requirements": ["Clear requirement from analysis"],
"focus_paths": ["D:\\project\\src\\module\\path", "./tests/module/path"],
"acceptance": ["Measurable acceptance criterion"],
"parent": "IMPL-N",
"depends_on": ["IMPL-N.M"],
"inherited": {"shared_patterns": [], "common_dependencies": []},
"shared_context": {"tech_stack": [], "conventions": []},
"artifacts": [
{
"path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
"priority": "highest",
"usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
},
{
"path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
"priority": "high",
"usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place"
}
]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_context_package",
"action": "Load context package for artifact paths",
"note": "Context package path is now at top-level field: context_package_path",
"commands": [
"Read({{context_package_path}})"
],
"output_to": "context_package",
"on_error": "fail"
},
{
"step": "load_role_analysis_artifacts",
"action": "Load role analyses from context-package.json (supports multiple files per role)",
"note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analysis_artifacts",
"on_error": "skip_optional"
},
{
"step": "load_planning_context",
"action": "Load plan-generated context intelligence with resolved conflicts",
"note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.",
"commands": [
"Read({{context_package_path}})",
"Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)"
],
"output_to": "planning_context",
"on_error": "fail",
"usage_guidance": {
"context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)",
"guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)"
}
},
{
"step": "codebase_exploration",
"action": "Explore codebase using native tools",
"command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")",
"output_to": "codebase_structure"
},
{
"step": "analyze_task_patterns",
"action": "Analyze existing code patterns and identify modification targets",
"commands": [
"bash(cd \"[focus_paths]\")",
"bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
],
"output_to": "task_context_with_targets",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement task following role analyses and context",
"description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.",
"modification_points": [
"Apply requirements and design specs from role analysis documents",
"Use enhancements and clarifications from synthesis phase",
"Use finalized decisions from guidance-specification.md (includes resolved conflicts)",
"Use context-package.json for focus paths and dependency resolution",
"Consult specific role artifacts for implementation details when needed",
"Integrate with existing patterns"
],
"logic_flow": [
"Load role analyses (requirements, design, enhancements from synthesis)",
"Load guidance-specification.md (finalized decisions with resolved conflicts if any)",
"Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)",
"Extract requirements and design decisions from role documents",
"Review synthesis enhancements and clarifications",
"Use finalized decisions (conflicts already resolved if applicable)",
"Identify modification targets using context package",
"Implement following role requirements and design specs",
"Consult role artifacts for detailed specifications when needed",
"Validate against acceptance criteria"
],
"depends_on": [],
"output": "implementation"
}
],
"target_files": ["file:function:lines"]
}
}
```
### 6.2. IMPL_PLAN.md Structure
This document provides a high-level overview of the entire implementation plan.
```markdown
---
identifier: WFS-{session-id}
source: "User requirements" | "File: path" | "Issue: ISS-001"
role_analyses: .workflow/{session-id}/.brainstorming/[role]/analysis*.md
artifacts: .workflow/{session-id}/.brainstorming/
context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context
guidance_specification: .workflow/{session-id}/.brainstorming/guidance-specification.md # Finalized decisions with resolved conflicts
workflow_type: "standard | tdd | design" # Indicates execution model
verification_history: # CCW quality gates
synthesis_clarify: "passed | skipped | pending" # Brainstorm phase clarification
action_plan_verify: "pending"
conflict_resolution: "resolved | none | low" # Status from context-package.json
phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning" # CCW workflow phases
---
# Implementation Plan: {Project Title}
## 1. Summary
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
**Core Objectives**:
- [Key objective 1]
- [Key objective 2]
**Technical Approach**:
- [High-level approach]
## 2. Context Analysis
### CCW Workflow Context
**Phase Progression**:
- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
**Quality Gates**:
- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
**Context Package Summary**:
- **Focus Paths**: {list key directories from context-package.json}
- **Key Files**: {list primary files for modification}
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
### Project Profile
- **Type**: Greenfield/Enhancement/Refactor
- **Scale**: User count, data volume, complexity
- **Tech Stack**: Primary technologies
- **Timeline**: Duration and milestones
### Module Structure
'''
[Directory tree showing key modules]
'''
### Dependencies
**Primary**: [Core libraries and frameworks]
**APIs**: [External services]
**Development**: [Testing, linting, CI/CD tools]
### Patterns & Conventions
- **Architecture**: [Key patterns like DI, Event-Driven]
- **Component Design**: [Design patterns]
- **State Management**: [State strategy]
- **Code Style**: [Naming, TypeScript coverage]
## 3. Brainstorming Artifacts Reference
### Artifact Usage Strategy
**Primary Reference (Role Analyses)**:
- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
- **When**: Every task references relevant role analyses for requirements and design decisions
- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
**Context Intelligence (context-package.json)**:
- **What**: Smart context gathered by CCW's context-gather phase
- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
**Conflict Resolution Status**:
- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
### Role Analysis Documents (Highest Priority)
Role analyses provide specialized perspectives on the implementation:
- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
### Supporting Artifacts (Reference)
- **topic-framework.md**: Role-specific discussion points and analysis framework
**Artifact Priority in Development**:
1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
## 4. Implementation Strategy
### Execution Strategy
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
**Rationale**: [Why this execution model fits the project]
**Parallelization Opportunities**:
- [List independent workstreams]
**Serialization Requirements**:
- [List critical dependencies]
### Architectural Approach
**Key Architecture Decisions**:
- [ADR references from role analyses]
- [Justification for architecture patterns]
**Integration Strategy**:
- [How modules communicate]
- [State management approach]
### Key Dependencies
**Task Dependency Graph**:
'''
[High-level dependency visualization]
'''
**Critical Path**: [Identify bottleneck tasks]
### Testing Strategy
**Testing Approach**:
- Unit testing: [Tools, scope]
- Integration testing: [Key integration points]
- E2E testing: [Critical user flows]
**Coverage Targets**:
- Lines: ≥70%
- Functions: ≥70%
- Branches: ≥65%
**Quality Gates**:
- [CI/CD gates]
- [Performance budgets]
## 5. Task Breakdown Summary
### Task Count
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
### Task Structure
- **IMPL-1**: [Main task title]
- **IMPL-2**: [Main task title]
...
### Complexity Assessment
- **High**: [List with rationale]
- **Medium**: [List]
- **Low**: [List]
### Dependencies
[Reference Section 4.3 for dependency graph]
**Parallelization Opportunities**:
- [Specific task groups that can run in parallel]
## 6. Implementation Plan (Detailed Phased Breakdown)
### Execution Strategy
**Phase 1 (Weeks 1-2): [Phase Name]**
- **Tasks**: IMPL-1, IMPL-2
- **Deliverables**:
- [Specific deliverable 1]
- [Specific deliverable 2]
- **Success Criteria**:
- [Measurable criterion]
**Phase 2 (Weeks 3-N): [Phase Name]**
...
### Resource Requirements
**Development Team**:
- [Team composition and skills]
**External Dependencies**:
- [Third-party services, APIs]
**Infrastructure**:
- [Development, staging, production environments]
## 7. Risk Assessment & Mitigation
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|------|--------|-------------|---------------------|-------|
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
**Critical Risks** (High impact + High probability):
- [Risk 1]: [Detailed mitigation plan]
**Monitoring Strategy**:
- [How risks will be monitored]
## 8. Success Criteria
**Functional Completeness**:
- [ ] All requirements from role analysis documents implemented
- [ ] All acceptance criteria from task.json files met
**Technical Quality**:
- [ ] Test coverage ≥70%
- [ ] Bundle size within budget
- [ ] Performance targets met
**Operational Readiness**:
- [ ] CI/CD pipeline operational
- [ ] Monitoring and logging configured
- [ ] Documentation complete
**Business Metrics**:
- [ ] [Key business metrics from role analyses]
```
### 6.3. TODO_LIST.md Structure
A simple Markdown file for tracking the status of each task.
```markdown
# Tasks: [Session Topic]
## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
## Status Legend
- `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task
- `- [x]` = Completed leaf task
- Maximum 2 levels: Main tasks and subtasks only
```
### 6.4. Output Files Diagram
The command organizes outputs into a standard directory structure.
```
.workflow/{session-id}/
├── IMPL_PLAN.md # Implementation plan
├── TODO_LIST.md # Progress tracking
├── .task/
│ ├── IMPL-1.json # Container task
│ ├── IMPL-1.1.json # Leaf task with flow_control
│ └── IMPL-1.2.json # Leaf task with flow_control
├── .brainstorming # Input artifacts from brainstorm + synthesis
│ ├── guidance-specification.md # Finalized decisions (with resolved conflicts if any)
│ └── {role}/analysis*.md # Role analyses (enhanced by synthesis, with resolved conflicts if any)
└── .process/
└── context-package.json # Input from context-gather (smart context + conflict_risk status)
```
## 7. Artifact Integration
The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
#### Artifact Priority
1. **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
2. **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
3. **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
#### Artifact-Task Mapping
Artifacts are mapped to tasks based on their relevance to the task's domain.
- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
## 8. CLI Execute Mode Details
When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
**Key Points**:
- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
### Example 1: Agent Mode - Simple Task (Default, No Command)
```json
{
"id": "IMPL-001",
"title": "Implement user authentication module",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context": {
"depends_on": [],
"focus_paths": ["src/auth"],
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
"acceptance": [
"JWT token generation working",
"Login and registration endpoints implemented",
"Tests passing with >70% coverage"
]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_role_analyses",
"action": "Load role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analyses",
"on_error": "fail"
},
{
"step": "load_context",
"action": "Load context package for project structure",
"commands": ["Read({{context_package_path}})"],
"output_to": "context_pkg",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement JWT-based authentication",
"description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns",
"modification_points": [
"Create auth service with JWT generation",
"Implement login endpoint with credential validation",
"Implement registration endpoint with user creation",
"Add JWT middleware for route protection"
],
"logic_flow": [
"User registers → validate input → hash password → create user",
"User logs in → validate credentials → generate JWT → return token",
"Protected routes → validate JWT → extract user → allow access"
],
"depends_on": [],
"output": "auth_implementation"
}
],
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"]
}
}
```
### Example 2: CLI Execute Mode - Single Codex Step
```json
{
"id": "IMPL-002",
"title": "Implement user authentication module",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context": {
"depends_on": [],
"focus_paths": ["src/auth"],
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
"acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_role_analyses",
"action": "Load role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analyses",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement authentication with Codex",
"description": "Create JWT-based authentication module",
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
"logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
"depends_on": [],
"output": "auth_implementation"
}
],
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts"]
}
}
```
### Example 3: CLI Execute Mode - Multi-Step with Resume
```json
{
"id": "IMPL-003",
"title": "Implement role-based access control",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context": {
"depends_on": ["IMPL-002"],
"focus_paths": ["src/auth", "src/middleware"],
"requirements": ["User roles and permissions", "Route protection middleware"],
"acceptance": ["RBAC models created", "Middleware working", "Management API complete"]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_context",
"action": "Load context and role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "full_context",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Create RBAC models",
"description": "Define role and permission data models",
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Define role model", "Define permission model", "Create migrations"],
"logic_flow": ["Design schema", "Implement models", "Generate migrations"],
"depends_on": [],
"output": "rbac_models"
},
{
"step": 2,
"title": "Implement RBAC middleware",
"description": "Create route protection middleware using models from step 1",
"command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
"logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
"depends_on": [1],
"output": "rbac_middleware"
},
{
"step": 3,
"title": "Add role management API",
"description": "Create CRUD endpoints for roles and permissions",
"command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
"logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
"depends_on": [2],
"output": "role_management_api"
}
],
"target_files": [
"src/models/Role.ts",
"src/models/Permission.ts",
"src/middleware/rbac.ts",
"src/routes/roles.ts"
]
}
}
```
**Pattern Summary**:
- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
## 9. Error Handling
### Input Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Session not found | Invalid session ID | Verify session exists |
| Context missing | Incomplete planning | Run context-gather first |
| Invalid format | Corrupted results | Regenerate analysis |
### Task Generation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Count exceeds limit | >10 tasks | Re-scope requirements |
| Invalid structure | Missing fields | Fix analysis results |
| Dependency cycle | Circular refs | Adjust dependencies |
### Artifact Integration Errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Artifact not found | Missing output | Continue without artifacts |
| Invalid format | Corrupted file | Skip artifact loading |
| Path invalid | Moved/deleted | Update references |
## 10. Integration & Usage
### Command Chain
- **Called By**: `/workflow:plan` (Phase 4)
- **Calls**: None (terminal command)
- **Followed By**: `/workflow:execute`, `/workflow:status`
### Basic Usage
```bash
/workflow:tools:task-generate --session WFS-auth
```
## 11. Related Commands
- `/workflow:plan` - Orchestrates entire planning
- `/workflow:plan --cli-execute` - Planning with CLI execution mode
- `/workflow:tools:context-gather` - Provides context package
- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional)
- `/workflow:execute` - Executes generated tasks

281
.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md Normal file
View File

@@ -0,0 +1,281 @@
---
name: tdd-coverage-analysis
description: Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification
argument-hint: "--session WFS-session-id"
allowed-tools: Read(*), Write(*), Bash(*)
---
# TDD Coverage Analysis Command
## Overview
Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD workflow validation.
## Core Responsibilities
- Extract test files from TEST tasks
- Run test suite with coverage
- Parse coverage metrics
- Verify TDD cycle execution (Red -> Green -> Refactor)
- Generate coverage and cycle reports
## Execution Lifecycle
### Phase 1: Extract Test Tasks
```bash
find .workflow/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
```
**Output**: List of test directories/files from all TEST tasks
### Phase 2: Run Test Suite
```bash
# Node.js/JavaScript
npm test -- --coverage --json > .workflow/{session_id}/.process/test-results.json
# Python
pytest --cov --json-report > .workflow/{session_id}/.process/test-results.json
# Other frameworks (detect from project)
[test_command] --coverage --json-output .workflow/{session_id}/.process/test-results.json
```
**Output**: test-results.json with coverage data
### Phase 3: Parse Coverage Data
```bash
jq '.coverage' .workflow/{session_id}/.process/test-results.json > .workflow/{session_id}/.process/coverage-report.json
```
**Extract**:
- Line coverage percentage
- Branch coverage percentage
- Function coverage percentage
- Uncovered lines/branches
### Phase 4: Verify TDD Cycle
For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M):
**1. Red Phase Verification**
```bash
# Check TEST task summary
cat .workflow/{session_id}/.summaries/TEST-N.M-summary.md
```
Verify:
- Tests were created
- Tests failed initially
- Failure messages were clear
**2. Green Phase Verification**
```bash
# Check IMPL task summary
cat .workflow/{session_id}/.summaries/IMPL-N.M-summary.md
```
Verify:
- Implementation was completed
- Tests now pass
- Implementation was minimal
**3. Refactor Phase Verification**
```bash
# Check REFACTOR task summary
cat .workflow/{session_id}/.summaries/REFACTOR-N.M-summary.md
```
Verify:
- Refactoring was completed
- Tests still pass
- Code quality improved
### Phase 5: Generate Analysis Report
Create `.workflow/{session_id}/.process/tdd-cycle-report.md`:
```markdown
# TDD Cycle Analysis - {Session ID}
## Coverage Metrics
- **Line Coverage**: {percentage}%
- **Branch Coverage**: {percentage}%
- **Function Coverage**: {percentage}%
## Coverage Details
### Covered
- {covered_lines} lines
- {covered_branches} branches
- {covered_functions} functions
### Uncovered
- Lines: {uncovered_line_numbers}
- Branches: {uncovered_branch_locations}
## TDD Cycle Verification
### Feature 1: {Feature Name}
**Chain**: TEST-1.1 -> IMPL-1.1 -> REFACTOR-1.1
- [PASS] **Red Phase**: Tests created and failed initially
- [PASS] **Green Phase**: Implementation made tests pass
- [PASS] **Refactor Phase**: Refactoring maintained green tests
### Feature 2: {Feature Name}
**Chain**: TEST-2.1 -> IMPL-2.1 -> REFACTOR-2.1
- [PASS] **Red Phase**: Tests created and failed initially
- [WARN] **Green Phase**: Tests pass but implementation seems over-engineered
- [PASS] **Refactor Phase**: Refactoring maintained green tests
[Repeat for all features]
## TDD Compliance Summary
- **Total Chains**: {N}
- **Complete Cycles**: {N}
- **Incomplete Cycles**: {0}
- **Compliance Score**: {score}/100
## Gaps Identified
- Feature 3: Missing initial test failure verification
- Feature 5: No refactoring step completed
## Recommendations
- Complete missing refactoring steps
- Add edge case tests for Feature 2
- Verify test failure messages are descriptive
```
## Output Files
```
.workflow/{session-id}/
└── .process/
├── test-results.json # Raw test execution results
├── coverage-report.json # Parsed coverage data
└── tdd-cycle-report.md # TDD cycle analysis
```
## Test Framework Detection
Auto-detect test framework from project:
```bash
# Check for test frameworks
if [ -f "package.json" ] && grep -q "jest\|mocha\|vitest" package.json; then
TEST_CMD="npm test -- --coverage --json"
elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
TEST_CMD="pytest --cov --json-report"
elif [ -f "Cargo.toml" ]; then
TEST_CMD="cargo test -- --test-threads=1 --nocapture"
elif [ -f "go.mod" ]; then
TEST_CMD="go test -coverprofile=coverage.out -json ./..."
else
TEST_CMD="echo 'No supported test framework found'"
fi
```
## TDD Cycle Verification Algorithm
```
For each feature N:
1. Load TEST-N.M-summary.md
IF summary missing:
Mark: "Red phase incomplete"
SKIP to next feature
CHECK: Contains "test" AND "fail"
IF NOT found:
Mark: "Red phase verification failed"
ELSE:
Mark: "Red phase [PASS]"
2. Load IMPL-N.M-summary.md
IF summary missing:
Mark: "Green phase incomplete"
SKIP to next feature
CHECK: Contains "pass" OR "green"
IF NOT found:
Mark: "Green phase verification failed"
ELSE:
Mark: "Green phase [PASS]"
3. Load REFACTOR-N.M-summary.md
IF summary missing:
Mark: "Refactor phase incomplete"
CONTINUE (refactor is optional)
CHECK: Contains "refactor" AND "pass"
IF NOT found:
Mark: "Refactor phase verification failed"
ELSE:
Mark: "Refactor phase [PASS]"
4. Calculate chain score:
- Red + Green + Refactor all [PASS] = 100%
- Red + Green [PASS], Refactor missing = 80%
- Red [PASS], Green missing = 40%
- All missing = 0%
```
## Coverage Metrics Calculation
```bash
# Parse coverage from test-results.json
line_coverage=$(jq '.coverage.lineCoverage' test-results.json)
branch_coverage=$(jq '.coverage.branchCoverage' test-results.json)
function_coverage=$(jq '.coverage.functionCoverage' test-results.json)
# Calculate overall score
overall_score=$(echo "($line_coverage + $branch_coverage + $function_coverage) / 3" | bc)
```
## Error Handling
### Test Execution Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Test framework not found | No test config | Configure test framework first |
| Tests fail to run | Syntax errors | Fix code before analysis |
| Coverage not available | Missing coverage tool | Install coverage plugin |
### Cycle Verification Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Summary missing | Task not executed | Execute tasks before analysis |
| Invalid summary format | Corrupted file | Re-run task to regenerate |
| No test evidence | Tests not committed | Ensure tests are committed |
## Integration & Usage
### Command Chain
- **Called By**: `/workflow:tdd-verify` (Phase 3)
- **Calls**: Test framework commands (npm test, pytest, etc.)
- **Followed By**: Compliance report generation
### Basic Usage
```bash
/workflow:tools:tdd-coverage-analysis --session WFS-auth
```
### Expected Output
```
TDD Coverage Analysis complete for session: WFS-auth
## Coverage Results
Line Coverage: 87%
Branch Coverage: 82%
Function Coverage: 91%
## TDD Cycle Verification
[PASS] Feature 1: Complete (Red -> Green -> Refactor)
[PASS] Feature 2: Complete (Red -> Green -> Refactor)
[WARN] Feature 3: Incomplete (Red -> Green, missing Refactor)
Overall Compliance: 93/100
Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
```
## Related Commands
- `/workflow:tdd-verify` - Uses this tool for verification
- `/workflow:tools:task-generate-tdd` - Generates tasks this tool analyzes
- `/workflow:execute` - Executes tasks before analysis

467
.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md Normal file
View File

@@ -0,0 +1,467 @@
---
name: test-concept-enhanced
description: Analyze test requirements and generate test generation strategy using Gemini with test-context package
argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
examples:
- /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
---
# Test Concept Enhanced Command
## Overview
Specialized analysis tool for test generation workflows that uses Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies.
## Core Philosophy
- **Coverage-Driven**: Focus on identified test gaps from context analysis
- **Pattern-Based**: Learn from existing tests and project conventions
- **Gemini-Powered**: Use Gemini for test requirement analysis and strategy design
- **Single-Round Analysis**: Comprehensive test analysis in one execution
- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution
## Core Responsibilities
- Parse test-context-package.json from test-context-gather
- Analyze implementation summaries and coverage gaps
- Study existing test patterns and conventions
- Generate test generation strategy using Gemini
- Produce TEST_ANALYSIS_RESULTS.md for task generation
## Execution Lifecycle
### Phase 1: Validation & Preparation
1. **Session Validation**
- Load `.workflow/{test_session_id}/workflow-session.json`
- Verify test session type is "test-gen"
- Extract source session reference
2. **Context Package Validation**
- Read `test-context-package.json`
- Validate required sections: metadata, source_context, test_coverage, test_framework
- Extract coverage gaps and framework details
3. **Strategy Determination**
- **Simple Test Generation** (1-3 files): Single Gemini analysis
- **Medium Test Generation** (4-6 files): Gemini comprehensive analysis
- **Complex Test Generation** (>6 files): Gemini analysis with modular approach
### Phase 2: Gemini Test Analysis
**Tool Configuration**:
```bash
cd .workflow/{test_session_id}/.process && gemini -p "
PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
MODE: analysis
CONTEXT: @{.workflow/{test_session_id}/.process/test-context-package.json}
**MANDATORY FIRST STEP**: Read and analyze test-context-package.json to understand:
- Test coverage gaps from test_coverage.missing_tests[]
- Implementation context from source_context.implementation_summaries[]
- Existing test patterns from test_framework.conventions
- Changed files requiring tests from source_context.implementation_summaries[].changed_files
**ANALYSIS REQUIREMENTS**:
1. **Implementation Understanding**
- Load all implementation summaries from source session
- Understand implemented features, APIs, and business logic
- Extract key functions, classes, and modules
- Identify integration points and dependencies
2. **Existing Test Pattern Analysis**
- Study existing test files for patterns and conventions
- Identify test structure (describe/it, test suites, fixtures)
- Analyze assertion patterns and mocking strategies
- Extract test setup/teardown patterns
3. **Coverage Gap Assessment**
- For each file in missing_tests[], analyze:
- File purpose and functionality
- Public APIs requiring test coverage
- Critical paths and edge cases
- Integration points requiring tests
- Prioritize tests: high (core logic), medium (utilities), low (helpers)
4. **Test Requirements Specification**
- For each missing test file, specify:
- **Test scope**: What needs to be tested
- **Test scenarios**: Happy path, error cases, edge cases, integration
- **Test data**: Required fixtures, mocks, test data
- **Dependencies**: External services, databases, APIs to mock
- **Coverage targets**: Functions/methods requiring tests
5. **Test Generation Strategy**
- Determine test generation approach for each file
- Identify reusable test patterns from existing tests
- Plan test data and fixture requirements
- Define mocking strategy for dependencies
- Specify expected test file structure
EXPECTED OUTPUT - Write to gemini-test-analysis.md:
# Test Generation Analysis
## 1. Implementation Context Summary
- **Source Session**: {source_session_id}
- **Implemented Features**: {feature_summary}
- **Changed Files**: {list_of_implementation_files}
- **Tech Stack**: {technologies_used}
## 2. Test Coverage Assessment
- **Existing Tests**: {count} files
- **Missing Tests**: {count} files
- **Coverage Percentage**: {percentage}%
- **Priority Breakdown**:
- High Priority: {count} files (core business logic)
- Medium Priority: {count} files (utilities, helpers)
- Low Priority: {count} files (configuration, constants)
## 3. Existing Test Pattern Analysis
- **Test Framework**: {framework_name_and_version}
- **File Naming Convention**: {pattern}
- **Test Structure**: {describe_it_or_other}
- **Assertion Style**: {expect_assert_should}
- **Mocking Strategy**: {mocking_framework_and_patterns}
- **Setup/Teardown**: {beforeEach_afterEach_patterns}
- **Test Data**: {fixtures_factories_builders}
## 4. Test Requirements by File
### File: {implementation_file_path}
**Test File**: {suggested_test_file_path}
**Priority**: {high|medium|low}
#### Scope
- {description_of_what_needs_testing}
#### Test Scenarios
1. **Happy Path Tests**
- {scenario_1}
- {scenario_2}
2. **Error Handling Tests**
- {error_scenario_1}
- {error_scenario_2}
3. **Edge Case Tests**
- {edge_case_1}
- {edge_case_2}
4. **Integration Tests** (if applicable)
- {integration_scenario_1}
- {integration_scenario_2}
#### Test Data & Fixtures
- {required_test_data}
- {required_mocks}
- {required_fixtures}
#### Dependencies to Mock
- {external_service_1}
- {external_service_2}
#### Coverage Targets
- Function: {function_name} - {test_requirements}
- Function: {function_name} - {test_requirements}
---
[Repeat for each missing test file]
---
## 5. Test Generation Strategy
### Overall Approach
- {strategy_description}
### Test Generation Order
1. {file_1} - {rationale}
2. {file_2} - {rationale}
3. {file_3} - {rationale}
### Reusable Patterns
- {pattern_1_from_existing_tests}
- {pattern_2_from_existing_tests}
### Test Data Strategy
- {approach_to_test_data_and_fixtures}
### Mocking Strategy
- {approach_to_mocking_dependencies}
### Quality Criteria
- Code coverage target: {percentage}%
- Test scenarios per function: {count}
- Integration test coverage: {approach}
## 6. Implementation Targets
**Purpose**: Identify new test files to create
**Format**: New test files only (no existing files to modify)
**Test Files to Create**:
1. **Target**: `tests/auth/TokenValidator.test.ts`
- **Type**: Create new test file
- **Purpose**: Test TokenValidator class
- **Scenarios**: 15 test cases covering validation logic, error handling, edge cases
- **Dependencies**: Mock JWT library, test fixtures for tokens
2. **Target**: `tests/middleware/errorHandler.test.ts`
- **Type**: Create new test file
- **Purpose**: Test error handling middleware
- **Scenarios**: 8 test cases for different error types and response formats
- **Dependencies**: Mock Express req/res/next, error fixtures
[List all test files to create]
## 7. Success Metrics
- **Test Coverage Goal**: {target_percentage}%
- **Test Quality**: All scenarios covered (happy, error, edge, integration)
- **Convention Compliance**: Follow existing test patterns
- **Maintainability**: Clear test descriptions, reusable fixtures
RULES:
- Focus on TEST REQUIREMENTS and GENERATION STRATEGY, NOT code generation
- Study existing test patterns thoroughly for consistency
- Prioritize critical business logic tests
- Specify clear test scenarios and coverage targets
- Identify all dependencies requiring mocks
- **MUST write output to .workflow/{test_session_id}/.process/gemini-test-analysis.md**
- Do NOT generate actual test code or implementation
- Output ONLY test analysis and generation strategy
" --approval-mode yolo
```
**Output Location**: `.workflow/{test_session_id}/.process/gemini-test-analysis.md`
### Phase 3: Results Synthesis
1. **Output Validation**
- Verify `gemini-test-analysis.md` exists and is complete
- Validate all required sections present
- Check test requirements are actionable
2. **Quality Assessment**
- Test scenarios cover happy path, errors, edge cases
- Dependencies and mocks clearly identified
- Test generation strategy is practical
- Coverage targets are reasonable
### Phase 4: TEST_ANALYSIS_RESULTS.md Generation
Synthesize Gemini analysis into standardized format:
```markdown
# Test Generation Analysis Results
## Executive Summary
- **Test Session**: {test_session_id}
- **Source Session**: {source_session_id}
- **Analysis Timestamp**: {timestamp}
- **Coverage Gap**: {missing_test_count} files require tests
- **Test Framework**: {framework}
- **Overall Strategy**: {high_level_approach}
---
## 1. Coverage Assessment
### Current Coverage
- **Existing Tests**: {count} files
- **Implementation Files**: {count} files
- **Coverage Percentage**: {percentage}%
### Missing Tests (Priority Order)
1. **High Priority** ({count} files)
- {file_1} - {reason}
- {file_2} - {reason}
2. **Medium Priority** ({count} files)
- {file_1} - {reason}
3. **Low Priority** ({count} files)
- {file_1} - {reason}
---
## 2. Test Framework & Conventions
### Framework Configuration
- **Framework**: {framework_name}
- **Version**: {version}
- **Test Pattern**: {file_pattern}
- **Test Directory**: {directory_structure}
### Conventions
- **File Naming**: {convention}
- **Test Structure**: {describe_it_blocks}
- **Assertions**: {assertion_library}
- **Mocking**: {mocking_framework}
- **Setup/Teardown**: {beforeEach_afterEach}
### Example Pattern (from existing tests)
```
{example_test_structure_from_analysis}
```
---
## 3. Test Requirements by File
[For each missing test, include:]
### Test File: {test_file_path}
**Implementation**: {implementation_file}
**Priority**: {high|medium|low}
**Estimated Test Count**: {count}
#### Test Scenarios
1. **Happy Path**: {scenarios}
2. **Error Handling**: {scenarios}
3. **Edge Cases**: {scenarios}
4. **Integration**: {scenarios}
#### Dependencies & Mocks
- {dependency_1_to_mock}
- {dependency_2_to_mock}
#### Test Data Requirements
- {fixture_1}
- {fixture_2}
---
## 4. Test Generation Strategy
### Generation Approach
{overall_strategy_description}
### Generation Order
1. {test_file_1} - {rationale}
2. {test_file_2} - {rationale}
3. {test_file_3} - {rationale}
### Reusable Components
- **Test Fixtures**: {common_fixtures}
- **Mock Patterns**: {common_mocks}
- **Helper Functions**: {test_helpers}
### Quality Targets
- **Coverage Goal**: {percentage}%
- **Scenarios per Function**: {min_count}
- **Integration Coverage**: {approach}
---
## 5. Implementation Targets
**Purpose**: New test files to create (code-developer will generate these)
**Test Files to Create**:
1. **Target**: `tests/auth/TokenValidator.test.ts`
- **Implementation Source**: `src/auth/TokenValidator.ts`
- **Test Scenarios**: 15 (validation, error handling, edge cases)
- **Dependencies**: Mock JWT library, token fixtures
- **Priority**: High
2. **Target**: `tests/middleware/errorHandler.test.ts`
- **Implementation Source**: `src/middleware/errorHandler.ts`
- **Test Scenarios**: 8 (error types, response formats)
- **Dependencies**: Mock Express, error fixtures
- **Priority**: High
[List all test files with full specifications]
---
## 6. Success Criteria
### Coverage Metrics
- Achieve {target_percentage}% code coverage
- All public APIs have tests
- Critical paths fully covered
### Quality Standards
- All test scenarios covered (happy, error, edge, integration)
- Follow existing test conventions
- Clear test descriptions and assertions
- Maintainable test structure
### Validation Approach
- Run full test suite after generation
- Verify coverage with coverage tool
- Manual review of test quality
- Integration test validation
---
## 7. Reference Information
### Source Context
- **Implementation Summaries**: {paths}
- **Existing Tests**: {example_tests}
- **Documentation**: {relevant_docs}
### Analysis Tools
- **Gemini Analysis**: gemini-test-analysis.md
- **Coverage Tools**: {coverage_tool_if_detected}
```
**Output Location**: `.workflow/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
## Error Handling
### Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Missing context package | test-context-gather not run | Run test-context-gather first |
| No coverage gaps | All files have tests | Skip test generation, proceed to test execution |
| No test framework detected | Missing test dependencies | Request user to configure test framework |
| Invalid source session | Source session incomplete | Complete implementation first |
### Gemini Execution Errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Timeout | Large project analysis | Reduce scope, analyze by module |
| Output incomplete | Token limit exceeded | Retry with focused analysis |
| No output file | Write permission error | Check directory permissions |
### Fallback Strategy
- If Gemini fails, generate basic TEST_ANALYSIS_RESULTS.md from context package
- Use coverage gaps and framework info to create minimal requirements
- Provide guidance for manual test planning
## Performance Optimization
- **Focused Analysis**: Only analyze files with missing tests
- **Pattern Reuse**: Study existing tests for quick pattern extraction
- **Parallel Operations**: Load implementation summaries in parallel
- **Timeout Management**: 20-minute limit for Gemini analysis
## Integration
### Called By
- `/workflow:test-gen` (Phase 4: Analysis)
### Requires
- `/workflow:tools:test-context-gather` output (test-context-package.json)
### Followed By
- `/workflow:tools:test-task-generate` - Generates test task JSON with code-developer invocation
## Success Criteria
- ✅ Valid TEST_ANALYSIS_RESULTS.md generated
- ✅ All missing tests documented with requirements
- ✅ Test scenarios cover happy path, errors, edge cases
- ✅ Dependencies and mocks identified
- ✅ Test generation strategy is actionable
- ✅ Execution time < 20 minutes
- ✅ Output follows existing test conventions
## Related Commands
- `/workflow:tools:test-context-gather` - Provides input context
- `/workflow:tools:test-task-generate` - Consumes analysis results
- `/workflow:test-gen` - Main test generation workflow

210
.claude/skills/command-guide/reference/commands/workflow/tools/test-context-gather.md Normal file
View File

@@ -0,0 +1,210 @@
---
name: test-context-gather
description: Collect test coverage context using test-context-search-agent and package into standardized test-context JSON
argument-hint: "--session WFS-test-session-id"
examples:
- /workflow:tools:test-context-gather --session WFS-test-auth
- /workflow:tools:test-context-gather --session WFS-test-payment
allowed-tools: Task(*), Read(*), Glob(*)
---
# Test Context Gather Command (/workflow:tools:test-context-gather)
## Overview
Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
**Agent**: `test-context-search-agent` (`.claude/agents/test-context-search-agent.md`)
## Core Philosophy
- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution
- **Detection-First**: Check for existing test-context-package before executing
- **Coverage-First**: Analyze existing test coverage before planning new tests
- **Source Context Loading**: Import implementation summaries from source session
- **Standardized Output**: Generate `.workflow/{test_session_id}/.process/test-context-package.json`
## Execution Flow
### Step 1: Test-Context-Package Detection
**Execute First** - Check if valid package already exists:
```javascript
const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
if (file_exists(testContextPath)) {
const existing = Read(testContextPath);
// Validate package belongs to current test session
if (existing?.metadata?.test_session_id === test_session_id) {
console.log("✅ Valid test-context-package found for session:", test_session_id);
console.log("📊 Coverage Stats:", existing.test_coverage.coverage_stats);
console.log("🧪 Framework:", existing.test_framework.framework);
console.log("⚠️ Missing Tests:", existing.test_coverage.missing_tests.length);
return existing; // Skip execution, return existing
} else {
console.warn("⚠️ Invalid test_session_id in existing package, re-generating...");
}
}
```
### Step 2: Invoke Test-Context-Search Agent
**Only execute if Step 1 finds no valid package**
```javascript
Task(
subagent_type="test-context-search-agent",
description="Gather test coverage context",
prompt=`
You are executing as test-context-search-agent (.claude/agents/test-context-search-agent.md).
## Execution Mode
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
## Session Information
- **Test Session ID**: ${test_session_id}
- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json
## Mission
Execute complete test-context-search-agent workflow for test generation planning:
### Phase 1: Session Validation & Source Context Loading
1. **Detection**: Check for existing test-context-package (early exit if valid)
2. **Test Session Validation**: Load test session metadata, extract source_session reference
3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack
### Phase 2: Test Coverage Analysis
Execute coverage discovery:
- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files)
- **Track 2**: Coverage gap analysis (match implementation files to test files)
- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module)
### Phase 3: Framework Detection & Packaging
1. Framework identification from package.json/requirements.txt
2. Convention analysis from existing test patterns
3. Generate and validate test-context-package.json
## Output Requirements
Complete test-context-package.json with:
- **metadata**: test_session_id, source_session_id, task_type, complexity
- **source_context**: implementation_summaries, tech_stack, project_patterns
- **test_coverage**: existing_tests[], missing_tests[], coverage_stats
- **test_framework**: framework, version, test_pattern, conventions
- **assets**: implementation_summary[], existing_test[], source_code[] with priorities
- **focus_areas**: Test generation guidance based on coverage gaps
## Quality Validation
Before completion verify:
- [ ] Valid JSON format with all required fields
- [ ] Source session context loaded successfully
- [ ] Test coverage gaps identified
- [ ] Test framework detected (or marked as 'unknown')
- [ ] Coverage percentage calculated correctly
- [ ] Missing tests catalogued with priority
- [ ] Execution time < 30 seconds (< 60s for large codebases)
Execute autonomously following agent documentation.
Report completion with coverage statistics.
`
)
```
### Step 3: Output Verification
After agent completes, verify output:
```javascript
// Verify file was created
const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
if (!file_exists(outputPath)) {
throw new Error("❌ Agent failed to generate test-context-package.json");
}
// Load and display summary
const testContext = Read(outputPath);
console.log("✅ Test context package generated successfully");
console.log("📊 Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%");
console.log("⚠️ Tests to generate:", testContext.test_coverage.missing_tests.length);
```
## Parameter Reference
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) |
## Output Schema
Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema.
**Key Sections**:
- **metadata**: Test session info, source session reference, complexity
- **source_context**: Implementation summaries with changed files and tech stack
- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics
- **test_framework**: Framework name, version, patterns, conventions
- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code)
- **focus_areas**: Test generation guidance based on analysis
## Usage Examples
### Basic Usage
```bash
/workflow:tools:test-context-gather --session WFS-test-auth
```
### Expected Output
```
✅ Valid test-context-package found for session: WFS-test-auth
📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 }
🧪 Framework: jest
⚠️ Missing Tests: 1
```
## Success Criteria
- ✅ Valid test-context-package.json generated in `.workflow/{test_session_id}/.process/`
- ✅ Source session context loaded successfully
- ✅ Test coverage gaps identified (>90% accuracy)
- ✅ Test framework detected and documented
- ✅ Execution completes within 30 seconds (60s for large codebases)
- ✅ All required schema fields present and valid
- ✅ Coverage statistics calculated correctly
- ✅ Agent reports completion with statistics
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate |
| Source session not found | Invalid source_session reference | Verify test session metadata |
| No implementation summaries | Source session incomplete | Complete source session first |
| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access |
| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed |
## Integration
### Called By
- `/workflow:test-gen` (Phase 3: Context Gathering)
### Calls
- `test-context-search-agent` - Autonomous test coverage analysis
### Followed By
- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning
## Notes
- **Detection-first**: Always check for existing test-context-package before invoking agent
- **Agent autonomy**: Agent handles all coverage analysis logic per `.claude/agents/test-context-search-agent.md`
- **No redundancy**: This command is a thin orchestrator, all logic in agent
- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
- **Coverage focus**: Primary goal is identifying implementation files without tests
## Related Commands
- `/workflow:test-gen` - Main test generation workflow
- `/workflow:tools:test-concept-enhanced` - Test generation analysis
- `/workflow:tools:test-task-generate` - Test task JSON generation

695
.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md Normal file
View File

@@ -0,0 +1,695 @@
---
name: test-task-generate
description: Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex
argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
examples:
- /workflow:tools:test-task-generate --session WFS-test-auth
- /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
- /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
- /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
---
# Test Task Generation Command
## Overview
Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle specification, including Gemini diagnosis (using bug-fix template) and manual fix workflow (Codex automation only when explicitly requested).
## Execution Modes
### Test Generation (IMPL-001)
- **Agent Mode (Default)**: @code-developer generates tests within agent context
- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
### Test Fix (IMPL-002)
- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
## Core Philosophy
- **Analysis-Driven Test Generation**: Use TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
- **Agent-Based Test Creation**: Call @code-developer agent for comprehensive test generation
- **Coverage-First**: Generate all missing tests before execution
- **Test Execution**: Execute complete test suite after generation
- **Gemini Diagnosis**: Use Gemini for root cause analysis and fix suggestions (references bug-fix template)
- **Manual Fixes First**: Apply fixes manually by default, codex only when explicitly needed
- **Iterative Refinement**: Repeat test-analyze-fix-retest cycle until all tests pass
- **Surgical Fixes**: Minimal code changes, no refactoring during test fixes
- **Auto-Revert**: Rollback all changes if max iterations reached
## Core Responsibilities
- Parse TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
- Extract test requirements and generation strategy
- Parse `--use-codex` flag to determine fix mode (manual vs automated)
- Generate test generation subtask calling @code-developer
- Generate test execution and fix cycle task JSON with appropriate fix mode
- Configure Gemini diagnosis workflow (bug-fix template) and manual/Codex fix application
- Create test-oriented IMPL_PLAN.md and TODO_LIST.md with test generation phase
## Execution Lifecycle
### Phase 1: Input Validation & Discovery
1. **Parameter Parsing**
- Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
- Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
- Store flag values for task JSON generation
2. **Test Session Validation**
- Load `.workflow/{test-session-id}/workflow-session.json`
- Verify `workflow_type: "test_session"`
- Extract `source_session_id` from metadata
3. **Test Analysis Results Loading**
- **REQUIRED**: Load `.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md`
- Parse test requirements by file
- Extract test generation strategy
- Identify test files to create with specifications
4. **Test Context Package Loading**
- Load `.workflow/{test-session-id}/.process/test-context-package.json`
- Extract test framework configuration
- Extract coverage gaps and priorities
- Load source session implementation summaries
### Phase 2: Task JSON Generation
Generate **TWO task JSON files**:
1. **IMPL-001.json** - Test Generation (calls @code-developer)
2. **IMPL-002.json** - Test Execution and Fix Cycle (calls @test-fix-agent)
#### IMPL-001.json - Test Generation Task
```json
{
"id": "IMPL-001",
"title": "Generate comprehensive tests for [sourceSessionId]",
"status": "pending",
"meta": {
"type": "test-gen",
"agent": "@code-developer",
"source_session": "[sourceSessionId]",
"test_framework": "jest|pytest|cargo|detected"
},
"context": {
"requirements": [
"Generate comprehensive test files based on TEST_ANALYSIS_RESULTS.md",
"Follow existing test patterns and conventions from test framework",
"Create tests for all missing coverage identified in analysis",
"Include happy path, error handling, edge cases, and integration tests",
"Use test data and mocks as specified in analysis",
"Ensure tests follow project coding standards"
],
"focus_paths": [
"tests/**/*",
"src/**/*.test.*",
"{paths_from_analysis}"
],
"acceptance": [
"All test files from TEST_ANALYSIS_RESULTS.md section 5 are created",
"Tests follow existing test patterns and conventions",
"Test scenarios cover happy path, errors, edge cases, integration",
"All dependencies are properly mocked",
"Test files are syntactically valid and can be executed",
"Test coverage meets analysis requirements"
],
"depends_on": [],
"source_context": {
"session_id": "[sourceSessionId]",
"test_analysis": ".workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md",
"test_context": ".workflow/[testSessionId]/.process/test-context-package.json",
"implementation_summaries": [
".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
]
}
},
"flow_control": {
"pre_analysis": [
{
"step": "load_test_analysis",
"action": "Load test generation requirements and strategy",
"commands": [
"Read(.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md)",
"Read(.workflow/[testSessionId]/.process/test-context-package.json)"
],
"output_to": "test_generation_requirements",
"on_error": "fail"
},
{
"step": "load_implementation_context",
"action": "Load source implementation for test generation context",
"commands": [
"bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
],
"output_to": "implementation_context",
"on_error": "skip_optional"
},
{
"step": "load_existing_test_patterns",
"action": "Study existing tests for pattern reference",
"commands": [
"bash(find . -name \"*.test.*\" -type f)",
"bash(# Read first 2 existing test files as examples)",
"bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
"bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
],
"output_to": "existing_test_patterns",
"on_error": "skip_optional"
}
],
// Agent Mode (Default): Agent implements tests
"implementation_approach": [
{
"step": 1,
"title": "Generate comprehensive test suite",
"description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
"modification_points": [
"Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
"Study existing test patterns",
"Create test files with all required scenarios",
"Implement happy path, error handling, edge case, and integration tests",
"Add required mocks and fixtures"
],
"logic_flow": [
"Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
"Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
"Study existing test patterns from test_context.test_framework.conventions",
"For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
"Follow test framework conventions and project standards",
"Ensure all tests are executable and syntactically valid"
],
"depends_on": [],
"output": "test_suite"
}
],
// CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
"implementation_approach": [{
"step": 1,
"title": "Generate tests using Codex",
"description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
"modification_points": [
"Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
"Codex generates all test files listed in analysis section 5",
"Codex ensures tests follow framework conventions"
],
"logic_flow": [
"Start new Codex session",
"Pass TEST_ANALYSIS_RESULTS.md to Codex",
"Codex studies existing test patterns",
"Codex generates comprehensive test suite",
"Codex validates test syntax and executability"
],
"command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
"depends_on": [],
"output": "test_generation"
}],
"target_files": [
"{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
"{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
"{test_file_N from TEST_ANALYSIS_RESULTS.md section 5}"
]
}
}
```
#### IMPL-002.json - Test Execution & Fix Cycle Task
```json
{
"id": "IMPL-002",
"title": "Execute and fix tests for [sourceSessionId]",
"status": "pending",
"meta": {
"type": "test-fix",
"agent": "@test-fix-agent",
"source_session": "[sourceSessionId]",
"test_framework": "jest|pytest|cargo|detected",
"max_iterations": 5,
"use_codex": false // Set to true if --use-codex flag present
},
"context": {
"requirements": [
"Execute complete test suite (generated in IMPL-001)",
"Diagnose test failures using Gemini analysis with bug-fix template",
"Present fixes to user for manual application (default)",
"Use Codex ONLY if user explicitly requests automation",
"Iterate until all tests pass or max iterations reached",
"Revert changes if unable to fix within iteration limit"
],
"focus_paths": [
"tests/**/*",
"src/**/*.test.*",
"{implementation_files_from_source_session}"
],
"acceptance": [
"All tests pass successfully (100% pass rate)",
"No test failures or errors in final run",
"Code changes are minimal and surgical",
"All fixes are verified through retest",
"Iteration logs document fix progression"
],
"depends_on": ["IMPL-001"],
"source_context": {
"session_id": "[sourceSessionId]",
"test_generation_summary": ".workflow/[testSessionId]/.summaries/IMPL-001-summary.md",
"implementation_summaries": [
".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
]
}
},
"flow_control": {
"pre_analysis": [
{
"step": "load_source_session_summaries",
"action": "Load implementation context from source session",
"commands": [
"bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
"bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
],
"output_to": "implementation_context",
"on_error": "skip_optional"
},
{
"step": "discover_test_framework",
"action": "Identify test framework and test command",
"commands": [
"bash(jq -r '.scripts.test // \"npm test\"' package.json 2>/dev/null || echo 'pytest' || echo 'cargo test')",
"bash([ -f 'package.json' ] && echo 'jest/npm' || [ -f 'pytest.ini' ] && echo 'pytest' || [ -f 'Cargo.toml' ] && echo 'cargo' || echo 'unknown')"
],
"output_to": "test_command",
"on_error": "fail"
},
{
"step": "analyze_test_coverage",
"action": "Analyze test coverage and identify missing tests",
"commands": [
"bash(find . -name \"*.test.*\" -type f)",
"bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
"bash(# Count implementation files vs test files)",
"bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
"bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))",
"bash(echo \"Implementation files: $impl_count, Test files: $test_count\")"
],
"output_to": "test_coverage_analysis",
"on_error": "skip_optional"
},
{
"step": "identify_files_without_tests",
"action": "List implementation files that lack corresponding test files",
"commands": [
"bash(# For each changed file from source session, check if test exists)",
"bash(for file in [changed_files]; do test_file=$(echo $file | sed 's/\\(.*\\)\\.\\(ts\\|js\\|py\\)$/\\1.test.\\2/'); [ ! -f \"$test_file\" ] && echo \"$file\"; done)"
],
"output_to": "files_without_tests",
"on_error": "skip_optional"
},
{
"step": "prepare_test_environment",
"action": "Ensure test environment is ready",
"commands": [
"bash([ -f 'package.json' ] && npm install 2>/dev/null || true)",
"bash([ -f 'requirements.txt' ] && pip install -q -r requirements.txt 2>/dev/null || true)"
],
"output_to": "environment_status",
"on_error": "skip_optional"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Execute iterative test-fix-retest cycle",
"description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
"test_fix_cycle": {
"max_iterations": 5,
"cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
"tools": {
"test_execution": "bash(test_command)",
"diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
"fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
"verification": "bash(test_command) + regression_check"
},
"exit_conditions": {
"success": "all_tests_pass",
"failure": "max_iterations_reached",
"error": "test_command_not_found"
}
},
"modification_points": [
"PHASE 1: Initial Test Execution",
" 1.1. Discover test command from framework detection",
" 1.2. Execute initial test run: bash([test_command])",
" 1.3. Parse test output and count failures",
" 1.4. If all pass → Skip to PHASE 3 (success)",
" 1.5. If failures → Store failure output, proceed to PHASE 2",
"",
"PHASE 2: Iterative Test-Fix-Retest Cycle (max 5 iterations)",
" Note: This phase handles test failures, NOT test generation failures",
" Initialize: max_iterations=5, current_iteration=0",
" ",
" WHILE (tests failing AND current_iteration < max_iterations):",
" current_iteration++",
" ",
" STEP 2.1: Gemini Diagnosis (using bug-fix template)",
" - Prepare diagnosis context:",
" * Test failure output from previous run",
" * Source files from focus_paths",
" * Implementation summaries from source session",
" - Execute Gemini analysis with bug-fix template:",
" bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
" PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
" TASK: Systematic bug analysis and fix recommendations for test failure",
" MODE: analysis",
" CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
" Test output: [test_failures]",
" Source files: [focus_paths]",
" Implementation: [implementation_context]",
" EXPECTED: Root cause analysis, code path tracing, targeted fixes",
" RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Bug: [test_failure_description]",
" Minimal surgical fixes only - no refactoring",
" \" > fix-iteration-[N]-diagnosis.md)",
" - Parse diagnosis → extract fix_suggestion and target_files",
" - Present fix to user for manual application (default)",
" ",
" STEP 2.2: Apply Fix (Based on meta.use_codex Flag)",
" ",
" IF meta.use_codex = false (DEFAULT):",
" - Present Gemini diagnosis to user for manual fix",
" - User applies fix based on diagnosis recommendations",
" - Stage changes: bash(git add -A)",
" - Store fix log: .process/fix-iteration-[N]-changes.log",
" ",
" IF meta.use_codex = true (--use-codex flag present):",
" - Stage current changes (if valid git repo): bash(git add -A)",
" - First iteration: Start new Codex session",
" codex -C [project_root] --full-auto exec \"",
" PURPOSE: Fix test failure iteration 1",
" TASK: [fix_suggestion from Gemini]",
" MODE: write",
" CONTEXT: Diagnosis: .workflow/.process/fix-iteration-1-diagnosis.md",
" Target files: [target_files]",
" Implementation context: [implementation_context]",
" EXPECTED: Minimal code changes to resolve test failure",
" RULES: Apply ONLY suggested changes, no refactoring",
" Preserve existing code style",
" \" --skip-git-repo-check -s danger-full-access",
" - Subsequent iterations: Resume session for context continuity",
" codex exec \"",
" CONTINUE TO NEXT FIX:",
" Iteration [N] of 5: Fix test failure",
" ",
" PURPOSE: Fix remaining test failures",
" TASK: [fix_suggestion from Gemini iteration N]",
" CONTEXT: Previous fixes applied, diagnosis: .process/fix-iteration-[N]-diagnosis.md",
" EXPECTED: Surgical fix for current failure",
" RULES: Build on previous fixes, maintain consistency",
" \" resume --last --skip-git-repo-check -s danger-full-access",
" - Store fix log: .process/fix-iteration-[N]-changes.log",
" ",
" STEP 2.3: Retest and Verification",
" - Re-execute test suite: bash([test_command])",
" - Capture output: .process/fix-iteration-[N]-retest.log",
" - Count failures: bash(grep -c 'FAIL\\|ERROR' .process/fix-iteration-[N]-retest.log)",
" - Check for regression:",
" IF new_failures > previous_failures:",
" WARN: Regression detected",
" Include in next Gemini diagnosis context",
" - Analyze results:",
" IF all_tests_pass:",
" BREAK loop → Proceed to PHASE 3",
" ELSE:",
" Update test_failures context",
" CONTINUE loop",
" ",
" IF max_iterations reached AND tests still failing:",
" EXECUTE: git reset --hard HEAD (revert all changes)",
" MARK: Task status = blocked",
" GENERATE: Detailed failure report with iteration logs",
" EXIT: Require manual intervention",
"",
"PHASE 3: Final Validation and Certification",
" 3.1. Execute final confirmation test run",
" 3.2. Generate success summary:",
" - Iterations required: [current_iteration]",
" - Fixes applied: [summary from iteration logs]",
" - Test results: All passing ✅",
" 3.3. Mark task status: completed",
" 3.4. Update TODO_LIST.md: Mark as ✅",
" 3.5. Certify code: APPROVED for deployment"
],
"logic_flow": [
"Load source session implementation context",
"Discover test framework and command",
"PHASE 0: Test Coverage Check",
" Analyze existing test files",
" Identify files without tests",
" IF tests missing:",
" Report to user (no automatic generation)",
" Wait for user to generate tests or request automation",
" ELSE:",
" Skip to Phase 1",
"PHASE 1: Initial Test Execution",
" Execute test suite",
" IF all pass → Success (Phase 3)",
" ELSE → Store failures, proceed to Phase 2",
"PHASE 2: Iterative Fix Cycle (max 5 iterations)",
" LOOP (max 5 times):",
" 1. Gemini diagnoses failure with bug-fix template → fix suggestion",
" 2. Check meta.use_codex flag:",
" - IF false (default): Present fix to user for manual application",
" - IF true (--use-codex): Codex applies fix with resume for continuity",
" 3. Retest and check results",
" 4. IF pass → Exit loop to Phase 3",
" 5. ELSE → Continue with updated context",
" IF max iterations → Revert + report failure",
"PHASE 3: Final Validation",
" Confirm all tests pass",
" Generate summary (include test generation info)",
" Certify code APPROVED"
],
"error_handling": {
"max_iterations_reached": {
"action": "revert_all_changes",
"commands": [
"bash(git reset --hard HEAD)",
"bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
],
"report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
},
"test_command_fails": {
"action": "treat_as_test_failure",
"context": "Use stderr as failure context for Gemini diagnosis"
},
"codex_apply_fails": {
"action": "retry_once_then_skip",
"fallback": "Mark iteration as skipped, continue to next"
},
"gemini_diagnosis_fails": {
"action": "retry_with_simplified_context",
"fallback": "Use previous diagnosis, continue"
},
"regression_detected": {
"action": "log_warning_continue",
"context": "Include regression info in next Gemini diagnosis"
}
},
"depends_on": [],
"output": "test_fix_results"
}
],
"target_files": [
"Auto-discovered from test failures",
"Extracted from Gemini diagnosis each iteration",
"Format: file:function:lines or file (for new files)"
],
"codex_session": {
"strategy": "resume_for_continuity",
"first_iteration": "codex exec \"fix iteration 1\" --full-auto",
"subsequent_iterations": "codex exec \"fix iteration N\" resume --last",
"benefits": [
"Maintains conversation context across fixes",
"Remembers previous decisions and patterns",
"Ensures consistency in fix approach",
"Reduces redundant context injection"
]
}
}
}
```
### Phase 3: IMPL_PLAN.md Generation
#### Document Structure
```markdown
---
identifier: WFS-test-[session-id]
source_session: WFS-[source-session-id]
workflow_type: test_session
test_framework: jest|pytest|cargo|detected
---
# Test Validation Plan: [Source Session Topic]
## Summary
Execute comprehensive test suite for implementation from session WFS-[source-session-id].
Diagnose and fix all test failures using iterative Gemini analysis and Codex execution.
## Source Session Context
- **Implementation Session**: WFS-[source-session-id]
- **Completed Tasks**: IMPL-001, IMPL-002, ...
- **Changed Files**: [list from git log]
- **Implementation Summaries**: [references to source session summaries]
## Test Framework
- **Detected Framework**: jest|pytest|cargo|other
- **Test Command**: npm test|pytest|cargo test
- **Test Files**: [discovered test files]
- **Coverage**: [estimated test coverage]
## Test-Fix-Retest Cycle
- **Max Iterations**: 5
- **Diagnosis Tool**: Gemini (analysis mode with bug-fix template from bug-index.md)
- **Fix Tool**: Manual (default, meta.use_codex=false) or Codex (if --use-codex flag, meta.use_codex=true)
- **Verification**: Bash test execution + regression check
### Cycle Workflow
1. **Initial Test**: Execute full suite, capture failures
2. **Iterative Fix Loop** (max 5 times):
- Gemini diagnoses failure using bug-fix template → surgical fix suggestion
- Check meta.use_codex flag:
- If false (default): Present fix to user for manual application
- If true (--use-codex): Codex applies fix with resume for context continuity
- Retest and verify (check for regressions)
- Continue until all pass or max iterations reached
3. **Final Validation**: Confirm all tests pass, certify code
### Error Recovery
- **Max iterations reached**: Revert all changes, report failure
- **Test command fails**: Treat as test failure, diagnose with Gemini
- **Codex fails**: Retry once, skip iteration if still failing
- **Regression detected**: Log warning, include in next diagnosis
## Task Breakdown
- **IMPL-001**: Execute and validate tests with iterative fix cycle
## Implementation Strategy
- **Phase 1**: Initial test execution and failure capture
- **Phase 2**: Iterative Gemini diagnosis + Codex fix + retest
- **Phase 3**: Final validation and code certification
## Success Criteria
- All tests pass (100% pass rate)
- No test failures or errors in final run
- Minimal, surgical code changes
- Iteration logs document fix progression
- Code certified APPROVED for deployment
```
### Phase 4: TODO_LIST.md Generation
```markdown
# Tasks: Test Validation for [Source Session]
## Task Progress
- [ ] **IMPL-001**: Execute and validate tests with iterative fix cycle → [📋](./.task/IMPL-001.json)
## Execution Details
- **Source Session**: WFS-[source-session-id]
- **Test Framework**: jest|pytest|cargo
- **Max Iterations**: 5
- **Tools**: Gemini diagnosis + Codex resume fixes
## Status Legend
- `- [ ]` = Pending
- `- [x]` = Completed
```
## Output Files Structure
```
.workflow/WFS-test-[session]/
├── workflow-session.json # Test session metadata
├── IMPL_PLAN.md # Test validation plan
├── TODO_LIST.md # Progress tracking
├── .task/
│ └── IMPL-001.json # Test-fix task with cycle spec
├── .process/
│ ├── ANALYSIS_RESULTS.md # From concept-enhanced (optional)
│ ├── context-package.json # From context-gather
│ ├── initial-test.log # Phase 1: Initial test results
│ ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
│ ├── fix-iteration-1-changes.log # Codex changes iteration 1
│ ├── fix-iteration-1-retest.log # Retest results iteration 1
│ ├── fix-iteration-N-*.md/log # Subsequent iterations
│ └── final-test.log # Phase 3: Final validation
└── .summaries/
└── IMPL-001-summary.md # Success report OR failure report
```
## Error Handling
### Input Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Not a test session | Missing workflow_type: "test_session" | Verify session created by test-gen |
| Source session not found | Invalid source_session_id | Check source session exists |
| No implementation summaries | Source session incomplete | Ensure source session has completed tasks |
### Test Framework Discovery Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| No test command found | Unknown framework | Manual test command specification |
| No test files found | Tests not written | Request user to write tests first |
| Test dependencies missing | Incomplete setup | Run dependency installation |
### Generation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Invalid JSON structure | Template error | Fix task generation logic |
| Missing required fields | Incomplete metadata | Validate session metadata |
## Integration & Usage
### Command Chain
- **Called By**: `/workflow:test-gen` (Phase 4)
- **Calls**: None (terminal command)
- **Followed By**: `/workflow:execute` (user-triggered)
### Basic Usage
```bash
# Manual fix mode (default)
/workflow:tools:test-task-generate --session WFS-test-auth
# Automated Codex fix mode
/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
```
### Flag Behavior
- **No flag**: `meta.use_codex=false`, manual fixes presented to user
- **--use-codex**: `meta.use_codex=true`, Codex automatically applies fixes with resume mechanism
## Related Commands
- `/workflow:test-gen` - Creates test session and calls this tool
- `/workflow:tools:context-gather` - Provides cross-session context
- `/workflow:tools:concept-enhanced` - Provides test strategy analysis
- `/workflow:execute` - Executes the generated test-fix task
- `@test-fix-agent` - Agent that executes the iterative test-fix cycle
## Agent Execution Notes
The `@test-fix-agent` will execute the task by following the `flow_control.implementation_approach` specification:
1. **Load task JSON**: Read complete test-fix task from `.task/IMPL-002.json`
2. **Check meta.use_codex**: Determine fix mode (manual or automated)
3. **Execute pre_analysis**: Load source context, discover framework, analyze tests
4. **Phase 1**: Run initial test suite
5. **Phase 2**: If failures, enter iterative loop:
- Use Gemini for diagnosis (analysis mode with bug-fix template)
- Check meta.use_codex flag:
- If false (default): Present fix suggestions to user for manual application
- If true (--use-codex): Use Codex resume for automated fixes (maintains context)
- Retest and check for regressions
- Repeat max 5 times
6. **Phase 3**: Generate summary and certify code
7. **Error Recovery**: Revert changes if max iterations reached
**Bug Diagnosis Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
**Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.

911
.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md Normal file
View File

@@ -0,0 +1,911 @@
---
name: animation-extract
description: Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation
argument-hint: "[--base-path <path>] [--session <id>] [--urls "<list>"] [--mode <auto|interactive>] [--focus "<types>"]"
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
---
# Animation Extraction Command
## Overview
Extract animation and transition patterns from web pages using CSS extraction, visual analysis, or interactive questioning. This command generates production-ready animation tokens and guidelines that integrate with design systems.
**Strategy**: Hybrid Extraction with Interactive Fallback
- **Auto Mode (Priority 1)**: Extract from CSS via Chrome DevTools when URLs provided
- **Visual Mode (Priority 2)**: Analyze screenshots for motion cues (blur, position changes)
- **Interactive Mode (Priority 3)**: Guided questioning when extraction insufficient
- **Output**: `animation-tokens.json` + `animation-guide.md`
## Phase 0: Setup & Input Validation
### Step 1: Detect Input Mode & Base Path
```bash
# Detect input source
# Priority: --urls → url mode | --mode interactive → question mode
# Parse URLs if provided (format: "target:url,target:url,...")
IF --urls:
url_list = []
FOR pair IN split(--urls, ","):
IF ":" IN pair:
target, url = pair.split(":", 1)
url_list.append({target: target.strip(), url: url.strip()})
ELSE:
url_list.append({target: "page", url: pair.strip()})
has_urls = true
primary_url = url_list[0].url
ELSE:
has_urls = false
# Determine extraction mode
extraction_mode = --mode OR (has_urls ? "auto" : "interactive")
# Parse animation focus (if provided)
IF --focus:
focus_types = split(--focus, ",") # e.g., "transitions,hover,scroll"
ELSE:
focus_types = ["all"] # Extract all animation types
# Determine base path
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# OR use --base-path / --session parameters
```
### Step 2: Load Design Tokens Context
```bash
# Load existing design tokens for duration/easing alignment
IF exists({base_path}/style-extraction/style-1/design-tokens.json):
design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
has_design_context = true
ELSE:
has_design_context = false
WARN: "⚠️ No design tokens found - animation tokens will use standalone values"
# Create output directory
bash(mkdir -p {base_path}/animation-extraction)
bash(mkdir -p {base_path}/.intermediates/animation-analysis)
```
---
**Phase 0 Output**: `extraction_mode`, `base_path`, `has_urls`, `url_list[]`, `focus_types[]`, `has_design_context`
## Phase 1: CSS Animation Extraction (Auto Mode - URL Required)
### Step 1: Check Extraction Mode
```bash
# extraction_mode == "interactive" → skip to Phase 2
# extraction_mode == "auto" AND has_urls → execute this phase
```
**If interactive mode**: Skip to Phase 2
### Step 2: Extract Computed Animations (Auto-Trigger)
```bash
# AUTO-TRIGGER: If URLs are available, automatically extract CSS animations/transitions
IF has_urls AND mcp_chrome_devtools_available:
REPORT: "🔍 Auto-triggering URL mode: Extracting CSS animations and transitions"
# Read extraction script
script_content = Read(~/.claude/scripts/extract-animations.js)
# For each URL:
FOR url_info IN url_list:
target = url_info.target
url = url_info.url
REPORT: " Processing: {target} ({url})"
# Open page in Chrome DevTools
mcp__chrome-devtools__navigate_page(url=url)
# Wait for page to fully load and animations to initialize
bash(sleep 2)
# Execute extraction script
result = mcp__chrome-devtools__evaluate_script(function=script_content)
# Save raw animation data
Write({base_path}/.intermediates/animation-analysis/animations-{target}.json, result)
REPORT: " ✅ Extracted: {result.summary.total_animations} animations, {result.summary.total_transitions} transitions"
animations_extracted = true
REPORT: " ✅ CSS animation extraction complete"
ELSE IF has_urls AND NOT mcp_chrome_devtools_available:
animations_extracted = false
REPORT: "⚠️ Chrome DevTools MCP not available"
REPORT: " Falling back to interactive mode for animation guidance"
ELSE:
animations_extracted = false
```
**Extraction Script Reference**: `~/.claude/scripts/extract-animations.js`
**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
**Script returns**:
- `metadata`: Extraction timestamp, URL, method
- `transitions`: Array of transition definitions (property, duration, easing, delay)
- `animations`: Array of keyframe animations (name, duration, easing, keyframes)
- `transforms`: Common transform patterns
- `summary`: Statistics (total_animations, total_transitions, unique_easings)
**Benefits**:
- ✅ Real animation values from production sites
- ✅ Captures all CSS transitions and @keyframes rules
- ✅ Identifies common easing functions and durations
- ✅ Maps animations to element selectors
---
**Phase 1 Output**: `animations-{target}.json` (intermediate files)
## Phase 2: Interactive Animation Specification (Interactive/Fallback Mode)
### Step 1: Check if Extraction Sufficient
```bash
# If animations extracted from CSS, check coverage
IF animations_extracted:
total_animations = sum([data.summary.total_animations for data in all_extracted])
total_transitions = sum([data.summary.total_transitions for data in all_extracted])
# If sufficient data found, skip interactive mode
IF total_animations >= 3 OR total_transitions >= 5:
REPORT: "✅ Sufficient animation data extracted from CSS"
SKIP to Phase 3
ELSE:
REPORT: "⚠️ Limited animation data found - launching interactive mode"
extraction_insufficient = true
ELSE:
extraction_insufficient = true
```
### Step 2: Generate Animation Questions (Main Flow)
```bash
# If extraction failed or insufficient, use interactive questioning
IF extraction_insufficient OR extraction_mode == "interactive":
REPORT: "🤔 Interactive animation specification mode"
REPORT: " Context: {has_design_context ? 'Aligning with design tokens' : 'Standalone animation system'}"
REPORT: " Focus: {focus_types}"
# Determine question categories based on focus_types
question_categories = []
IF "all" IN focus_types OR "transitions" IN focus_types:
question_categories.append("timing_scale")
question_categories.append("easing_philosophy")
IF "all" IN focus_types OR "interactions" IN focus_types OR "hover" IN focus_types:
question_categories.append("button_interactions")
question_categories.append("card_interactions")
question_categories.append("input_interactions")
IF "all" IN focus_types OR "page" IN focus_types:
question_categories.append("page_transitions")
IF "all" IN focus_types OR "loading" IN focus_types:
question_categories.append("loading_states")
IF "all" IN focus_types OR "scroll" IN focus_types:
question_categories.append("scroll_animations")
```
### Step 3: Output Questions in Text Format (Main Flow)
```markdown
# Generate and output structured questions
REPORT: ""
REPORT: "===== 动画规格交互式配置 ====="
REPORT: ""
question_number = 1
questions_output = []
# Q1: Timing Scale (if included)
IF "timing_scale" IN question_categories:
REPORT: "【问题{question_number} - 时间尺度】您的设计需要什么样的过渡速度？"
REPORT: "a) 快速敏捷"
REPORT: " 说明：100-200ms 过渡，适合工具型应用和即时反馈场景"
REPORT: "b) 平衡适中"
REPORT: " 说明：200-400ms 过渡，通用选择，符合多数用户预期"
REPORT: "c) 流畅舒缓"
REPORT: " 说明：400-600ms 过渡，适合品牌展示和沉浸式体验"
REPORT: "d) 自定义"
REPORT: " 说明：需要指定具体数值和使用场景"
REPORT: ""
questions_output.append({id: question_number, category: "timing_scale", options: ["a", "b", "c", "d"]})
question_number += 1
# Q2: Easing Philosophy (if included)
IF "easing_philosophy" IN question_categories:
REPORT: "【问题{question_number} - 缓动风格】哪种缓动曲线符合您的品牌调性？"
REPORT: "a) 线性匀速"
REPORT: " 说明：恒定速度，技术感和精确性，适合数据可视化"
REPORT: "b) 快入慢出"
REPORT: " 说明：快速启动自然减速，最接近物理世界，通用推荐"
REPORT: "c) 慢入慢出"
REPORT: " 说明：平滑对称，精致优雅，适合高端品牌"
REPORT: "d) 弹性效果"
REPORT: " 说明：Spring/Bounce 回弹，活泼现代，适合互动性强的应用"
REPORT: ""
questions_output.append({id: question_number, category: "easing_philosophy", options: ["a", "b", "c", "d"]})
question_number += 1
# Q3-5: Interaction Animations (button, card, input - if included)
IF "button_interactions" IN question_categories:
REPORT: "【问题{question_number} - 按钮交互】按钮悬停/点击时如何反馈？"
REPORT: "a) 微妙变化"
REPORT: " 说明：仅颜色/透明度变化，适合简约设计"
REPORT: "b) 抬升效果"
REPORT: " 说明：轻微缩放+阴影加深，增强物理感知"
REPORT: "c) 滑动移位"
REPORT: " 说明：Transform translateY，视觉引导明显"
REPORT: "d) 无动画"
REPORT: " 说明：静态交互，性能优先或特定品牌要求"
REPORT: ""
questions_output.append({id: question_number, category: "button_interactions", options: ["a", "b", "c", "d"]})
question_number += 1
IF "card_interactions" IN question_categories:
REPORT: "【问题{question_number} - 卡片交互】卡片悬停时的动画效果？"
REPORT: "a) 阴影加深"
REPORT: " 说明：Box-shadow 变化，层次感增强"
REPORT: "b) 上浮效果"
REPORT: " 说明：Transform translateY(-4px)，明显的空间层次"
REPORT: "c) 缩放放大"
REPORT: " 说明：Scale(1.02)，突出焦点内容"
REPORT: "d) 无动画"
REPORT: " 说明：静态卡片，性能或设计考量"
REPORT: ""
questions_output.append({id: question_number, category: "card_interactions", options: ["a", "b", "c", "d"]})
question_number += 1
IF "input_interactions" IN question_categories:
REPORT: "【问题{question_number} - 表单交互】输入框是否需要微交互反馈？"
REPORT: "a) 聚焦动画"
REPORT: " 说明：边框/阴影过渡，清晰的状态指示"
REPORT: "b) 错误抖动"
REPORT: " 说明：水平shake动画，错误提示更明显"
REPORT: "c) 成功勾选"
REPORT: " 说明：Checkmark 动画，完成反馈"
REPORT: "d) 全部包含"
REPORT: " 说明：聚焦+错误+成功的完整反馈体系"
REPORT: "e) 无微交互"
REPORT: " 说明：标准表单，无额外动画"
REPORT: ""
questions_output.append({id: question_number, category: "input_interactions", options: ["a", "b", "c", "d", "e"]})
question_number += 1
# Q6: Page Transitions (if included)
IF "page_transitions" IN question_categories:
REPORT: "【问题{question_number} - 页面过渡】页面/路由切换是否需要过渡动画？"
REPORT: "a) 淡入淡出"
REPORT: " 说明：Crossfade 效果，平滑过渡不突兀"
REPORT: "b) 滑动切换"
REPORT: " 说明：Swipe left/right，方向性导航"
REPORT: "c) 缩放过渡"
REPORT: " 说明：Scale in/out，空间层次感"
REPORT: "d) 无过渡"
REPORT: " 说明：即时切换，性能优先"
REPORT: ""
questions_output.append({id: question_number, category: "page_transitions", options: ["a", "b", "c", "d"]})
question_number += 1
# Q7: Loading States (if included)
IF "loading_states" IN question_categories:
REPORT: "【问题{question_number} - 加载状态】加载时使用何种动画风格？"
REPORT: "a) 旋转加载器"
REPORT: " 说明：Spinner 圆形旋转，通用加载指示"
REPORT: "b) 脉冲闪烁"
REPORT: " 说明：Opacity pulse，轻量级反馈"
REPORT: "c) 骨架屏"
REPORT: " 说明：Shimmer effect，内容占位预览"
REPORT: "d) 进度条"
REPORT: " 说明：Linear fill，进度量化展示"
REPORT: ""
questions_output.append({id: question_number, category: "loading_states", options: ["a", "b", "c", "d"]})
question_number += 1
# Q8: Scroll Animations (if included)
IF "scroll_animations" IN question_categories:
REPORT: "【问题{question_number} - 滚动动画】元素是否在滚动时触发动画？"
REPORT: "a) 淡入出现"
REPORT: " 说明：Opacity 0→1，渐进式内容呈现"
REPORT: "b) 上滑出现"
REPORT: " 说明：TranslateY + fade，方向性引导"
REPORT: "c) 缩放淡入"
REPORT: " 说明：Scale 0.9→1 + fade，聚焦效果"
REPORT: "d) 交错延迟"
REPORT: " 说明：Stagger 序列动画，列表渐次呈现"
REPORT: "e) 无滚动动画"
REPORT: " 说明：静态内容，性能或可访问性考量"
REPORT: ""
questions_output.append({id: question_number, category: "scroll_animations", options: ["a", "b", "c", "d", "e"]})
question_number += 1
REPORT: "支持格式："
REPORT: "- 空格分隔：1a 2b 3c"
REPORT: "- 逗号分隔：1a,2b,3c"
REPORT: "- 自由组合：1a 2b,3c"
REPORT: ""
REPORT: "请输入您的选择："
```
### Step 4: Wait for User Input (Main Flow)
```javascript
# Wait for user input
user_raw_input = WAIT_FOR_USER_INPUT()
# Store raw input for debugging
REPORT: "收到输入: {user_raw_input}"
```
### Step 5: Parse User Answers (Main Flow)
```javascript
# Intelligent input parsing (support multiple formats)
answers = {}
# Parse input using intelligent matching
# Support formats: "1a 2b 3c", "1a,2b,3c", "1a 2b,3c"
parsed_responses = PARSE_USER_INPUT(user_raw_input, questions_output)
# Validate parsing
IF parsed_responses.is_valid:
# Map question numbers to categories
FOR response IN parsed_responses.answers:
question_id = response.question_id
selected_option = response.option
# Find category for this question
FOR question IN questions_output:
IF question.id == question_id:
category = question.category
answers[category] = selected_option
REPORT: "✅ 问题{question_id} ({category}): 选择 {selected_option}"
break
ELSE:
REPORT: "❌ 输入格式无法识别，请参考格式示例重新输入："
REPORT: " 示例：1a 2b 3c 4d"
# Return to Step 3 for re-input
GOTO Step 3
```
### Step 6: Write Animation Specification (Main Flow)
```javascript
# Map user choices to specification structure
specification = {
"metadata": {
"source": "interactive",
"timestamp": NOW(),
"focus_types": focus_types,
"has_design_context": has_design_context
},
"timing_scale": MAP_TIMING_SCALE(answers.timing_scale),
"easing_philosophy": MAP_EASING_PHILOSOPHY(answers.easing_philosophy),
"interactions": {
"button": MAP_BUTTON_INTERACTION(answers.button_interactions),
"card": MAP_CARD_INTERACTION(answers.card_interactions),
"input": MAP_INPUT_INTERACTION(answers.input_interactions)
},
"page_transitions": MAP_PAGE_TRANSITIONS(answers.page_transitions),
"loading_animations": MAP_LOADING_STATES(answers.loading_states),
"scroll_animations": MAP_SCROLL_ANIMATIONS(answers.scroll_animations)
}
# Mapping functions (inline logic)
FUNCTION MAP_TIMING_SCALE(option):
SWITCH option:
CASE "a": RETURN {scale: "fast", base_duration: "150ms", range: "100-200ms"}
CASE "b": RETURN {scale: "balanced", base_duration: "300ms", range: "200-400ms"}
CASE "c": RETURN {scale: "smooth", base_duration: "500ms", range: "400-600ms"}
CASE "d": RETURN {scale: "custom", base_duration: "300ms", note: "User to provide values"}
FUNCTION MAP_EASING_PHILOSOPHY(option):
SWITCH option:
CASE "a": RETURN {style: "linear", curve: "linear"}
CASE "b": RETURN {style: "ease-out", curve: "cubic-bezier(0, 0, 0.2, 1)"}
CASE "c": RETURN {style: "ease-in-out", curve: "cubic-bezier(0.4, 0, 0.2, 1)"}
CASE "d": RETURN {style: "spring", curve: "cubic-bezier(0.34, 1.56, 0.64, 1)"}
FUNCTION MAP_BUTTON_INTERACTION(option):
SWITCH option:
CASE "a": RETURN {type: "subtle", properties: ["color", "background-color", "opacity"]}
CASE "b": RETURN {type: "lift", properties: ["transform", "box-shadow"], transform: "scale(1.02)"}
CASE "c": RETURN {type: "slide", properties: ["transform"], transform: "translateY(-2px)"}
CASE "d": RETURN {type: "none", properties: []}
FUNCTION MAP_CARD_INTERACTION(option):
SWITCH option:
CASE "a": RETURN {type: "shadow", properties: ["box-shadow"]}
CASE "b": RETURN {type: "float", properties: ["transform", "box-shadow"], transform: "translateY(-4px)"}
CASE "c": RETURN {type: "scale", properties: ["transform"], transform: "scale(1.02)"}
CASE "d": RETURN {type: "none", properties: []}
FUNCTION MAP_INPUT_INTERACTION(option):
SWITCH option:
CASE "a": RETURN {enabled: ["focus"], focus: {properties: ["border-color", "box-shadow"]}}
CASE "b": RETURN {enabled: ["error"], error: {animation: "shake", keyframes: "translateX"}}
CASE "c": RETURN {enabled: ["success"], success: {animation: "checkmark", keyframes: "draw"}}
CASE "d": RETURN {enabled: ["focus", "error", "success"]}
CASE "e": RETURN {enabled: []}
FUNCTION MAP_PAGE_TRANSITIONS(option):
SWITCH option:
CASE "a": RETURN {enabled: true, style: "fade", animation: "fadeIn/fadeOut"}
CASE "b": RETURN {enabled: true, style: "slide", animation: "slideLeft/slideRight"}
CASE "c": RETURN {enabled: true, style: "zoom", animation: "zoomIn/zoomOut"}
CASE "d": RETURN {enabled: false}
FUNCTION MAP_LOADING_STATES(option):
SWITCH option:
CASE "a": RETURN {style: "spinner", animation: "rotate", keyframes: "360deg"}
CASE "b": RETURN {style: "pulse", animation: "pulse", keyframes: "opacity"}
CASE "c": RETURN {style: "skeleton", animation: "shimmer", keyframes: "gradient-shift"}
CASE "d": RETURN {style: "progress", animation: "fill", keyframes: "width"}
FUNCTION MAP_SCROLL_ANIMATIONS(option):
SWITCH option:
CASE "a": RETURN {enabled: true, style: "fade", animation: "fadeIn"}
CASE "b": RETURN {enabled: true, style: "slideUp", animation: "slideUp", transform: "translateY(20px)"}
CASE "c": RETURN {enabled: true, style: "scaleIn", animation: "scaleIn", transform: "scale(0.9)"}
CASE "d": RETURN {enabled: true, style: "stagger", animation: "fadeIn", stagger_delay: "100ms"}
CASE "e": RETURN {enabled: false}
# Write specification file
output_path = "{base_path}/.intermediates/animation-analysis/animation-specification.json"
Write(output_path, JSON.stringify(specification, indent=2))
REPORT: "✅ Animation specification saved to {output_path}"
REPORT: " Proceeding to token synthesis..."
```
---
**Phase 2 Output**: `animation-specification.json` (user preferences)
## Phase 3: Animation Token Synthesis (Agent - No User Interaction)
**Executor**: `Task(ui-design-agent)` for token generation
**⚠️ CRITICAL**: This phase has NO user interaction. Agent only reads existing data and generates tokens.
### Step 1: Load All Input Sources
```bash
# Gather all available animation data
extracted_animations = []
IF animations_extracted:
FOR target IN target_list:
IF exists({base_path}/.intermediates/animation-analysis/animations-{target}.json):
extracted_animations.append(Read(file))
user_specification = null
IF exists({base_path}/.intermediates/animation-analysis/animation-specification.json):
user_specification = Read(file)
REPORT: "✅ Loaded user specification from Phase 2"
ELSE:
REPORT: "⚠️ No user specification found - using extracted CSS only"
design_tokens = null
IF has_design_context:
design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
```
### Step 2: Launch Token Generation Task (Pure Synthesis)
```javascript
Task(ui-design-agent): `
[ANIMATION_TOKEN_GENERATION_TASK]
Synthesize animation data into production-ready tokens - NO user interaction
SESSION: {session_id} | BASE_PATH: {base_path}
## ⚠️ CRITICAL: Pure Synthesis Task
- NO user questions or interaction
- READ existing specification files ONLY
- Generate tokens based on available data
## Input Sources (Read-Only)
1. **Extracted CSS Animations** (if available):
${extracted_animations.length > 0 ? JSON.stringify(extracted_animations) : "None - skip CSS data"}
2. **User Specification** (REQUIRED if Phase 2 ran):
File: {base_path}/.intermediates/animation-analysis/animation-specification.json
${user_specification ? "Status: ✅ Found - READ this file for user choices" : "Status: ⚠️ Not found - use CSS extraction only"}
3. **Design Tokens Context** (for alignment):
${design_tokens ? JSON.stringify(design_tokens) : "None - standalone animation system"}
## Synthesis Rules
### Priority System
1. User specification from animation-specification.json (highest priority)
2. Extracted CSS values from animations-*.json (medium priority)
3. Industry best practices (fallback)
### Duration Normalization
- IF user_specification.timing_scale EXISTS:
Use user's chosen scale (fast/balanced/smooth/custom)
- ELSE IF extracted CSS durations available:
Cluster extracted durations into 3-5 semantic scales
- ELSE:
Use standard scale (instant:0ms, fast:150ms, normal:300ms, slow:500ms, very-slow:800ms)
- Align with design token spacing scale if available
### Easing Standardization
- IF user_specification.easing_philosophy EXISTS:
Use user's chosen philosophy (linear/ease-out/ease-in-out/spring)
- ELSE IF extracted CSS easings available:
Identify common easing functions from CSS
- ELSE:
Use standard easings
- Map to semantic names and convert to cubic-bezier format
### Animation Categorization
Organize into:
- **duration**: Timing scale (instant, fast, normal, slow, very-slow)
- **easing**: Easing functions (linear, ease-in, ease-out, ease-in-out, spring)
- **transitions**: Property-specific transitions (color, transform, opacity, etc.)
- **keyframes**: Named @keyframe animations (fadeIn, slideInUp, pulse, etc.)
- **interactions**: Interaction-specific presets (button-hover, card-hover, input-focus, etc.)
- **page_transitions**: Route/view change animations (if user enabled)
- **scroll_animations**: Scroll-triggered animations (if user enabled)
### User Specification Integration
IF user_specification EXISTS:
- Map user choices to token values:
* timing_scale → duration values
* easing_philosophy → easing curves
* interactions.button → interactions.button-hover token
* interactions.card → interactions.card-hover token
* interactions.input → micro-interaction tokens
* page_transitions → page_transitions tokens
* loading_animations → loading state tokens
* scroll_animations → scroll_animations tokens
## Generate Files
### 1. animation-tokens.json
Complete animation token structure using var() references:
{
"duration": {
"instant": "0ms",
"fast": "150ms", # Adjust based on user_specification.timing_scale
"normal": "300ms",
"slow": "500ms",
"very-slow": "800ms"
},
"easing": {
"linear": "linear",
"ease-in": "cubic-bezier(0.4, 0, 1, 1)",
"ease-out": "cubic-bezier(0, 0, 0.2, 1)", # Adjust based on user_specification.easing_philosophy
"ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
"spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
},
"transitions": {
"color": {
"property": "color, background-color, border-color",
"duration": "var(--duration-fast)",
"easing": "var(--easing-ease-out)"
},
"transform": {
"property": "transform",
"duration": "var(--duration-normal)",
"easing": "var(--easing-ease-out)"
},
"opacity": {
"property": "opacity",
"duration": "var(--duration-normal)",
"easing": "var(--easing-ease-in-out)"
}
},
"keyframes": {
"fadeIn": {"0%": {"opacity": "0"}, "100%": {"opacity": "1"}},
"slideInUp": {"0%": {"transform": "translateY(20px)", "opacity": "0"}, "100%": {"transform": "translateY(0)", "opacity": "1"}},
"pulse": {"0%, 100%": {"opacity": "1"}, "50%": {"opacity": "0.7"}},
# Add more keyframes based on user_specification choices
},
"interactions": {
"button-hover": {
# Map from user_specification.interactions.button
"properties": ["background-color", "transform"],
"duration": "var(--duration-fast)",
"easing": "var(--easing-ease-out)",
"transform": "scale(1.02)"
},
"card-hover": {
# Map from user_specification.interactions.card
"properties": ["box-shadow", "transform"],
"duration": "var(--duration-normal)",
"easing": "var(--easing-ease-out)",
"transform": "translateY(-4px)"
}
# Add input-focus, modal-open, dropdown-toggle based on user choices
},
"page_transitions": {
# IF user_specification.page_transitions.enabled == true
"fade": {
"duration": "var(--duration-normal)",
"enter": "fadeIn",
"exit": "fadeOut"
}
# Add slide, zoom based on user_specification.page_transitions.style
},
"scroll_animations": {
# IF user_specification.scroll_animations.enabled == true
"default": {
"animation": "fadeIn", # From user_specification.scroll_animations.style
"duration": "var(--duration-slow)",
"easing": "var(--easing-ease-out)",
"threshold": "0.1",
"stagger_delay": "100ms" # From user_specification if stagger chosen
}
}
}
### 2. animation-guide.md
Comprehensive usage guide with sections:
- **Animation Philosophy**: Rationale from user choices and CSS analysis
- **Duration Scale**: Explanation of timing values and usage contexts
- **Easing Functions**: When to use each easing curve
- **Transition Presets**: Property-specific transition guidelines
- **Keyframe Animations**: Available animations and use cases
- **Interaction Patterns**: Button, card, input animation examples
- **Page Transitions**: Route change animation implementation (if enabled)
- **Scroll Animations**: Scroll-trigger setup and configuration (if enabled)
- **Implementation Examples**: CSS and JavaScript code samples
- **Accessibility**: prefers-reduced-motion media query setup
- **Performance Best Practices**: Hardware acceleration, will-change usage
## Output File Paths
- animation-tokens.json: {base_path}/animation-extraction/animation-tokens.json
- animation-guide.md: {base_path}/animation-extraction/animation-guide.md
## Critical Requirements
- ✅ READ animation-specification.json if it exists (from Phase 2)
- ✅ Use Write() tool immediately for both files
- ✅ All tokens use CSS Custom Property format: var(--duration-fast)
- ✅ Include prefers-reduced-motion media query guidance
- ✅ Validate all cubic-bezier values are valid (4 numbers between 0-1)
- ❌ NO user questions or interaction in this phase
- ❌ NO external research or MCP calls
`
```
---
**Phase 3 Output**: `animation-tokens.json` + `animation-guide.md`
## Phase 4: Verify Output
### Step 1: Check Files Created
```bash
# Verify animation tokens created
bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
bash(test -f {base_path}/animation-extraction/animation-guide.md && echo "exists")
# Validate structure
bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "easing" && echo "valid")
```
### Step 2: Verify File Sizes
```bash
bash(ls -lh {base_path}/animation-extraction/)
```
**Output**: 2 files verified (animation-tokens.json, animation-guide.md)
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
{content: "CSS animation extraction (auto mode)", status: "completed", activeForm: "Extracting from CSS"},
{content: "Interactive specification (main flow)", status: "completed", activeForm: "Collecting user input in main flow"},
{content: "Animation token synthesis (agent - no interaction)", status: "completed", activeForm: "Generating tokens via agent"},
{content: "Verify output files", status: "completed", activeForm: "Verifying files"}
]});
```
### Output Message
```
✅ Animation extraction complete!
Configuration:
- Session: {session_id}
- Extraction Mode: {extraction_mode} (auto/interactive)
- Input Sources:
{IF animations_extracted:
- ✅ CSS extracted from {len(url_list)} URL(s)
}
{IF user_specification:
- ✅ User specification via interactive mode (main flow)
}
{IF has_design_context:
- ✅ Aligned with existing design tokens
}
Generated Files:
{base_path}/animation-extraction/
├── animation-tokens.json # Production-ready animation tokens
└── animation-guide.md # Usage guidelines and examples
{IF animations_extracted:
Intermediate Analysis:
{base_path}/.intermediates/animation-analysis/
├── animations-*.json # Extracted CSS data ({len(url_list)} files)
}
{IF user_specification:
└── animation-specification.json # User preferences
}
Extracted Data Summary:
- Duration scales: {duration_count} values
- Easing functions: {easing_count} types
- Interaction presets: {interaction_count} patterns
- Keyframe animations: {keyframe_count} animations
Next: Animation tokens ready for integration
• style-extract/layout-extract can reference animation tokens
• generate command will include animation CSS
• Tokens use var() format for easy customization
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
# Create output directories
bash(mkdir -p {base_path}/animation-extraction)
bash(mkdir -p {base_path}/.intermediates/animation-analysis)
```
### Validation Commands
```bash
# Check if already extracted
bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
# Validate JSON structure
bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
# Count animation types
bash(cat animation-tokens.json | grep -c "\"keyframes\":")
```
### File Operations
```bash
# Load design tokens context
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && cat it)
# Verify output
bash(ls {base_path}/animation-extraction/)
```
## Output Structure
```
{base_path}/
├── .intermediates/ # Intermediate analysis files
│ └── animation-analysis/
│ ├── animations-{target}.json # Extracted CSS (auto mode)
│ └── animation-specification.json # User input (interactive mode)
└── animation-extraction/ # Final animation tokens
├── animation-tokens.json # Production-ready animation tokens
└── animation-guide.md # Usage guide and examples
```
## animation-tokens.json Format
```json
{
"duration": {
"instant": "0ms",
"fast": "150ms",
"normal": "300ms",
"slow": "500ms",
"very-slow": "800ms"
},
"easing": {
"linear": "linear",
"ease-in": "cubic-bezier(0.4, 0, 1, 1)",
"ease-out": "cubic-bezier(0, 0, 0.2, 1)",
"ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
"spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
},
"transitions": {
"color": {"property": "...", "duration": "var(--duration-fast)", "easing": "..."},
"transform": {"property": "...", "duration": "...", "easing": "..."}
},
"keyframes": {
"fadeIn": {"0%": {...}, "100%": {...}},
"slideInUp": {...}
},
"interactions": {
"button-hover": {"properties": [...], "duration": "...", "transform": "..."},
"card-hover": {...}
},
"page_transitions": {...},
"scroll_animations": {...}
}
```
**Requirements**: CSS var() format, valid cubic-bezier values, prefers-reduced-motion support
## Error Handling
### Common Errors
```
ERROR: No URL or interactive mode specified
→ Provide --urls for auto mode or use --mode interactive
ERROR: Chrome DevTools unavailable
→ Automatically falls back to interactive mode
ERROR: Insufficient animation data extracted
→ Launches interactive mode for supplemental input
ERROR: Invalid cubic-bezier values
→ Validates and corrects to nearest standard easing
```
### Recovery Strategies
- **CSS extraction failure**: Falls back to interactive mode
- **Partial extraction**: Supplements with interactive questioning
- **Invalid data**: Validates and uses fallback values
## Key Features
- **Auto-Trigger CSS Extraction** - Automatically extracts animations when --urls provided
- **Hybrid Strategy** - Combines CSS extraction with interactive specification
- **Main Flow Interaction** - User questions in main flow, agent only for token synthesis
- **Intelligent Fallback** - Gracefully handles extraction failures
- **Context-Aware** - Aligns with existing design tokens
- **Production-Ready** - CSS var() format, accessibility support
- **Comprehensive Coverage** - Transitions, keyframes, interactions, scroll animations
- **Separated Concerns** - User decisions (Phase 2 main flow) → Token generation (Phase 3 agent)
## Integration
**Workflow Position**: Between style extraction and layout extraction (or parallel)
**New Workflow**:
1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
2. **`/workflow:ui-design:animation-extract`** → `animation-tokens.json` + `animation-guide.md` (NEW)
3. `/workflow:ui-design:layout-extract` → `layout-templates.json`
4. `/workflow:ui-design:generate`:
- Reads: design-tokens.json + animation-tokens.json + layout-templates.json
- Generates: Prototypes with animation CSS included
**Input**: URLs (auto mode) or interactive questioning
**Output**: `animation-tokens.json` + `animation-guide.md`
**Next**: `/workflow:ui-design:layout-extract` OR `/workflow:ui-design:generate`
**Note**: This command extracts motion design patterns (animations, transitions) to complement visual style tokens. Can run in parallel with layout-extract.

480
.claude/skills/command-guide/reference/commands/workflow/ui-design/batch-generate.md Normal file
View File

@@ -0,0 +1,480 @@
---
name: batch-generate
description: Prompt-driven batch UI generation using target-style-centric parallel execution with design token application
argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
---
# Batch Generate UI Prototypes (/workflow:ui-design:batch-generate)
## Overview
Prompt-driven UI generation with intelligent target extraction and **target-style-centric batch execution**. Each agent handles all layouts for one target × style combination.
**Strategy**: Prompt → Targets → Batched Generation
- **Prompt-driven**: Describe what to build, command extracts targets
- **Agent scope**: Each of `T × S` agents generates `L` layouts
- **Parallel batching**: Max 6 concurrent agents for optimal throughput
- **Component isolation**: Complete task independence
- **Style-aware**: HTML adapts to design_attributes
- **Self-contained CSS**: Direct token values (no var() refs)
**Supports**: Pages (full layouts) and components (isolated elements)
## Phase 1: Setup & Validation
### Step 1: Parse Prompt & Resolve Configuration
```bash
# Parse required parameters
prompt_text = --prompt
device_type = --device-type OR "responsive"
# Extract targets from prompt
IF --targets:
target_list = split_and_clean(--targets)
ELSE:
target_list = extract_targets_from_prompt(prompt_text) # See helpers
IF NOT target_list: target_list = ["home"] # Fallback
# Detect target type
target_type = --target-type OR detect_target_type(target_list)
# Resolve base path
IF --base-path:
base_path = --base-path
ELSE IF --session:
bash(find .workflow/WFS-{session} -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
ELSE:
bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
# Get variant counts
style_variants = --style-variants OR bash(ls {base_path}/style-extraction/style-* -d | wc -l)
layout_variants = --layout-variants OR 3
```
**Output**: `base_path`, `target_list[]`, `target_type`, `device_type`, `style_variants`, `layout_variants`
### Step 2: Validate Design Tokens
```bash
# Check design tokens exist
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
# Load design space analysis (optional, from intermediates)
IF exists({base_path}/.intermediates/style-analysis/design-space-analysis.json):
design_space_analysis = Read({base_path}/.intermediates/style-analysis/design-space-analysis.json)
```
**Output**: `design_tokens_valid`, `design_space_analysis`
### Step 3: Gather Layout Inspiration (Reuse or Create)
```bash
# Check if layout inspirations already exist from layout-extract phase
inspiration_source = "{base_path}/.intermediates/layout-analysis/inspirations"
FOR target IN target_list:
# Priority 1: Reuse existing inspiration from layout-extract
IF exists({inspiration_source}/{target}-layout-ideas.txt):
# Reuse existing inspiration (no action needed)
REPORT: "Using existing layout inspiration for {target}"
ELSE:
# Priority 2: Generate new inspiration via MCP
bash(mkdir -p {inspiration_source})
search_query = "{target} {target_type} layout patterns variations"
mcp__exa__web_search_exa(query=search_query, numResults=5)
# Extract context from prompt for this target
target_requirements = extract_relevant_context_from_prompt(prompt_text, target)
# Write inspiration file to centralized location
Write({inspiration_source}/{target}-layout-ideas.txt, inspiration_content)
REPORT: "Created new layout inspiration for {target}"
```
**Output**: `T` inspiration text files (reused or created in `.intermediates/layout-analysis/inspirations/`)
## Phase 2: Target-Style-Centric Batch Generation (Agent)
**Executor**: `Task(ui-design-agent)` × `T × S` tasks in **batched parallel** (max 6 concurrent)
### Step 1: Calculate Batch Execution Plan
```bash
bash(mkdir -p {base_path}/prototypes)
# Build task list: T × S combinations
MAX_PARALLEL = 6
total_tasks = T × S
total_batches = ceil(total_tasks / MAX_PARALLEL)
# Initialize batch tracking
TodoWrite({todos: [
{content: "Batch 1/{batches}: Generate 6 tasks", status: "in_progress"},
{content: "Batch 2/{batches}: Generate 6 tasks", status: "pending"},
...
]})
```
### Step 2: Launch Batched Agent Tasks
For each batch (up to 6 parallel tasks):
```javascript
Task(ui-design-agent): `
[TARGET_STYLE_UI_GENERATION_FROM_PROMPT]
🎯 ONE component: {target} × Style-{style_id} ({philosophy_name})
Generate: {layout_variants} × 2 files (HTML + CSS per layout)
PROMPT CONTEXT: {target_requirements} # Extracted from original prompt
TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants}
BASE_PATH: {base_path}
DEVICE: {device_type}
${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""}
## Reference
- Layout inspiration: Read("{base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt")
- Design tokens: Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
Parse ALL token values including:
* colors, typography (with combinations), spacing, opacity
* border_radius, shadows, breakpoints
* component_styles (button, card, input variants)
${design_attributes ? "- Adapt DOM to: density, visual_weight, formality, organic_vs_geometric" : ""}
## Generation
For EACH layout (1 to {layout_variants}):
1. HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
- Complete HTML5: <!DOCTYPE>, <head>, <body>
- CSS ref: <link href="{target}-style-{style_id}-layout-N.css">
- Semantic: <header>, <nav>, <main>, <footer>
- A11y: ARIA labels, landmarks, responsive meta
- Viewport: <meta name="viewport" content="width=device-width, initial-scale=1.0">
- Follow user requirements from prompt
${design_attributes ? `
- DOM adaptation:
* density='spacious' → flatter hierarchy
* density='compact' → deeper nesting
* visual_weight='heavy' → extra wrappers
* visual_weight='minimal' → direct structure` : ""}
- Device-specific: Optimize for {device_type}
2. CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
- Self-contained: Direct token VALUES (no var())
- Use tokens: colors, fonts, spacing, opacity, borders, shadows
- IF tokens.component_styles exists: Use component presets for buttons, cards, inputs
- IF tokens.typography.combinations exists: Use typography presets for headings and body text
- Device-optimized: {device_type} styles
${device_type === 'responsive' ? '- Responsive: Mobile-first @media' : '- Fixed: ' + device_type}
${design_attributes ? `
- Token selection: density → spacing, visual_weight → shadows` : ""}
## Notes
- ✅ Token VALUES directly from design-tokens.json (with typography.combinations, opacity, component_styles support)
- ✅ Follow prompt requirements for {target}
- ✅ Optimize for {device_type}
- ❌ NO var() refs, NO external deps
- Layouts structurally DISTINCT
- Write files IMMEDIATELY (per layout)
- CSS filename MUST match HTML <link href>
`
# After each batch completes
TodoWrite: Mark batch completed, next batch in_progress
```
## Phase 3: Verify & Generate Previews
### Step 1: Verify Generated Files
```bash
# Count expected vs found
bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
# Expected: S × L × T × 2
# Validate samples
Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
```
**Output**: `S × L × T × 2` files verified
### Step 2: Run Preview Generation Script
```bash
bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
```
**Script generates**:
- `compare.html` (interactive matrix)
- `index.html` (navigation)
- `PREVIEW.md` (instructions)
### Step 3: Verify Preview Files
```bash
bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
```
**Output**: 3 preview files
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Setup and parse prompt", status: "completed", activeForm: "Parsing prompt"},
{content: "Detect token sources", status: "completed", activeForm: "Loading design systems"},
{content: "Gather layout inspiration", status: "completed", activeForm: "Researching layouts"},
{content: "Batch 1/{batches}: Generate 6 tasks", status: "completed", activeForm: "Generating batch 1"},
... (all batches completed)
{content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
]});
```
### Output Message
```
✅ Prompt-driven batch UI generation complete!
Prompt: {prompt_text}
Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants}
- Target Type: {target_type}
- Device Type: {device_type}
- Targets: {target_list} ({T} targets)
- Total Prototypes: {S × L × T}
Batch Execution:
- Total tasks: {T × S} (targets × styles)
- Batches: {batches} (max 6 parallel per batch)
- Agent scope: {L} layouts per target×style
- Component isolation: Complete task independence
- Device-specific: All layouts optimized for {device_type}
Quality:
- Style-aware: {design_space_analysis ? 'HTML adapts to design_attributes' : 'Standard structure'}
- CSS: Self-contained (direct token values, no var())
- Device-optimized: {device_type} layouts
- Tokens: Production-ready (WCAG AA compliant)
Generated Files:
{base_path}/prototypes/
├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
├── {target}-style-{s}-layout-{l}.css
├── compare.html (interactive matrix)
├── index.html (navigation)
└── PREVIEW.md (instructions)
Layout Inspirations:
{base_path}/.intermediates/layout-analysis/inspirations/ ({T} text files, reused or created)
Preview:
1. Open compare.html (recommended)
2. Open index.html
3. Read PREVIEW.md
Next: /workflow:ui-design:update
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
# Count style variants
bash(ls {base_path}/style-extraction/style-* -d | wc -l)
# Check design tokens exist
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
```
### Validation Commands
```bash
# Count generated files
bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
# Verify preview
bash(test -f {base_path}/prototypes/compare.html && echo "exists")
```
### File Operations
```bash
# Create prototypes directory
bash(mkdir -p {base_path}/prototypes)
# Create inspirations directory (if needed)
bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
# Run preview script
bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
```
## Output Structure
```
{base_path}/
├── .intermediates/
│ └── layout-analysis/
│ └── inspirations/
│ └── {target}-layout-ideas.txt # Layout inspiration (reused or created)
├── prototypes/
│ ├── {target}-style-{s}-layout-{l}.html # Final prototypes
│ ├── {target}-style-{s}-layout-{l}.css
│ ├── compare.html
│ ├── index.html
│ └── PREVIEW.md
└── style-extraction/
└── style-{s}/
├── design-tokens.json
└── style-guide.md
```
## Error Handling
### Common Errors
```
ERROR: No design tokens found
→ Run /workflow:ui-design:style-extract first
ERROR: No targets extracted from prompt
→ Use --targets explicitly or rephrase prompt
ERROR: MCP search failed
→ Check network, retry
ERROR: Batch {N} agent tasks failed
→ Check agent output, retry specific target×style combinations
ERROR: Script permission denied
→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
```
### Recovery Strategies
- **Partial success**: Keep successful target×style combinations
- **Missing design_attributes**: Works without (less style-aware)
- **Invalid tokens**: Validate design-tokens.json structure
- **Failed batch**: Re-run command, only failed combinations will retry
## Quality Checklist
- [ ] Prompt clearly describes targets
- [ ] CSS uses direct token values (no var())
- [ ] HTML adapts to design_attributes (if available)
- [ ] Semantic HTML5 structure
- [ ] ARIA attributes present
- [ ] Device-optimized layouts
- [ ] Layouts structurally distinct
- [ ] compare.html works
## Key Features
- **Prompt-Driven**: Describe what to build, command extracts targets
- **Target-Style-Centric**: `T×S` agents, each handles `L` layouts
- **Parallel Batching**: Max 6 concurrent agents with progress tracking
- **Component Isolation**: Complete task independence
- **Style-Aware**: HTML adapts to design_attributes
- **Self-Contained CSS**: Direct token values (no var())
- **Device-Specific**: Optimized for desktop/mobile/tablet/responsive
- **Inspiration-Based**: MCP-powered layout research
- **Production-Ready**: Semantic, accessible, responsive
## Integration
**Input**:
- Required: Prompt, design-tokens.json
- Optional: design-space-analysis.json (from `.intermediates/style-analysis/`)
- Reuses: Layout inspirations from `.intermediates/layout-analysis/inspirations/` (if available from layout-extract)
**Output**: S×L×T prototypes for `/workflow:ui-design:update`
**Compatible**: style-extract, explore-auto, imitate-auto outputs
**Optimization**: Reuses layout inspirations from layout-extract phase, avoiding duplicate MCP searches
## Usage Examples
### Basic: Auto-detection
```bash
/workflow:ui-design:batch-generate \
--prompt "Dashboard with metric cards and charts"
# Auto: latest design run, extracts "dashboard" target
# Output: S × L × 1 prototypes
```
### With Session
```bash
/workflow:ui-design:batch-generate \
--prompt "Auth pages: login, signup, password reset" \
--session WFS-auth
# Uses WFS-auth's design run
# Extracts: ["login", "signup", "password-reset"]
# Batches: 2 (if S=3: 9 tasks = 6+3)
# Output: S × L × 3 prototypes
```
### Components with Device Type
```bash
/workflow:ui-design:batch-generate \
--prompt "Mobile UI components: navbar, card, footer" \
--target-type component \
--device-type mobile
# Mobile-optimized component generation
# Output: S × L × 3 prototypes
```
### Large Scale (Multi-batch)
```bash
/workflow:ui-design:batch-generate \
--prompt "E-commerce site" \
--targets "home,shop,product,cart,checkout" \
--style-variants 4 \
--layout-variants 2
# Tasks: 5 × 4 = 20 (4 batches: 6+6+6+2)
# Output: 4 × 2 × 5 = 40 prototypes
```
## Helper Functions Reference
### Target Extraction
```python
# extract_targets_from_prompt(prompt_text)
# Patterns: "Create X and Y", "Generate X, Y, Z pages", "Build X"
# Returns: ["x", "y", "z"] (normalized lowercase with hyphens)
# detect_target_type(target_list)
# Keywords: page (home, dashboard, login) vs component (navbar, card, button)
# Returns: "page" or "component"
# extract_relevant_context_from_prompt(prompt_text, target)
# Extracts sentences mentioning specific target
# Returns: Relevant context string
```
## Batch Execution Details
### Parallel Control
- **Max concurrent**: 6 agents per batch
- **Task distribution**: T × S tasks = ceil(T×S/6) batches
- **Progress tracking**: TodoWrite per-batch status
- **Examples**:
- 3 tasks → 1 batch
- 9 tasks → 2 batches (6+3)
- 20 tasks → 4 batches (6+6+6+2)
### Performance
| Tasks | Batches | Est. Time | Efficiency |
|-------|---------|-----------|------------|
| 1-6 | 1 | 3-5 min | 100% |
| 7-12 | 2 | 6-10 min | ~85% |
| 13-18 | 3 | 9-15 min | ~80% |
| 19-30 | 4-5 | 12-25 min | ~75% |
### Optimization Tips
1. **Reduce tasks**: Fewer targets or styles
2. **Adjust layouts**: L=2 instead of L=3 for faster iteration
3. **Stage generation**: Core pages first, secondary pages later
## Notes
- **Prompt quality**: Clear descriptions improve target extraction
- **Token sources**: Consolidated (production) or proposed (fast-track)
- **Batch parallelism**: Max 6 concurrent for stability
- **Scalability**: Tested up to 30+ tasks (5+ batches)
- **Dependencies**: MCP web search, ui-generate-preview.sh script

361
.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md Normal file
View File

@@ -0,0 +1,361 @@
---
name: capture
description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping
argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
---
# Batch Screenshot Capture (/workflow:ui-design:capture)
## Overview
Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes multiple URLs in parallel.
**Strategy**: MCP → Playwright → Chrome → Manual
**Output**: Flat structure `screenshots/{target}.png`
## Phase 1: Initialize & Parse
### Step 1: Determine Base Path
```bash
# Priority: --base-path > session > standalone
bash(if [ -n "$BASE_PATH" ]; then
echo "$BASE_PATH"
elif [ -n "$SESSION_ID" ]; then
find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d-%H%M%S)"
else
echo ".workflow/.design/run-$(date +%Y%m%d-%H%M%S)"
fi)
bash(mkdir -p $BASE_PATH/screenshots)
```
### Step 2: Parse URL Map
```javascript
// Input: "home:https://linear.app, pricing:https://linear.app/pricing"
url_entries = []
FOR pair IN split(params["--url-map"], ","):
parts = pair.split(":", 1)
IF len(parts) != 2:
ERROR: "Invalid format: {pair}. Expected: 'target:url'"
EXIT 1
target = parts[0].strip().lower().replace(" ", "-")
url = parts[1].strip()
// Validate target name
IF NOT regex_match(target, r"^[a-z0-9][a-z0-9_-]*$"):
ERROR: "Invalid target: {target}"
EXIT 1
// Add https:// if missing
IF NOT url.startswith("http"):
url = f"https://{url}"
url_entries.append({target, url})
```
**Output**: `base_path`, `url_entries[]`
### Step 3: Initialize Todos
```javascript
TodoWrite({todos: [
{content: "Parse url-map", status: "completed", activeForm: "Parsing"},
{content: "Detect MCP tools", status: "in_progress", activeForm: "Detecting"},
{content: "Capture screenshots", status: "pending", activeForm: "Capturing"},
{content: "Verify results", status: "pending", activeForm: "Verifying"}
]})
```
## Phase 2: Detect Screenshot Tools
### Step 1: Check MCP Availability
```javascript
// List available MCP servers
all_resources = ListMcpResourcesTool()
available_servers = unique([r.server for r in all_resources])
// Check Chrome DevTools MCP
chrome_devtools = "chrome-devtools" IN available_servers
chrome_screenshot = check_tool_exists("mcp__chrome-devtools__take_screenshot")
// Check Playwright MCP
playwright_mcp = "playwright" IN available_servers
playwright_screenshot = check_tool_exists("mcp__playwright__screenshot")
// Determine primary tool
IF chrome_devtools AND chrome_screenshot:
tool = "chrome-devtools"
ELSE IF playwright_mcp AND playwright_screenshot:
tool = "playwright"
ELSE:
tool = null
```
**Output**: `tool` (chrome-devtools | playwright | null)
### Step 2: Check Local Fallback
```bash
# Only if MCP unavailable
bash(which playwright 2>/dev/null || echo "")
bash(which google-chrome || which chrome || which chromium 2>/dev/null || echo "")
```
**Output**: `local_tools[]`
## Phase 3: Capture Screenshots
### Screenshot Format Options
**PNG Format** (default, lossless):
- **Pros**: Lossless quality, best for detailed UI screenshots
- **Cons**: Larger file sizes (typically 200-500 KB per screenshot)
- **Parameters**: `format: "png"` (no quality parameter)
- **Use case**: High-fidelity UI replication, design system extraction
**WebP Format** (optional, lossy/lossless):
- **Pros**: Smaller file sizes with good quality (50-70% smaller than PNG)
- **Cons**: Requires quality parameter, slight quality loss at high compression
- **Parameters**: `format: "webp", quality: 90` (80-100 recommended)
- **Use case**: Batch captures, network-constrained environments
**JPEG Format** (optional, lossy):
- **Pros**: Smallest file sizes
- **Cons**: Lossy compression, not recommended for UI screenshots
- **Parameters**: `format: "jpeg", quality: 90`
- **Use case**: Photo-heavy pages, not recommended for UI design
### Step 1: MCP Capture (If Available)
```javascript
IF tool == "chrome-devtools":
// Get or create page
pages = mcp__chrome-devtools__list_pages()
IF pages.length == 0:
mcp__chrome-devtools__new_page({url: url_entries[0].url})
page_idx = 0
ELSE:
page_idx = 0
mcp__chrome-devtools__select_page({pageIdx: page_idx})
// Capture each URL
FOR entry IN url_entries:
mcp__chrome-devtools__navigate_page({url: entry.url, timeout: 30000})
bash(sleep 2)
// PNG format doesn't support quality parameter
// Use PNG for lossless quality (larger files)
mcp__chrome-devtools__take_screenshot({
fullPage: true,
format: "png",
filePath: f"{base_path}/screenshots/{entry.target}.png"
})
// Alternative: Use WebP with quality for smaller files
// mcp__chrome-devtools__take_screenshot({
// fullPage: true,
// format: "webp",
// quality: 90,
// filePath: f"{base_path}/screenshots/{entry.target}.webp"
// })
ELSE IF tool == "playwright":
FOR entry IN url_entries:
mcp__playwright__screenshot({
url: entry.url,
output_path: f"{base_path}/screenshots/{entry.target}.png",
full_page: true,
timeout: 30000
})
```
### Step 2: Local Fallback (If MCP Failed)
```bash
# Try Playwright CLI
bash(playwright screenshot "$url" "$output_file" --full-page --timeout 30000)
# Try Chrome headless
bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$url")
```
### Step 3: Manual Mode (If All Failed)
```
⚠️ Manual Screenshot Required
Failed URLs:
home: https://linear.app
Save to: .workflow/.design/run-20250110/screenshots/home.png
Steps:
1. Visit URL in browser
2. Take full-page screenshot
3. Save to path above
4. Type 'ready' to continue
Options: ready | skip | abort
```
## Phase 4: Verification
### Step 1: Scan Captured Files
```bash
bash(ls -1 $base_path/screenshots/*.{png,jpg,jpeg,webp} 2>/dev/null)
bash(du -h $base_path/screenshots/*.png 2>/dev/null)
```
### Step 2: Generate Metadata
```javascript
captured_files = Glob(f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}")
captured_targets = [basename_no_ext(f) for f in captured_files]
metadata = {
"timestamp": current_timestamp(),
"total_requested": len(url_entries),
"total_captured": len(captured_targets),
"screenshots": []
}
FOR entry IN url_entries:
is_captured = entry.target IN captured_targets
metadata.screenshots.append({
"target": entry.target,
"url": entry.url,
"captured": is_captured,
"path": f"{base_path}/screenshots/{entry.target}.png" IF is_captured ELSE null,
"size_kb": file_size_kb IF is_captured ELSE null
})
Write(f"{base_path}/screenshots/capture-metadata.json", JSON.stringify(metadata))
```
**Output**: `capture-metadata.json`
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Parse url-map", status: "completed", activeForm: "Parsing"},
{content: "Detect MCP tools", status: "completed", activeForm: "Detecting"},
{content: "Capture screenshots", status: "completed", activeForm: "Capturing"},
{content: "Verify results", status: "completed", activeForm: "Verifying"}
]})
```
### Output Message
```
✅ Batch screenshot capture complete!
Summary:
- Requested: {total_requested}
- Captured: {total_captured}
- Success rate: {success_rate}%
- Method: {tool || "Local fallback"}
Output:
{base_path}/screenshots/
├── home.png (245.3 KB)
├── pricing.png (198.7 KB)
└── capture-metadata.json
Next: /workflow:ui-design:extract --images "screenshots/*.png"
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
# Create screenshot directory
bash(mkdir -p $BASE_PATH/screenshots)
```
### Tool Detection
```bash
# Check MCP
all_resources = ListMcpResourcesTool()
# Check local tools
bash(which playwright 2>/dev/null)
bash(which google-chrome 2>/dev/null)
```
### Verification
```bash
# List captures
bash(ls -1 $base_path/screenshots/*.png 2>/dev/null)
# File sizes
bash(du -h $base_path/screenshots/*.png)
```
## Output Structure
```
{base_path}/
└── screenshots/
├── home.png
├── pricing.png
├── about.png
└── capture-metadata.json
```
## Error Handling
### Common Errors
```
ERROR: Invalid url-map format
→ Use: "target:url, target2:url2"
ERROR: png screenshots do not support 'quality'
→ PNG format is lossless, no quality parameter needed
→ Remove quality parameter OR switch to webp/jpeg format
ERROR: MCP unavailable
→ Using local fallback
ERROR: All tools failed
→ Manual mode activated
```
### Format-Specific Errors
```
❌ Wrong: format: "png", quality: 90
✅ Right: format: "png"
✅ Or use: format: "webp", quality: 90
✅ Or use: format: "jpeg", quality: 90
```
### Recovery
- **Partial success**: Keep successful captures
- **Retry**: Re-run with failed targets only
- **Manual**: Follow interactive guidance
## Quality Checklist
- [ ] All requested URLs processed
- [ ] File sizes > 1KB (valid images)
- [ ] Metadata JSON generated
- [ ] No missing targets (or documented)
## Key Features
- **MCP-first**: Prioritize managed tools
- **Multi-tier fallback**: 4 layers (MCP → Local → Manual)
- **Batch processing**: Parallel capture
- **Error tolerance**: Partial failures handled
- **Structured output**: Flat, predictable
## Integration
**Input**: `--url-map` (multiple target:url pairs)
**Output**: `screenshots/*.png` + `capture-metadata.json`
**Called by**: `/workflow:ui-design:imitate-auto`, `/workflow:ui-design:explore-auto`
**Next**: `/workflow:ui-design:extract` or `/workflow:ui-design:explore-layers`

494
.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md Normal file
View File

@@ -0,0 +1,494 @@
---
name: explore-auto
description: Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution
argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
---
# UI Design Auto Workflow Command
## Overview & Execution Model
**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning.
**Unified Target System**: Generates `style_variants × layout_variants × targets` prototypes, where targets can be:
- **Pages** (full-page layouts): home, dashboard, settings, etc.
- **Components** (isolated UI elements): navbar, card, hero, form, etc.
- **Mixed**: Can combine both in a single workflow
**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
1. User triggers: `/workflow:ui-design:explore-auto [params]`
2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
4. Phase 2.3 (animation-extract, optional) → **WAIT for completion** → Auto-continues
5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
8. Phase 5 (batch-plan, optional) → Reports completion
**Phase Transition Mechanism**:
- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
- Upon each phase completion: Automatically process output and execute next phase
- No additional user interaction after Phase 0c confirmation
**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
## Core Rules
1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
2. **No Preliminary Validation**: Sub-commands handle their own validation
3. **Parse & Pass**: Extract data from each output for next phase
4. **Default to All**: When selecting variants/prototypes, use ALL generated items
5. **Track Progress**: Update TodoWrite after each phase
6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
## Parameter Requirements
**Optional Parameters** (all have smart defaults):
- `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
- `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
- `--device-type "desktop|mobile|tablet|responsive|auto"`: Device type for layout optimization (default: `auto` - intelligent detection)
- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
- **Mobile**: 375×812px - Touch-friendly, compact layouts
- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
- **Responsive**: 1920×1080px base with mobile-first breakpoints
- `--session <id>`: Workflow session ID (standalone mode if omitted)
- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
- `--prompt "<description>"`: Design style and target description
- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
- `--batch-plan`: Auto-generate implementation tasks after design-update
**Legacy Parameters** (maintained for backward compatibility):
- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
- `--components "<list>"`: Alias for `--targets` with `--target-type component`
**Input Rules**:
- Must provide at least one: `--images` or `--prompt` or `--targets`
- Multiple parameters can be combined for guided analysis
- If `--targets` not provided, intelligently inferred from prompt/session
**Supported Target Types**:
- **Pages** (full layouts): home, dashboard, settings, profile, login, etc.
- **Components** (UI elements):
- Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
- Content: hero, card, list, table, grid, timeline
- Input: form, search, filter, input-group
- Feedback: modal, alert, toast, badge, progress
- Media: gallery, carousel, video-player, image-card
- Other: footer, pagination, dropdown, tooltip, avatar
**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
- "Generate **3 style variants**" → `--style-variants 3`
- "**2 layout options**" → `--layout-variants 2`
- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
- Explicit flags override prompt inference
## Execution Modes
**Matrix Mode** (style-centric):
- Generates `style_variants × layout_variants × targets` prototypes
- **Phase 1**: `style_variants` complete design systems (extract)
- **Phase 2**: Layout templates extraction (layout-extract)
- **Phase 3**: Style-centric batch generation (generate)
- Sub-phase 1: `targets × layout_variants` target-specific layout plans
- **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
- Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
- Performance: Efficient parallel execution with S agents
- Quality: HTML structure adapts to design_attributes
- Pages: Full-page layouts with complete structure
- Components: Isolated elements with minimal wrapper
**Integrated vs. Standalone**:
- `--session` flag determines session integration or standalone execution
## 6-Phase Execution
### Phase 0a: Intelligent Prompt Parsing
```bash
# Parse variant counts from prompt or use explicit/default values
IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
ELSE:
style_variants = --style-variants OR 3
layout_variants = --layout-variants OR 3
VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
```
### Phase 0a-2: Device Type Inference
```bash
# Device type inference
device_type = "auto"
# Step 1: Explicit parameter (highest priority)
IF --device-type AND --device-type != "auto":
device_type = --device-type
device_source = "explicit"
ELSE:
# Step 2: Prompt analysis
IF --prompt:
device_keywords = {
"desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
"mobile": ["mobile", "phone", "smartphone", "ios", "android"],
"tablet": ["tablet", "ipad", "medium screen"],
"responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
}
detected_device = detect_device_from_prompt(--prompt, device_keywords)
IF detected_device:
device_type = detected_device
device_source = "prompt_inference"
# Step 3: Target type inference
IF device_type == "auto":
# Components are typically desktop-first, pages can vary
device_type = target_type == "component" ? "desktop" : "responsive"
device_source = "target_type_inference"
STORE: device_type, device_source
```
**Device Type Presets**:
- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
- **Mobile**: 375×812px - Touch-friendly, compact layouts
- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
- **Responsive**: 1920×1080px base with mobile-first breakpoints
**Detection Keywords**:
- Prompt contains "mobile", "phone", "smartphone" → mobile
- Prompt contains "tablet", "ipad" → tablet
- Prompt contains "desktop", "web", "laptop" → desktop
- Prompt contains "responsive", "adaptive" → responsive
- Otherwise: Inferred from target type (components→desktop, pages→responsive)
### Phase 0b: Run Initialization & Directory Setup
```bash
run_id = "run-$(date +%Y%m%d-%H%M%S)"
base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
Write({base_path}/.run-metadata.json): {
"run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
"workflow": "ui-design:auto",
"architecture": "style-centric-batch-generation",
"parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
"targets": "${inferred_target_list}", "target_type": "${target_type}",
"prompt": "${prompt_text}", "images": "${images_pattern}",
"device_type": "${device_type}", "device_source": "${device_source}" },
"status": "in_progress",
"performance_mode": "optimized"
}
```
### Phase 0c: Unified Target Inference with Intelligent Type Detection
```bash
# Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
target_list = []; target_type = "auto"; target_source = "none"
# Step 1-2: Explicit parameters (legacy or unified)
IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
ELSE IF --targets:
target_list = split(--targets); target_source = "explicit"
target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
# Step 3: Prompt analysis (Claude internal analysis)
ELSE IF --prompt:
analysis_result = analyze_prompt("{prompt_text}") # Extract targets, types, purpose
target_list = analysis_result.targets
target_type = analysis_result.primary_type OR detect_target_type(target_list)
target_source = "prompt_analysis"
# Step 4: Session synthesis
ELSE IF --session AND exists(role analysis documents):
target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
# Step 5: Fallback
IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
# Validate and clean
validated_targets = [normalize(t) for t in target_list if is_valid(t)]
IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
IF --target-type != "auto": target_type = --target-type
# Interactive confirmation
DISPLAY_CONFIRMATION(target_type, target_source, validated_targets, device_type, device_source):
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
"{emoji} {LABEL} CONFIRMATION (Style-Centric)"
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
"Type: {target_type} | Source: {target_source}"
"Targets ({count}): {', '.join(validated_targets)}"
"Device: {device_type} | Source: {device_source}"
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
"Performance: {style_variants} agent calls"
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
"Modification Options:"
" • 'continue/yes/ok' - Proceed with current configuration"
" • 'targets: a,b,c' - Replace target list"
" • 'skip: x,y' - Remove specific targets"
" • 'add: z' - Add new targets"
" • 'type: page|component' - Change target type"
" • 'device: desktop|mobile|tablet|responsive' - Change device type"
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
user_input = WAIT_FOR_USER_INPUT()
# Process user modifications
MATCH user_input:
"continue|yes|ok" → proceed
"targets: ..." → validated_targets = parse_new_list()
"skip: ..." → validated_targets = remove_items()
"add: ..." → validated_targets = add_items()
"type: ..." → target_type = extract_type()
"device: ..." → device_type = extract_device()
default → proceed with current list
STORE: inferred_target_list, target_type, target_inference_source
# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
# This is the only user interaction point in the workflow
# After this point, all subsequent phases execute automatically without user intervention
```
**Helper Function: detect_target_type()**
```bash
detect_target_type(target_list):
page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
RETURN "component" IF component_matches > page_matches ELSE "page"
```
### Phase 1: Style Extraction
```bash
command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
(--images ? "--images \"{images}\" " : "") +
(--prompt ? "--prompt \"{prompt}\" " : "") +
"--mode explore --variants {style_variants}"
SlashCommand(command)
# Output: {style_variants} style cards with design_attributes
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue)
```
### Phase 2.3: Animation Extraction (Optional - Interactive Mode)
```bash
# Animation extraction for motion design patterns
REPORT: "🚀 Phase 2.3: Animation Extraction (interactive mode)"
REPORT: " → Mode: Interactive specification"
REPORT: " → Purpose: Define motion design patterns"
command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
SlashCommand(command)
# Output: animation-tokens.json + animation-guide.md
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
```
### Phase 2.5: Layout Extraction
```bash
targets_string = ",".join(inferred_target_list)
command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
(--images ? "--images \"{images}\" " : "") +
(--prompt ? "--prompt \"{prompt}\" " : "") +
"--targets \"{targets_string}\" " +
"--mode explore --variants {layout_variants} " +
"--device-type \"{device_type}\""
REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
REPORT: " → Targets: {targets_string}"
REPORT: " → Layout variants: {layout_variants}"
REPORT: " → Device: {device_type}"
SlashCommand(command)
# Output: layout-templates.json with {targets × layout_variants} layout structures
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
```
### Phase 3: UI Assembly
```bash
command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
"--style-variants {style_variants} --layout-variants {layout_variants}"
total = style_variants × layout_variants × len(inferred_target_list)
REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
REPORT: " → Pure assembly: Combining layout templates + design tokens"
REPORT: " → Device: {device_type} (from layout templates)"
REPORT: " → Assembly tasks: {total} combinations"
SlashCommand(command)
# SlashCommand blocks until phase complete
# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
# Output:
# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
# - {target}-style-{s}-layout-{l}.css
# - compare.html (interactive matrix view)
# - PREVIEW.md (usage instructions)
```
### Phase 4: Design System Integration
```bash
command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
SlashCommand(command)
# SlashCommand blocks until phase complete
# Upon completion:
# - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
# - If no --batch-plan: Workflow complete, display final report
```
### Phase 5: Batch Task Generation (Optional)
```bash
IF --batch-plan:
FOR target IN inferred_target_list:
task_desc = "Implement {target} {target_type} based on design system"
SlashCommand("/workflow:plan --agent \"{task_desc}\"")
```
## TodoWrite Pattern
```javascript
// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
TodoWrite({todos: [
{"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
{"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
{"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
{"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
]})
// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
// 1. SlashCommand blocks and returns when phase is complete
// 2. Update current phase: status → "completed"
// 3. Update next phase: status → "in_progress"
// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
// This ensures continuous workflow tracking and prevents premature stopping
```
## Key Features
- **🚀 Performance**: Style-centric batch generation with S agent calls
- **🎨 Style-Aware**: HTML structure adapts to design_attributes
- **✅ Perfect Consistency**: Each style by single agent
- **📦 Autonomous**: No user intervention required between phases
- **🧠 Intelligent**: Parses natural language, infers targets/types
- **🔄 Reproducible**: Deterministic flow with isolated run directories
- **🎯 Flexible**: Supports pages, components, or mixed targets
## Examples
### 1. Page Mode (Prompt Inference)
```bash
/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
# Result: 27 prototypes (3×3×3) - responsive layouts (default)
```
### 2. Mobile-First Design
```bash
/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
```
### 3. Desktop Application
```bash
/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
```
### 4. Tablet Interface
```bash
/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
```
### 5. Custom Matrix with Session
```bash
/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
# Result: 2×2×N prototypes - device type inferred from session
```
### 6. Component Mode (Desktop)
```bash
/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
# Result: 12 prototypes (3×2×2) - desktop components
```
### 7. Intelligent Parsing + Batch Planning
```bash
/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
```
### 8. Large Scale Responsive
```bash
/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
# Result: 36 prototypes (3×3×4) - responsive layouts
```
## Completion Output
```
✅ UI Design Explore-Auto Workflow Complete!
Architecture: Style-Centric Batch Generation
Run ID: {run_id} | Session: {session_id or "standalone"}
Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
Phase 1: {s} complete design systems (style-extract)
Phase 2: {n×l} layout templates (layout-extract explore mode)
- Device: {device_type} layouts
- {n} targets × {l} layout variants = {n×l} structural templates
Phase 3: UI Assembly (generate)
- Pure assembly: layout templates + design tokens
- {s}×{l}×{n} = {total} final prototypes
Phase 4: Brainstorming artifacts updated
[Phase 5: {n} implementation tasks created] # if --batch-plan
Assembly Process:
✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
✅ Layout Extraction: {n×l} reusable structural templates
✅ Pure Assembly: No design decisions in generate phase
✅ Device-Optimized: Layouts designed for {device_type}
Design Quality:
✅ Token-Driven Styling: 100% var() usage
✅ Structural Variety: {l} distinct layouts per target
✅ Style Variety: {s} independent design systems
✅ Device-Optimized: Layouts designed for {device_type}
📂 {base_path}/
├── .intermediates/ (Intermediate analysis files)
│ ├── style-analysis/ (computed-styles.json, design-space-analysis.json)
│ └── layout-analysis/ (dom-structure-*.json, inspirations/*.txt)
├── style-extraction/ ({s} complete design systems)
├── layout-extraction/ ({n×l} layout templates + layout-space-analysis.json)
├── prototypes/ ({total} assembled prototypes)
└── .run-metadata.json (includes device type)
🌐 Preview: {base_path}/prototypes/compare.html
- Interactive {s}×{l} matrix view
- Side-by-side comparison
- Target-specific layouts with style-aware structure
- Toggle between {n} targets
{icon} Targets: {', '.join(targets)} (type: {target_type})
- Each target has {l} custom-designed layouts
- Each style × target × layout has unique HTML structure (not just CSS!)
- Layout plans stored as structured JSON
- Optimized for {device_type} viewing
Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
```

589
.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md Normal file
View File

@@ -0,0 +1,589 @@
---
name: explore-layers
description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer
argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
---
# Interactive Layer Exploration (/workflow:ui-design:explore-layers)
## Overview
Single-URL depth-controlled interactive capture. Progressively explores UI layers from pages to Shadow DOM.
**Depth Levels**:
- `1` = Page (full-page screenshot)
- `2` = Elements (key components)
- `3` = Interactions (modals, dropdowns)
- `4` = Embedded (iframes, widgets)
- `5` = Shadow DOM (web components)
**Requirements**: Chrome DevTools MCP
## Phase 1: Setup & Validation
### Step 1: Parse Parameters
```javascript
url = params["--url"]
depth = int(params["--depth"])
// Validate URL
IF NOT url.startswith("http"):
url = f"https://{url}"
// Validate depth
IF depth NOT IN [1, 2, 3, 4, 5]:
ERROR: "Invalid depth: {depth}. Use 1-5"
EXIT 1
```
### Step 2: Determine Base Path
```bash
bash(if [ -n "$BASE_PATH" ]; then
echo "$BASE_PATH"
elif [ -n "$SESSION_ID" ]; then
find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
echo ".workflow/WFS-$SESSION_ID/design-layers-$(date +%Y%m%d-%H%M%S)"
else
echo ".workflow/.design/layers-$(date +%Y%m%d-%H%M%S)"
fi)
# Create depth directories
bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
```
**Output**: `url`, `depth`, `base_path`
### Step 3: Validate MCP Availability
```javascript
all_resources = ListMcpResourcesTool()
chrome_devtools = "chrome-devtools" IN [r.server for r in all_resources]
IF NOT chrome_devtools:
ERROR: "explore-layers requires Chrome DevTools MCP"
ERROR: "Install: npm i -g @modelcontextprotocol/server-chrome-devtools"
EXIT 1
```
### Step 4: Initialize Todos
```javascript
todos = [
{content: "Setup and validation", status: "completed", activeForm: "Setting up"}
]
FOR level IN range(1, depth + 1):
todos.append({
content: f"Depth {level}: {DEPTH_NAMES[level]}",
status: "pending",
activeForm: f"Capturing depth {level}"
})
todos.append({content: "Generate layer map", status: "pending", activeForm: "Mapping"})
TodoWrite({todos})
```
## Phase 2: Navigate & Load Page
### Step 1: Get or Create Browser Page
```javascript
pages = mcp__chrome-devtools__list_pages()
IF pages.length == 0:
mcp__chrome-devtools__new_page({url: url, timeout: 30000})
page_idx = 0
ELSE:
page_idx = 0
mcp__chrome-devtools__select_page({pageIdx: page_idx})
mcp__chrome-devtools__navigate_page({url: url, timeout: 30000})
bash(sleep 3) // Wait for page load
```
**Output**: `page_idx`
## Phase 3: Depth 1 - Page Level
### Step 1: Capture Full Page
```javascript
TodoWrite(mark_in_progress: "Depth 1: Page")
output_file = f"{base_path}/screenshots/depth-1/full-page.png"
mcp__chrome-devtools__take_screenshot({
fullPage: true,
format: "png",
quality: 90,
filePath: output_file
})
layer_map = {
"url": url,
"depth": depth,
"layers": {
"depth-1": {
"type": "page",
"captures": [{
"name": "full-page",
"path": output_file,
"size_kb": file_size_kb(output_file)
}]
}
}
}
TodoWrite(mark_completed: "Depth 1: Page")
```
**Output**: `depth-1/full-page.png`
## Phase 4: Depth 2 - Element Level (If depth >= 2)
### Step 1: Analyze Page Structure
```javascript
IF depth < 2: SKIP
TodoWrite(mark_in_progress: "Depth 2: Elements")
snapshot = mcp__chrome-devtools__take_snapshot()
// Filter key elements
key_types = ["nav", "header", "footer", "aside", "button", "form", "article"]
key_elements = [
el for el in snapshot.interactiveElements
if el.type IN key_types OR el.role IN ["navigation", "banner", "main"]
][:10] // Limit to top 10
```
### Step 2: Capture Element Screenshots
```javascript
depth_2_captures = []
FOR idx, element IN enumerate(key_elements):
element_name = sanitize(element.text[:20] or element.type) or f"element-{idx}"
output_file = f"{base_path}/screenshots/depth-2/{element_name}.png"
TRY:
mcp__chrome-devtools__take_screenshot({
uid: element.uid,
format: "png",
quality: 85,
filePath: output_file
})
depth_2_captures.append({
"name": element_name,
"type": element.type,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
CATCH error:
REPORT: f"Skip {element_name}: {error}"
layer_map.layers["depth-2"] = {
"type": "elements",
"captures": depth_2_captures
}
TodoWrite(mark_completed: "Depth 2: Elements")
```
**Output**: `depth-2/{element}.png` × N
## Phase 5: Depth 3 - Interaction Level (If depth >= 3)
### Step 1: Analyze Interactive Triggers
```javascript
IF depth < 3: SKIP
TodoWrite(mark_in_progress: "Depth 3: Interactions")
// Detect structure
structure = mcp__chrome-devtools__evaluate_script({
function: `() => ({
modals: document.querySelectorAll('[role="dialog"], .modal').length,
dropdowns: document.querySelectorAll('[role="menu"], .dropdown').length,
tooltips: document.querySelectorAll('[role="tooltip"], [title]').length
})`
})
// Identify triggers
triggers = []
FOR element IN snapshot.interactiveElements:
IF element.attributes CONTAINS ("data-toggle", "aria-haspopup"):
triggers.append({
uid: element.uid,
type: "modal" IF "modal" IN element.classes ELSE "dropdown",
trigger: "click",
text: element.text
})
ELSE IF element.attributes CONTAINS ("title", "data-tooltip"):
triggers.append({
uid: element.uid,
type: "tooltip",
trigger: "hover",
text: element.text
})
triggers = triggers[:10] // Limit
```
### Step 2: Trigger Interactions & Capture
```javascript
depth_3_captures = []
FOR idx, trigger IN enumerate(triggers):
layer_name = f"{trigger.type}-{sanitize(trigger.text[:15]) or idx}"
output_file = f"{base_path}/screenshots/depth-3/{layer_name}.png"
TRY:
// Trigger interaction
IF trigger.trigger == "click":
mcp__chrome-devtools__click({uid: trigger.uid})
ELSE:
mcp__chrome-devtools__hover({uid: trigger.uid})
bash(sleep 1)
// Capture
mcp__chrome-devtools__take_screenshot({
fullPage: false, // Viewport only
format: "png",
quality: 90,
filePath: output_file
})
depth_3_captures.append({
"name": layer_name,
"type": trigger.type,
"trigger_method": trigger.trigger,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
// Dismiss (ESC key)
mcp__chrome-devtools__evaluate_script({
function: `() => {
document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'}));
}`
})
bash(sleep 0.5)
CATCH error:
REPORT: f"Skip {layer_name}: {error}"
layer_map.layers["depth-3"] = {
"type": "interactions",
"triggers": structure,
"captures": depth_3_captures
}
TodoWrite(mark_completed: "Depth 3: Interactions")
```
**Output**: `depth-3/{interaction}.png` × N
## Phase 6: Depth 4 - Embedded Level (If depth >= 4)
### Step 1: Detect Iframes
```javascript
IF depth < 4: SKIP
TodoWrite(mark_in_progress: "Depth 4: Embedded")
iframes = mcp__chrome-devtools__evaluate_script({
function: `() => {
return Array.from(document.querySelectorAll('iframe')).map(iframe => ({
src: iframe.src,
id: iframe.id || 'iframe',
title: iframe.title || 'untitled'
})).filter(i => i.src && i.src.startsWith('http'));
}`
})
```
### Step 2: Capture Iframe Content
```javascript
depth_4_captures = []
FOR idx, iframe IN enumerate(iframes):
iframe_name = f"iframe-{sanitize(iframe.title or iframe.id)}-{idx}"
output_file = f"{base_path}/screenshots/depth-4/{iframe_name}.png"
TRY:
// Navigate to iframe URL in new tab
mcp__chrome-devtools__new_page({url: iframe.src, timeout: 30000})
bash(sleep 2)
mcp__chrome-devtools__take_screenshot({
fullPage: true,
format: "png",
quality: 90,
filePath: output_file
})
depth_4_captures.append({
"name": iframe_name,
"url": iframe.src,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
// Close iframe tab
current_pages = mcp__chrome-devtools__list_pages()
mcp__chrome-devtools__close_page({pageIdx: current_pages.length - 1})
CATCH error:
REPORT: f"Skip {iframe_name}: {error}"
layer_map.layers["depth-4"] = {
"type": "embedded",
"captures": depth_4_captures
}
TodoWrite(mark_completed: "Depth 4: Embedded")
```
**Output**: `depth-4/iframe-*.png` × N
## Phase 7: Depth 5 - Shadow DOM (If depth = 5)
### Step 1: Detect Shadow Roots
```javascript
IF depth < 5: SKIP
TodoWrite(mark_in_progress: "Depth 5: Shadow DOM")
shadow_elements = mcp__chrome-devtools__evaluate_script({
function: `() => {
const elements = Array.from(document.querySelectorAll('*'));
return elements
.filter(el => el.shadowRoot)
.map((el, idx) => ({
tag: el.tagName.toLowerCase(),
id: el.id || \`shadow-\${idx}\`,
innerHTML: el.shadowRoot.innerHTML.substring(0, 100)
}));
}`
})
```
### Step 2: Capture Shadow DOM Components
```javascript
depth_5_captures = []
FOR idx, shadow IN enumerate(shadow_elements):
shadow_name = f"shadow-{sanitize(shadow.id)}"
output_file = f"{base_path}/screenshots/depth-5/{shadow_name}.png"
TRY:
// Inject highlight script
mcp__chrome-devtools__evaluate_script({
function: `() => {
const el = document.querySelector('${shadow.tag}${shadow.id ? "#" + shadow.id : ""}');
if (el) {
el.scrollIntoView({behavior: 'smooth', block: 'center'});
el.style.outline = '3px solid red';
}
}`
})
bash(sleep 0.5)
// Full-page screenshot (component highlighted)
mcp__chrome-devtools__take_screenshot({
fullPage: false,
format: "png",
quality: 90,
filePath: output_file
})
depth_5_captures.append({
"name": shadow_name,
"tag": shadow.tag,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
CATCH error:
REPORT: f"Skip {shadow_name}: {error}"
layer_map.layers["depth-5"] = {
"type": "shadow-dom",
"captures": depth_5_captures
}
TodoWrite(mark_completed: "Depth 5: Shadow DOM")
```
**Output**: `depth-5/shadow-*.png` × N
## Phase 8: Generate Layer Map
### Step 1: Compile Metadata
```javascript
TodoWrite(mark_in_progress: "Generate layer map")
// Calculate totals
total_captures = sum(len(layer.captures) for layer in layer_map.layers.values())
total_size_kb = sum(
sum(c.size_kb for c in layer.captures)
for layer in layer_map.layers.values()
)
layer_map["summary"] = {
"timestamp": current_timestamp(),
"total_depth": depth,
"total_captures": total_captures,
"total_size_kb": total_size_kb
}
Write(f"{base_path}/screenshots/layer-map.json", JSON.stringify(layer_map, indent=2))
TodoWrite(mark_completed: "Generate layer map")
```
**Output**: `layer-map.json`
## Completion
### Todo Update
```javascript
all_todos_completed = true
TodoWrite({todos: all_completed_todos})
```
### Output Message
```
✅ Interactive layer exploration complete!
Configuration:
- URL: {url}
- Max depth: {depth}
- Layers explored: {len(layer_map.layers)}
Capture Summary:
Depth 1 (Page): {depth_1_count} screenshot(s)
Depth 2 (Elements): {depth_2_count} screenshot(s)
Depth 3 (Interactions): {depth_3_count} screenshot(s)
Depth 4 (Embedded): {depth_4_count} screenshot(s)
Depth 5 (Shadow DOM): {depth_5_count} screenshot(s)
Total: {total_captures} captures ({total_size_kb:.1f} KB)
Output Structure:
{base_path}/screenshots/
├── depth-1/
│ └── full-page.png
├── depth-2/
│ ├── navbar.png
│ └── footer.png
├── depth-3/
│ ├── modal-login.png
│ └── dropdown-menu.png
├── depth-4/
│ └── iframe-analytics.png
├── depth-5/
│ └── shadow-button.png
└── layer-map.json
Next: /workflow:ui-design:extract --images "screenshots/**/*.png"
```
## Simple Bash Commands
### Directory Setup
```bash
# Create depth directories
bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
```
### Validation
```bash
# Check MCP
all_resources = ListMcpResourcesTool()
# Count captures per depth
bash(ls $base_path/screenshots/depth-{1..5}/*.png 2>/dev/null | wc -l)
```
### File Operations
```bash
# List all captures
bash(find $base_path/screenshots -name "*.png" -type f)
# Total size
bash(du -sh $base_path/screenshots)
```
## Output Structure
```
{base_path}/screenshots/
├── depth-1/
│ └── full-page.png
├── depth-2/
│ ├── {element}.png
│ └── ...
├── depth-3/
│ ├── {interaction}.png
│ └── ...
├── depth-4/
│ ├── iframe-*.png
│ └── ...
├── depth-5/
│ ├── shadow-*.png
│ └── ...
└── layer-map.json
```
## Depth Level Details
| Depth | Name | Captures | Time | Use Case |
|-------|------|----------|------|----------|
| 1 | Page | Full page | 30s | Quick preview |
| 2 | Elements | Key components | 1-2min | Component library |
| 3 | Interactions | Modals, dropdowns | 2-4min | UI flows |
| 4 | Embedded | Iframes | 3-6min | Complete context |
| 5 | Shadow DOM | Web components | 4-8min | Full coverage |
## Error Handling
### Common Errors
```
ERROR: Chrome DevTools MCP required
→ Install: npm i -g @modelcontextprotocol/server-chrome-devtools
ERROR: Invalid depth
→ Use: 1-5
ERROR: Interaction trigger failed
→ Some modals may be skipped, check layer-map.json
```
### Recovery
- **Partial success**: Lower depth captures preserved
- **Trigger failures**: Interaction layer may be incomplete
- **Iframe restrictions**: Cross-origin iframes skipped
## Quality Checklist
- [ ] All depths up to specified level captured
- [ ] layer-map.json generated with metadata
- [ ] File sizes valid (> 500 bytes)
- [ ] Interaction triggers executed
- [ ] Shadow DOM elements highlighted
## Key Features
- **Depth-controlled**: Progressive capture 1-5 levels
- **Interactive triggers**: Click/hover for hidden layers
- **Iframe support**: Embedded content captured
- **Shadow DOM**: Web component internals
- **Structured output**: Organized by depth
## Integration
**Input**: Single URL + depth level (1-5)
**Output**: Hierarchical screenshots + layer-map.json
**Complements**: `/workflow:ui-design:capture` (multi-URL batch)
**Next**: `/workflow:ui-design:extract` for design analysis

363
.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md Normal file
View File

@@ -0,0 +1,363 @@
---
name: generate
description: Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation
argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
---
# Generate UI Prototypes (/workflow:ui-design:generate)
## Overview
Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
**Strategy**: Pure Assembly
- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available)
- **Process**: Combine structure (DOM) with style (tokens)
- **Output**: Complete HTML/CSS prototypes
- **No Design Logic**: All layout and style decisions already made
- **Automatic Image Reference**: If source images exist in layout templates, they're automatically used for visual context
**Prerequisite Commands**:
- `/workflow:ui-design:style-extract` → Complete design systems (design-tokens.json + style-guide.md)
- `/workflow:ui-design:layout-extract` → Layout structure
## Phase 1: Setup & Validation
### Step 1: Resolve Base Path & Parse Configuration
```bash
# Determine working directory
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# Get style count
bash(ls {base_path}/style-extraction/style-* -d | wc -l)
# Image reference auto-detected from layout template source_image_path
```
### Step 2: Load Layout Templates
```bash
# Check layout templates exist
bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
# Load layout templates
Read({base_path}/layout-extraction/layout-templates.json)
# Extract: targets, layout_variants count, device_type, template structures
```
**Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
### Step 3: Validate Design Tokens
```bash
# Check design tokens exist for all styles
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
# For each style variant: Load design tokens
Read({base_path}/style-extraction/style-{id}/design-tokens.json)
```
**Output**: `design_tokens[]` for all style variants
### Step 4: Load Animation Tokens (Optional)
```bash
# Check if animation tokens exist
bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
# Load animation tokens if available
IF exists({base_path}/animation-extraction/animation-tokens.json):
animation_tokens = Read({base_path}/animation-extraction/animation-tokens.json)
has_animations = true
ELSE:
has_animations = false
```
**Output**: `animation_tokens` (optional), `has_animations` flag
## Phase 2: Assembly (Agent)
**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
### Step 1: Launch Assembly Tasks
```bash
bash(mkdir -p {base_path}/prototypes)
```
For each `target × style_id × layout_id`:
```javascript
Task(ui-design-agent): `
[LAYOUT_STYLE_ASSEMBLY]
🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
BASE_PATH: {base_path}
## Inputs (READ ONLY - NO DESIGN DECISIONS)
1. Layout Template:
Read("{base_path}/layout-extraction/layout-templates.json")
Find template where: target={target} AND variant_id="layout-{layout_id}"
Extract: dom_structure, css_layout_rules, device_type, source_image_path
2. Design Tokens:
Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
Extract: ALL token values including:
* colors, typography (with combinations), spacing, opacity
* border_radius, shadows, breakpoints
* component_styles (button, card, input variants)
Note: typography.combinations, opacity, and component_styles fields contain preset configurations using var() references
3. Animation Tokens (OPTIONAL):
IF exists("{base_path}/animation-extraction/animation-tokens.json"):
Read("{base_path}/animation-extraction/animation-tokens.json")
Extract: duration, easing, transitions, keyframes, interactions
has_animations = true
ELSE:
has_animations = false
4. Reference Image (AUTO-DETECTED):
IF template.source_image_path exists:
Read(template.source_image_path)
Purpose: Additional visual context for better placeholder content generation
Note: This is for reference only - layout and style decisions already made
ELSE:
Use generic placeholder content
## Assembly Process
1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
- Recursively build from template.dom_structure
- Add: <!DOCTYPE html>, <head>, <meta viewport>
- CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
- Inject placeholder content:
* Default: Use Lorem ipsum, generic sample data
* If reference image available: Generate more contextually appropriate placeholders
(e.g., realistic headings, meaningful text snippets that match the visual context)
- Preserve all attributes from dom_structure
2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
- Start with template.css_layout_rules
- Replace ALL var(--*) with actual token values from design-tokens.json
Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
- Add visual styling using design tokens:
* Colors: tokens.colors.*
* Typography: tokens.typography.* (including combinations)
* Opacity: tokens.opacity.*
* Shadows: tokens.shadows.*
* Border radius: tokens.border_radius.*
- IF tokens.component_styles exists: Add component style classes
* Generate classes for button variants (.btn-primary, .btn-secondary)
* Generate classes for card variants (.card-default, .card-interactive)
* Generate classes for input variants (.input-default, .input-focus, .input-error)
* Use var() references that resolve to actual token values
- IF tokens.typography.combinations exists: Add typography preset classes
* Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
* Use var() references for family, size, weight, line-height, letter-spacing
- IF has_animations == true: Inject animation tokens
* Add CSS Custom Properties for animations at :root level:
--duration-instant, --duration-fast, --duration-normal, etc.
--easing-linear, --easing-ease-out, etc.
* Add @keyframes rules from animation_tokens.keyframes
* Add interaction classes (.button-hover, .card-hover) from animation_tokens.interactions
* Add utility classes (.transition-color, .transition-transform) from animation_tokens.transitions
* Include prefers-reduced-motion media query for accessibility
- Device-optimized for template.device_type
## Assembly Rules
- ✅ Pure assembly: Combine existing structure + existing style
- ❌ NO layout design decisions (structure pre-defined)
- ❌ NO style design decisions (tokens pre-defined)
- ✅ Replace var() with actual values
- ✅ Add placeholder content only
- Write files IMMEDIATELY
- CSS filename MUST match HTML <link href="...">
`
```
### Step 2: Verify Generated Files
```bash
# Count expected vs found
bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
# Validate samples
Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
```
**Output**: `S × L × T × 2` files verified
## Phase 3: Generate Preview Files
### Step 1: Run Preview Generation Script
```bash
bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
```
**Script generates**:
- `compare.html` (interactive matrix)
- `index.html` (navigation)
- `PREVIEW.md` (instructions)
### Step 2: Verify Preview Files
```bash
bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
```
**Output**: 3 preview files
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
{content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
{content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
{content: "Verify files", status: "completed", activeForm: "Validating output"},
{content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
]});
```
### Output Message
```
✅ UI prototype assembly complete!
Configuration:
- Style Variants: {style_variants}
- Layout Variants: {layout_variants} (from layout-templates.json)
- Device Type: {device_type}
- Targets: {targets}
- Total Prototypes: {S × L × T}
- Image Reference: Auto-detected (uses source images when available in layout templates)
Assembly Process:
- Pure assembly: Combined pre-extracted layouts + design tokens
- No design decisions: All structure and style pre-defined
- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations
Quality:
- Structure: From layout-extract (DOM, CSS layout rules)
- Style: From style-extract (design tokens)
- CSS: Token values directly applied (var() replaced)
- Device-optimized: Layouts match device_type from templates
Generated Files:
{base_path}/prototypes/
├── _templates/
│ └── layout-templates.json (input, pre-extracted)
├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
├── {target}-style-{s}-layout-{l}.css
├── compare.html (interactive matrix)
├── index.html (navigation)
└── PREVIEW.md (instructions)
Preview:
1. Open compare.html (recommended)
2. Open index.html
3. Read PREVIEW.md
Next: /workflow:ui-design:update
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
# Count style variants
bash(ls {base_path}/style-extraction/style-* -d | wc -l)
```
### Validation Commands
```bash
# Check layout templates exist
bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
# Check design tokens exist
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
# Count generated files
bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
# Verify preview
bash(test -f {base_path}/prototypes/compare.html && echo "exists")
```
### File Operations
```bash
# Create directories
bash(mkdir -p {base_path}/prototypes)
# Run preview script
bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
```
## Output Structure
```
{base_path}/
├── layout-extraction/
│ └── layout-templates.json # Input (from layout-extract)
├── style-extraction/
│ └── style-{s}/
│ ├── design-tokens.json # Input (from style-extract)
│ └── style-guide.md
└── prototypes/
├── {target}-style-{s}-layout-{l}.html # Assembled prototypes
├── {target}-style-{s}-layout-{l}.css
├── compare.html
├── index.html
└── PREVIEW.md
```
## Error Handling
### Common Errors
```
ERROR: Layout templates not found
→ Run /workflow:ui-design:layout-extract first
ERROR: Design tokens not found
→ Run /workflow:ui-design:style-extract first
ERROR: Agent assembly failed
→ Check inputs exist, validate JSON structure
ERROR: Script permission denied
→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
```
### Recovery Strategies
- **Partial success**: Keep successful assembly combinations
- **Invalid template structure**: Validate layout-templates.json
- **Invalid tokens**: Validate design-tokens.json structure
## Quality Checklist
- [ ] CSS uses direct token values (var() replaced)
- [ ] HTML structure matches layout template exactly
- [ ] Semantic HTML5 structure preserved
- [ ] ARIA attributes from template present
- [ ] Device-specific optimizations applied
- [ ] All token references resolved
- [ ] compare.html works
## Key Features
- **Pure Assembly**: No design decisions, only combination
- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
- **Token Resolution**: var() placeholders replaced with actual values
- **Pre-validated**: Inputs already validated by extract/consolidate
- **Efficient**: Simple assembly vs complex generation
- **Production-Ready**: Semantic, accessible, token-driven
## Integration
**Prerequisites**:
- `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
- `/workflow:ui-design:layout-extract` → `layout-templates.json`
**Input**: `layout-templates.json` + `design-tokens.json`
**Output**: S×L×T prototypes for `/workflow:ui-design:update`
**Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`

682
.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md Normal file
View File

@@ -0,0 +1,682 @@
---
name: imitate-auto
description: High-speed multi-page UI replication with batch screenshot capture and design token extraction
argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt "<desc>"]
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
---
# UI Design Imitate-Auto Workflow Command
## Overview & Execution Model
**Fully autonomous replication orchestrator**: Efficiently replicate multiple web pages through sequential execution from screenshot capture to design integration.
**Dual Capture Strategy**: Supports two capture modes for different use cases:
- **Batch Mode** (default): Fast multi-URL screenshot capture via `/workflow:ui-design:capture`
- **Deep Mode**: Interactive layer exploration for single URL via `/workflow:ui-design:explore-layers`
**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
1. User triggers: `/workflow:ui-design:imitate-auto --url-map "..."`
2. Phase 0: Initialize and parse parameters
3. Phase 1: Screenshot capture (batch or deep mode) → **WAIT for completion** → Auto-continues
4. Phase 2: Style extraction (complete design systems) → **WAIT for completion** → Auto-continues
5. Phase 2.3: Animation extraction (CSS auto mode) → **WAIT for completion** → Auto-continues
6. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
7. Phase 3: Batch UI assembly → **WAIT for completion** → Auto-continues
8. Phase 4: Design system integration → Reports completion
**Phase Transition Mechanism**:
- `SlashCommand` is BLOCKING - execution pauses until completion
- Upon each phase completion: Automatically process output and execute next phase
- No user interaction required after initial parameter parsing
**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 5.
## Core Rules
1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
2. **No Preliminary Validation**: Sub-commands handle their own validation
3. **Parse & Pass**: Extract data from each output for next phase
4. **Track Progress**: Update TodoWrite after each phase
5. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 5.
## Parameter Requirements
**Required Parameters**:
- `--url-map "<map>"`: Target page mapping
- Format: `"target1:url1, target2:url2, ..."`
- Example: `"home:https://linear.app, pricing:https://linear.app/pricing"`
- First target serves as primary style source
**Optional Parameters**:
- `--capture-mode <batch|deep>` (Optional, default: batch): Screenshot capture strategy
- `batch` (default): Multi-URL fast batch capture via `/workflow:ui-design:capture`
- `deep`: Single-URL interactive depth exploration via `/workflow:ui-design:explore-layers`
- **Note**: `deep` mode only uses first URL from url-map
- `--depth <1-5>` (Optional, default: 3): Capture depth for deep mode
- `1`: Page level (full-page screenshot)
- `2`: Element level (+ key components)
- `3`: Interaction level (+ modals, dropdowns)
- `4`: Embedded level (+ iframes)
- `5`: Shadow DOM (+ web components)
- **Only applies when** `--capture-mode deep`
- `--session <id>` (Optional): Workflow session ID
- Integrate into existing session (`.workflow/WFS-{session}/`)
- Enable automatic design system integration (Phase 5)
- If not provided: standalone mode (`.workflow/.design/`)
- `--prompt "<desc>"` (Optional): Style extraction guidance
- Influences extract command analysis focus
- Example: `"Focus on dark mode"`, `"Emphasize minimalist design"`
- **Note**: Design systems are now production-ready by default (no separate consolidate step)
## Execution Modes
**Capture Modes**:
- **Batch Mode** (default): Multi-URL screenshot capture for fast replication
- Uses `/workflow:ui-design:capture` for parallel screenshot capture
- Optimized for replicating multiple pages efficiently
- **Deep Mode**: Single-URL layer exploration for detailed analysis
- Uses `/workflow:ui-design:explore-layers` for interactive depth traversal
- Captures page layers at different depths (1-5)
- Only processes first URL from url-map
**Token Processing**:
- **Direct Generation**: Complete design systems generated in style-extract phase
- Production-ready design-tokens.json with WCAG compliance
- Complete style-guide.md documentation
- No separate consolidation step required (~30-60s faster)
**Session Integration**:
- `--session` flag determines session integration or standalone execution
- Integrated: Design system automatically added to session artifacts
- Standalone: Output in `.workflow/.design/{run_id}/`
## 6-Phase Execution
### Phase 0: Initialization and Target Parsing
```bash
# Generate run ID
run_id = "run-$(date +%Y%m%d-%H%M%S)"
# Determine base path and session mode
IF --session:
session_id = {provided_session}
base_path = ".workflow/WFS-{session_id}/design-{run_id}"
session_mode = "integrated"
ELSE:
session_id = null
base_path = ".workflow/.design/{run_id}"
session_mode = "standalone"
# Create base directory
Bash(mkdir -p "{base_path}")
# Parse url-map
url_map_string = {--url-map}
VALIDATE: url_map_string is not empty, "--url-map parameter is required"
# Parse target:url pairs
url_map = {} # {target_name: url}
target_names = []
FOR pair IN split(url_map_string, ","):
pair = pair.strip()
IF ":" NOT IN pair:
ERROR: "Invalid url-map format: '{pair}'"
ERROR: "Expected format: 'target:url'"
ERROR: "Example: 'home:https://example.com, pricing:https://example.com/pricing'"
EXIT 1
target, url = pair.split(":", 1)
target = target.strip().lower().replace(" ", "-")
url = url.strip()
url_map[target] = url
target_names.append(target)
VALIDATE: len(target_names) > 0, "url-map must contain at least one target:url pair"
primary_target = target_names[0] # First target as primary style source
# Parse capture mode
capture_mode = --capture-mode OR "batch"
depth = int(--depth OR 3)
# Validate capture mode
IF capture_mode NOT IN ["batch", "deep"]:
ERROR: "Invalid --capture-mode: {capture_mode}"
ERROR: "Valid options: batch, deep"
EXIT 1
# Validate depth (only for deep mode)
IF capture_mode == "deep":
IF depth NOT IN [1, 2, 3, 4, 5]:
ERROR: "Invalid --depth: {depth}"
ERROR: "Valid range: 1-5"
EXIT 1
# Warn if multiple URLs in deep mode
IF len(target_names) > 1:
WARN: "⚠️ Deep mode only uses first URL: '{primary_target}'"
WARN: " Other URLs will be ignored: {', '.join(target_names[1:])}"
WARN: " For multi-URL, use --capture-mode batch"
# Write metadata
metadata = {
"workflow": "imitate-auto",
"run_id": run_id,
"session_id": session_id,
"timestamp": current_timestamp(),
"parameters": {
"url_map": url_map,
"capture_mode": capture_mode,
"depth": depth IF capture_mode == "deep" ELSE null,
"prompt": --prompt OR null
},
"targets": target_names,
"status": "in_progress"
}
Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
# Initialize TodoWrite
TodoWrite({todos: [
{content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
{content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "pending", activeForm: "Capturing screenshots"},
{content: "Extract style (complete design systems)", status: "pending", activeForm: "Extracting style"},
{content: "Extract animation (CSS auto mode)", status: "pending", activeForm: "Extracting animation"},
{content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
{content: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
{content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
]})
```
### Phase 1: Screenshot Capture (Dual Mode)
```bash
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🚀 Phase 1: Screenshot Capture"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
IF capture_mode == "batch":
# Mode A: Batch Multi-URL Capture
url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
TRY:
SlashCommand(capture_command)
CATCH error:
ERROR: "Batch capture failed: {error}"
ERROR: "Cannot proceed without screenshots"
EXIT 1
# Verify batch capture results
screenshot_metadata_path = "{base_path}/screenshots/capture-metadata.json"
IF NOT exists(screenshot_metadata_path):
ERROR: "capture command did not generate metadata file"
ERROR: "Expected: {screenshot_metadata_path}"
EXIT 1
screenshot_metadata = Read(screenshot_metadata_path)
captured_count = screenshot_metadata.total_captured
total_requested = screenshot_metadata.total_requested
missing_count = total_requested - captured_count
IF missing_count > 0:
missing_targets = [s.target for s in screenshot_metadata.screenshots if not s.captured]
WARN: "⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
IF captured_count == 0:
ERROR: "No screenshots captured - cannot proceed"
EXIT 1
ELSE: # capture_mode == "deep"
# Mode B: Deep Interactive Layer Exploration
primary_url = url_map[primary_target]
explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
TRY:
SlashCommand(explore_command)
CATCH error:
ERROR: "Deep exploration failed: {error}"
ERROR: "Cannot proceed without screenshots"
EXIT 1
# Verify deep exploration results
layer_map_path = "{base_path}/screenshots/layer-map.json"
IF NOT exists(layer_map_path):
ERROR: "explore-layers did not generate layer-map.json"
ERROR: "Expected: {layer_map_path}"
EXIT 1
layer_map = Read(layer_map_path)
captured_count = layer_map.summary.total_captures
total_requested = captured_count # For consistency with batch mode
TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} targets)" IF capture_mode == "batch" ELSE f"Deep exploration (depth {depth})",
mark_in_progress: "Extract style (visual tokens)")
```
### Phase 2: Style Extraction (Visual Tokens)
```bash
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🚀 Phase 2: Style Extraction"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Use all screenshots as input to extract single design system
IF capture_mode == "batch":
images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
ELSE: # deep mode
images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"
# Build extraction prompt
IF --prompt:
user_guidance = {--prompt}
extraction_prompt = f"Extract visual style tokens from '{primary_target}'. User guidance: {user_guidance}"
ELSE:
extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
# Build url-map string for style-extract (enables computed styles extraction)
url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()])
# Call style-extract command (imitate mode, automatically uses single variant)
# Pass --urls to enable auto-trigger of computed styles extraction
extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate"
TRY:
SlashCommand(extract_command)
CATCH error:
ERROR: "Style extraction failed: {error}"
ERROR: "Cannot proceed without visual tokens"
EXIT 1
# Verify extraction results
design_tokens_path = "{base_path}/style-extraction/style-1/design-tokens.json"
style_guide_path = "{base_path}/style-extraction/style-1/style-guide.md"
IF NOT exists(design_tokens_path) OR NOT exists(style_guide_path):
ERROR: "style-extract did not generate required files"
EXIT 1
TodoWrite(mark_completed: "Extract style (complete design systems)",
mark_in_progress: "Extract animation (CSS auto mode)")
```
### Phase 2.3: Animation Extraction (CSS Auto Mode)
```bash
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🚀 Phase 2.3: Animation Extraction"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Build URL list for animation-extract (auto mode for CSS extraction)
url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()])
# Call animation-extract command (auto mode for CSS animation extraction)
# Pass --urls to auto-trigger CSS animation/transition extraction via Chrome DevTools
animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto"
TRY:
SlashCommand(animation_extract_command)
CATCH error:
ERROR: "Animation extraction failed: {error}"
ERROR: "Cannot proceed without animation tokens"
EXIT 1
# Verify animation extraction results
animation_tokens_path = "{base_path}/animation-extraction/animation-tokens.json"
animation_guide_path = "{base_path}/animation-extraction/animation-guide.md"
IF NOT exists(animation_tokens_path) OR NOT exists(animation_guide_path):
ERROR: "animation-extract did not generate required files"
EXIT 1
TodoWrite(mark_completed: "Extract animation (CSS auto mode)",
mark_in_progress: "Extract layout (structure templates)")
```
### Phase 2.5: Layout Extraction (Structure Templates)
```bash
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🚀 Phase 2.5: Layout Extraction"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Build URL map for layout-extract
url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
# Call layout-extract command (imitate mode for structure replication)
# Pass --urls to enable auto-trigger of DOM structure extraction
layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate"
TRY:
SlashCommand(layout_extract_command)
CATCH error:
ERROR: "Layout extraction failed: {error}"
ERROR: "Cannot proceed without layout templates"
EXIT 1
# Verify layout extraction results
layout_templates_path = "{base_path}/layout-extraction/layout-templates.json"
IF NOT exists(layout_templates_path):
ERROR: "layout-extract did not generate layout-templates.json"
EXIT 1
TodoWrite(mark_completed: "Extract layout (structure templates)",
mark_in_progress: f"Assemble UI for {len(target_names)} targets")
```
### Phase 3: Batch UI Assembly
```bash
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🚀 Phase 3: UI Assembly"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
# Call generate command (pure assembler - combines layout templates + design tokens)
generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"
TRY:
SlashCommand(generate_command)
CATCH error:
ERROR: "UI assembly failed: {error}"
ERROR: "Layout templates or design tokens may be invalid"
EXIT 1
# Verify assembly results
prototypes_dir = "{base_path}/prototypes"
generated_html_files = Glob(f"{prototypes_dir}/*-style-1-layout-1.html")
generated_count = len(generated_html_files)
IF generated_count < len(target_names):
WARN: "⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
mark_in_progress: session_id ? "Integrate design system" : "Standalone completion")
```
### Phase 4: Design System Integration
```bash
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
REPORT: "🚀 Phase 4: Design System Integration"
REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
IF session_id:
update_command = f"/workflow:ui-design:update --session {session_id}"
TRY:
SlashCommand(update_command)
CATCH error:
WARN: "⚠️ Design system integration failed: {error}"
WARN: "Prototypes available at {base_path}/prototypes/"
# Update metadata
metadata = Read("{base_path}/.run-metadata.json")
metadata.status = "completed"
metadata.completion_time = current_timestamp()
metadata.outputs = {
"screenshots": f"{base_path}/screenshots/",
"style_system": f"{base_path}/style-extraction/style-1/",
"prototypes": f"{base_path}/prototypes/",
"captured_count": captured_count,
"generated_count": generated_count
}
Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
TodoWrite(mark_completed: session_id ? "Integrate design system" : "Standalone completion")
# Mark all phases complete
TodoWrite({todos: [
{content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
{content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "completed", activeForm: "Capturing"},
{content: "Extract style (complete design systems)", status: "completed", activeForm: "Extracting"},
{content: "Extract animation (CSS auto mode)", status: "completed", activeForm: "Extracting animation"},
{content: "Extract layout (structure templates)", status: "completed", activeForm: "Extracting layout"},
{content: f"Assemble UI for {len(target_names)} targets", status: "completed", activeForm: "Assembling"},
{content: session_id ? "Integrate design system" : "Standalone completion", status: "completed", activeForm: "Completing"}
]})
```
### Phase 6: Completion Report
**Completion Message**:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ UI Design Imitate-Auto Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━ 📊 Workflow Summary ━━━
Mode: {capture_mode == "batch" ? "Batch Multi-Page Replication" : f"Deep Interactive Exploration (depth {depth})"}
Session: {session_id or "standalone"}
Run ID: {run_id}
Phase 1 - Screenshot Capture: ✅ {IF capture_mode == "batch": f"{captured_count}/{total_requested} screenshots" ELSE: f"{captured_count} screenshots ({total_layers} layers)"}
{IF capture_mode == "batch" AND captured_count < total_requested: f"⚠️ {total_requested - captured_count} missing" ELSE: "All targets captured"}
Phase 2 - Style Extraction: ✅ Production-ready design systems
Output: style-extraction/style-1/ (design-tokens.json + style-guide.md)
Quality: WCAG AA compliant, OKLCH colors
Phase 2.3 - Animation Extraction: ✅ CSS animations and transitions
Output: animation-extraction/ (animation-tokens.json + animation-guide.md)
Method: Auto-extracted from live URLs via Chrome DevTools
Phase 2.5 - Layout Extraction: ✅ Structure templates
Templates: {template_count} layout structures
Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
Targets: {', '.join(target_names)}
Configuration: 1 style × 1 layout × {generated_count} pages
Phase 4 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
━━━ 📂 Output Structure ━━━
{base_path}/
├── screenshots/ # {captured_count} screenshots
{IF capture_mode == "batch":
│ ├── {target1}.png
│ ├── {target2}.png
│ └── capture-metadata.json
ELSE:
│ ├── depth-1/
│ │ └── full-page.png
│ ├── depth-2/
│ │ └── {elements}.png
│ ├── depth-{depth}/
│ │ └── {layers}.png
│ └── layer-map.json
}
├── style-extraction/ # Production-ready design systems
│ └── style-1/
│ ├── design-tokens.json
│ └── style-guide.md
├── animation-extraction/ # CSS animations and transitions
│ ├── animation-tokens.json
│ └── animation-guide.md
├── layout-extraction/ # Structure templates
│ └── layout-templates.json
└── prototypes/ # {generated_count} HTML/CSS files
├── {target1}-style-1-layout-1.html + .css
├── {target2}-style-1-layout-1.html + .css
├── compare.html # Interactive preview
└── index.html # Quick navigation
━━━ ⚡ Performance ━━━
Total workflow time: ~{estimate_total_time()} minutes
Screenshot capture: ~{capture_time}
Style extraction: ~{extract_time}
Token processing: ~{token_processing_time}
UI generation: ~{generate_time}
━━━ 🌐 Next Steps ━━━
1. Preview prototypes:
• Interactive matrix: Open {base_path}/prototypes/compare.html
• Quick navigation: Open {base_path}/prototypes/index.html
{IF session_id:
2. Create implementation tasks:
/workflow:plan --session {session_id}
3. Generate tests (if needed):
/workflow:test-gen {session_id}
ELSE:
2. To integrate into a workflow session:
• Create session: /workflow:session:start
• Copy design-tokens.json to session artifacts
3. Explore prototypes in {base_path}/prototypes/ directory
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
## TodoWrite Pattern
```javascript
// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution
TodoWrite({todos: [
{content: "Initialize and parse url-map", status: "in_progress", activeForm: "Initializing"},
{content: "Batch screenshot capture", status: "pending", activeForm: "Capturing screenshots"},
{content: "Extract style (complete design systems)", status: "pending", activeForm: "Extracting style"},
{content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
{content: "Assemble UI for all targets", status: "pending", activeForm: "Assembling UI"},
{content: "Integrate design system", status: "pending", activeForm: "Integrating"}
]})
// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
// 1. SlashCommand blocks and returns when phase is complete
// 2. Update current phase: status → "completed"
// 3. Update next phase: status → "in_progress"
// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
// This ensures continuous workflow tracking and prevents premature stopping
```
## Error Handling
### Pre-execution Checks
- **url-map format validation**: Clear error message with format example
- **Empty url-map**: Error and exit
- **Invalid target names**: Regex validation with suggestions
### Phase-Specific Errors
- **Screenshot capture failure (Phase 1)**:
- If total_captured == 0: Terminate workflow
- If partial failure: Warn but continue with available screenshots
- **Style extraction failure (Phase 2)**:
- If extract fails: Terminate with clear error
- If style-cards.json missing: Terminate with debugging info
- **Token processing failure (Phase 3)**:
- Consolidate mode: Terminate if consolidate fails
- Fast mode: Validate proposed_tokens exist before copying
- **UI generation failure (Phase 4)**:
- If generate fails: Terminate with error
- If generated_count < target_count: Warn but proceed
- **Integration failure (Phase 5)**:
- Non-blocking: Warn but don't terminate
- Prototypes already available
### Recovery Strategies
- **Partial screenshot failure**: Continue with available screenshots, list missing in warning
- **Generate failure**: Report specific target failures, user can re-generate individually
- **Integration failure**: Prototypes still usable, can integrate manually
## Key Features
- **🚀 Dual Capture**: Batch mode for speed, deep mode for detail
- **⚡ Production-Ready**: Complete design systems generated directly (~30-60s faster)
- **🎨 High-Fidelity**: Single unified design system from primary target
- **📦 Autonomous**: No user intervention required between phases
- **🔄 Reproducible**: Deterministic flow with isolated run directories
- **🎯 Flexible**: Standalone or session-integrated modes
## Examples
### 1. Basic Multi-Page Replication
```bash
/workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
# Result: 2 prototypes with fast-track tokens
```
### 2. Session Integration
```bash
/workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing"
# Result: 1 prototype with production-ready design system, integrated into session
```
### 3. Deep Exploration Mode
```bash
/workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
# Result: Interactive layer capture + prototype
```
### 4. Guided Style Extraction
```bash
/workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
# Result: 2 prototypes with minimalist style focus
```
## Integration Points
- **Input**: `--url-map` (multiple target:url pairs) + optional `--capture-mode`, `--depth`, `--session`, `--prompt`
- **Output**: Complete design system in `{base_path}/` (screenshots, style-extraction, layout-extraction, prototypes)
- **Sub-commands Called**:
1. Phase 1 (conditional):
- `--capture-mode batch`: `/workflow:ui-design:capture` (multi-URL batch)
- `--capture-mode deep`: `/workflow:ui-design:explore-layers` (single-URL depth exploration)
2. `/workflow:ui-design:style-extract` (Phase 2 - complete design systems)
3. `/workflow:ui-design:animation-extract` (Phase 2.3 - CSS animations and transitions)
4. `/workflow:ui-design:layout-extract` (Phase 2.5 - structure templates)
5. `/workflow:ui-design:generate` (Phase 3 - pure assembly)
6. `/workflow:ui-design:update` (Phase 4, if --session)
## Completion Output
```
✅ UI Design Imitate-Auto Workflow Complete!
Mode: {capture_mode} | Session: {session_id or "standalone"}
Run ID: {run_id}
Phase 1 - Screenshot Capture: ✅ {captured_count} screenshots
Phase 2 - Style Extraction: ✅ Production-ready design systems
Phase 2.5 - Layout Extraction: ✅ Structure templates
Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
Phase 4 - Integration: {IF session_id: "✅ Integrated" ELSE: "⏭️ Standalone"}
Design Quality:
✅ High-Fidelity Replication: Accurate style from primary target
✅ Token-Driven Styling: 100% var() usage
✅ Production-Ready: WCAG AA compliant, OKLCH colors
📂 {base_path}/
├── screenshots/ # {captured_count} screenshots
├── style-extraction/style-1/ # Production-ready design system
├── layout-extraction/ # Structure templates
└── prototypes/ # {generated_count} HTML/CSS files
🌐 Preview: {base_path}/prototypes/compare.html
- Interactive preview
- Side-by-side comparison
- {generated_count} replicated pages
Next: [/workflow:execute] OR [Open compare.html → /workflow:plan]
```

746
.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md Normal file
View File

@@ -0,0 +1,746 @@
---
name: layout-extract
description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis
argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
---
# Layout Extraction Command
## Overview
Extract structural layout information from reference images, URLs, or text prompts using AI analysis. This command separates the "scaffolding" (HTML structure and CSS layout) from the "paint" (visual tokens handled by `style-extract`).
**Strategy**: AI-Driven Structural Analysis
- **Agent-Powered**: Uses `ui-design-agent` for deep structural analysis
- **Dual-Mode**:
- `imitate`: High-fidelity replication of single layout structure
- `explore`: Multiple structurally distinct layout variations
- **Single Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
- **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
- **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
## Phase 0: Setup & Input Validation
### Step 1: Detect Input, Mode & Targets
```bash
# Detect input source
# Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
# Parse URLs if provided (format: "target:url,target:url,...")
IF --urls:
url_list = []
FOR pair IN split(--urls, ","):
IF ":" IN pair:
target, url = pair.split(":", 1)
url_list.append({target: target.strip(), url: url.strip()})
ELSE:
# Single URL without target
url_list.append({target: "page", url: pair.strip()})
has_urls = true
ELSE:
has_urls = false
url_list = []
# Determine extraction mode
extraction_mode = --mode OR "imitate" # "imitate" or "explore"
# Set variants count based on mode
IF extraction_mode == "imitate":
variants_count = 1 # Force single variant (ignore --variants)
ELSE IF extraction_mode == "explore":
variants_count = --variants OR 3 # Default to 3
VALIDATE: 1 <= variants_count <= 5
# Resolve targets
# Priority: --targets → url_list targets → prompt analysis → default ["page"]
IF --targets:
targets = split(--targets, ",")
ELSE IF has_urls:
targets = [url_info.target for url_info in url_list]
ELSE IF --prompt:
targets = extract_from_prompt(--prompt)
ELSE:
targets = ["page"]
# Resolve device type
device_type = --device-type OR "responsive" # desktop|mobile|tablet|responsive
# Determine base path
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# OR use --base-path / --session parameters
```
### Step 2: Load Inputs & Create Directories
```bash
# For image mode
bash(ls {images_pattern}) # Expand glob pattern
Read({image_path}) # Load each image
# For URL mode
# Parse URL list format: "target:url,target:url"
# Validate URLs are accessible
# For text mode
# Validate --prompt is non-empty
# Create output directory
bash(mkdir -p {base_path}/layout-extraction)
```
### Step 2.5: Extract DOM Structure (URL Mode - Auto-Trigger)
```bash
# AUTO-TRIGGER: If URLs are available (from --urls parameter), automatically extract real DOM structure
# This provides accurate layout data to supplement visual analysis
# Check if URLs provided via --urls parameter
IF --urls AND url_list:
REPORT: "🔍 Auto-triggering URL mode: Extracting DOM structure"
bash(mkdir -p {base_path}/.intermediates/layout-analysis)
# For each URL in url_list:
FOR url_info IN url_list:
target = url_info.target
url = url_info.url
IF mcp_chrome_devtools_available:
REPORT: " Processing: {target} ({url})"
# Read extraction script
script_content = Read(~/.claude/scripts/extract-layout-structure.js)
# Open page in Chrome DevTools
mcp__chrome-devtools__navigate_page(url=url)
# Execute layout extraction script
result = mcp__chrome-devtools__evaluate_script(function=script_content)
# Save DOM structure for this target (intermediate file)
Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
REPORT: " ✅ DOM structure extracted for '{target}'"
ELSE:
REPORT: " ⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
BREAK
dom_structure_available = mcp_chrome_devtools_available
ELSE:
dom_structure_available = false
```
**Extraction Script Reference**: `~/.claude/scripts/extract-layout-structure.js`
**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
**Script returns**:
- `metadata`: Extraction timestamp, URL, method, version
- `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
- `structure`: Hierarchical DOM tree with layout properties
- `exploration`: (Optional) Progressive exploration results when standard selectors fail
**Benefits**:
- ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
- ✅ Accurate element bounds (x, y, width, height)
- ✅ Structural hierarchy with depth control
- ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
- ✅ Progressive exploration: Auto-discovers missing selectors
**Progressive Exploration Strategy** (v2.2.0+):
When script finds <3 main containers, it automatically:
1. **Scans** all large visible containers (≥500×300px)
2. **Extracts** class patterns matching: `main|content|wrapper|container|page|layout|app`
3. **Suggests** new selectors to add to script
4. **Returns** exploration data in `result.exploration`:
```json
{
"triggered": true,
"discoveredCandidates": [{classes, bounds, display}],
"suggestedSelectors": [".wrapper", ".page-index"],
"recommendation": ".wrapper, .page-index, .app-container"
}
```
**Using Exploration Results**:
```javascript
// After extraction, check for suggestions
IF result.exploration?.triggered:
REPORT: result.exploration.warning
REPORT: "Suggested selectors: " + result.exploration.recommendation
// Update script by adding to commonClassSelectors array
// Then re-run extraction for better coverage
```
**Selector Update Workflow**:
1. Run extraction on unfamiliar site
2. Check `result.exploration.suggestedSelectors`
3. Add relevant selectors to script's `commonClassSelectors`
4. Re-run extraction → improved container detection
### Step 3: Memory Check
```bash
# 1. Check if inputs cached in session memory
IF session_has_inputs: SKIP Step 2 file reading
# 2. Check if output already exists
bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
IF exists: SKIP to completion
```
---
**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
## Phase 1: Layout Concept Generation (Explore Mode Only)
### Step 1: Check Extraction Mode
```bash
# extraction_mode == "imitate" → skip this phase
# extraction_mode == "explore" → execute this phase
```
**If imitate mode**: Skip to Phase 2
### Step 2: Gather Layout Inspiration (Explore Mode)
```bash
bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
# For each target: Research via MCP
# mcp__exa__web_search_exa(query="{target} layout patterns {device_type}", numResults=5)
# Write inspiration file
Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, inspiration_content)
```
### Step 3: Generate Layout Concept Options (Agent Task 1)
**Executor**: `Task(ui-design-agent)`
Launch agent to generate `variants_count` layout concept options for each target:
```javascript
Task(ui-design-agent): `
[LAYOUT_CONCEPT_GENERATION_TASK]
Generate {variants_count} structurally distinct layout concepts for each target
SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
TARGETS: {targets} | DEVICE_TYPE: {device_type}
## Input Analysis
- Targets: {targets.join(", ")}
- Device type: {device_type}
- Layout inspiration: Read inspirations from {base_path}/.intermediates/layout-analysis/inspirations/
- Visual references: {loaded_images if available}
${dom_structure_available ? "- DOM Structure: Read from .intermediates/layout-analysis/dom-structure-*.json" : ""}
## Analysis Rules
- For EACH target, generate {variants_count} structurally DIFFERENT layout concepts
- Concepts must differ in: grid structure, component arrangement, visual hierarchy
- Each concept should have distinct navigation pattern, content flow, and responsive behavior
## Generate for EACH Target
For target in {targets}:
For concept_index in 1..{variants_count}:
1. **Concept Definition**:
- concept_name (descriptive, e.g., "Classic Three-Column Holy Grail")
- design_philosophy (1-2 sentences explaining the structural approach)
- layout_pattern (e.g., "grid-3col", "flex-row", "single-column", "asymmetric-grid")
- key_components (array of main layout regions)
- structural_features (list of distinguishing characteristics)
2. **Wireframe Preview** (simple text representation):
- ascii_art (simple ASCII box diagram showing layout structure)
- Example:
┌─────────────────┐
│ HEADER │
├──┬─────────┬────┤
│ L│ MAIN │ R │
└──┴─────────┴────┘
## Output
Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json
Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)
CRITICAL: Use Write() tool immediately after generating complete JSON
`
```
### Step 4: Verify Options File Created
```bash
bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")
# Quick validation
bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep -q "layout_concepts" && echo "valid")
```
**Output**: `analysis-options.json` with layout concept options for all targets
---
## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
**Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates
### Step 1: Load and Present Options
```bash
# Read options file
options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
# Parse layout concepts
layout_concepts = options.layout_concepts
```
### Step 2: Present Options to User (Per Target)
For each target, present layout concept options and capture selection:
```
📋 Layout Concept Options for Target: {target}
We've generated {variants_count} structurally different layout concepts for review.
Please select your preferred concept for this target.
{FOR each concept in layout_concepts[target]:
═══════════════════════════════════════════════════
Concept {concept.index}: {concept.concept_name}
═══════════════════════════════════════════════════
Philosophy: {concept.design_philosophy}
Pattern: {concept.layout_pattern}
Components:
{FOR each component in concept.key_components:
• {component}
}
Features:
{FOR each feature in concept.structural_features:
• {feature}
}
Wireframe:
{concept.wireframe_preview.ascii_art}
═══════════════════════════════════════════════════
}
```
### Step 3: Capture User Selection (Per Target)
```javascript
// Use AskUserQuestion tool for each target
FOR each target:
AskUserQuestion({
questions: [{
question: "Which layout concept do you prefer for '{target}'?",
header: "Layout for " + target,
multiSelect: false,
options: [
{FOR each concept in layout_concepts[target]:
label: "Concept {concept.index}: {concept.concept_name}",
description: "{concept.design_philosophy}"
}
]
}]
})
// Parse user response
selected_option_text = user_answer
// Check for user cancellation
IF selected_option_text == null OR selected_option_text == "":
REPORT: "⚠️ User canceled selection. Workflow terminated."
EXIT workflow
// Extract concept index from response format "Concept N: Name"
match = selected_option_text.match(/Concept (\d+):/)
IF match:
selected_index = parseInt(match[1])
ELSE:
ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
EXIT workflow
// Store selection for this target
selections[target] = {
selected_index: selected_index,
concept_name: layout_concepts[target][selected_index-1].concept_name
}
```
### Step 4: Write User Selection File
```bash
# Create user selection JSON
selection_data = {
"metadata": {
"selected_at": "{current_timestamp}",
"selection_type": "per_target",
"session_id": "{session_id}"
},
"selections": selections // {target: {selected_index, concept_name}}
}
# Write to file
bash(echo '{selection_data}' > {base_path}/.intermediates/layout-analysis/user-selection.json)
# Verify
bash(test -f {base_path}/.intermediates/layout-analysis/user-selection.json && echo "saved")
```
### Step 5: Confirmation Message
```
✅ Selections recorded!
{FOR each target, selection in selections:
• {target}: Concept {selection.selected_index} - {selection.concept_name}
}
Proceeding to generate detailed layout templates based on your selections...
```
**Output**: `user-selection.json` with user's choices for all targets
## Phase 2: Layout Template Generation (Agent Task 2)
**Executor**: `Task(ui-design-agent)` for selected concept(s)
### Step 1: Load User Selection (Explore Mode)
```bash
# For explore mode, read user selection
IF extraction_mode == "explore":
selection = Read({base_path}/.intermediates/layout-analysis/user-selection.json)
selections_per_target = selection.selections
# Also read the selected concept details from options
options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
layout_concepts = options.layout_concepts
# Build selected concepts map
selected_concepts = {}
FOR each target in targets:
selected_index = selections_per_target[target].selected_index
selected_concepts[target] = layout_concepts[target][selected_index-1] # 0-indexed
ELSE:
# Imitate mode - no selection needed
selected_concepts = null
```
### Step 2: Launch Agent Task
Generate layout templates for selected concepts:
```javascript
Task(ui-design-agent): `
[LAYOUT_TEMPLATE_GENERATION_TASK]
Generate detailed layout templates based on user-selected concepts.
Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
DEVICE_TYPE: {device_type}
${extraction_mode == "explore" ? `
USER SELECTIONS:
${targets.map(target => `
Target: ${target}
- Selected Concept: ${selected_concepts[target].concept_name}
- Philosophy: ${selected_concepts[target].design_philosophy}
- Pattern: ${selected_concepts[target].layout_pattern}
- Key Components: ${selected_concepts[target].key_components.join(", ")}
- Structural Features: ${selected_concepts[target].structural_features.join(", ")}
`).join("\n")}
` : `
MODE: Imitate - High-fidelity replication of reference layout structure
TARGETS: ${targets.join(", ")}
`}
## Input Analysis
- Targets: {targets.join(", ")}
- Device type: {device_type}
- Visual references: {loaded_images if available}
${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-*.json - USE THIS for accurate layout properties" : ""}
## Generation Rules
${extraction_mode == "explore" ? `
- **Explore Mode**: Develop each user-selected layout concept into a detailed template
- Use the selected concept's key_components as foundation
- Apply the selected layout_pattern (grid-3col, flex-row, etc.)
- Honor the structural_features defined in the concept
- Expand the concept with complete DOM structure and CSS layout rules
` : `
- **Imitate Mode**: High-fidelity replication of reference layout structure
${dom_structure_available ? "- Use DOM structure data as ground truth" : "- Use visual inference"}
`}
${dom_structure_available ? `
- IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties
- Use DOM data as primary source for layout properties
- Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)
- Use actual element bounds for responsive breakpoint decisions
- Preserve identified patterns from DOM structure
` : ""}
## Generate for EACH Target
For target in {targets}:
${extraction_mode == "explore" ? "Based on user-selected concept:" : "Based on reference:"}
1. **DOM Structure**:
- Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
- ARIA roles and accessibility attributes
${extraction_mode == "explore" ? "- Use key_components from selected concept" : ""}
${dom_structure_available ? "- Base on extracted DOM tree from .intermediates" : "- Infer from visual analysis"}
- Device-specific optimizations for {device_type}
2. **Component Hierarchy**:
- Array of main layout regions
${extraction_mode == "explore" ? "- Derived from selected concept's key_components" : ""}
3. **CSS Layout Rules**:
${extraction_mode == "explore" ? "- Implement selected layout_pattern" : ""}
${dom_structure_available ? "- Use real layout properties from DOM structure data" : "- Focus on Grid, Flexbox, position, alignment"}
- Use CSS Custom Properties: var(--spacing-*), var(--breakpoint-*)
- Device-specific styles (mobile-first @media for responsive)
- NO colors, NO fonts, NO shadows - layout structure only
## Output Format
Write complete layout-templates.json with layout_templates array.
Each template must include:
- target (string)
- variant_id: "layout-1" (always 1 since only selected concept is generated)
- source_image_path (string): Reference image path
- device_type (string)
- design_philosophy (string ${extraction_mode == "explore" ? "- from selected concept" : ""})
- dom_structure (JSON object)
- component_hierarchy (array of strings)
- css_layout_rules (string)
## Critical Requirements
- ✅ Use Write() tool for layout-templates.json
- ✅ One template per target (only selected concept)
- ✅ Structure only, no visual styling
- ✅ Token-based CSS (var())
${extraction_mode == "explore" ? "- ✅ Maintain consistency with selected concepts" : ""}
`
```
**Output**: Agent generates `layout-templates.json` with one template per target
### Step 2: Write Output File
```bash
# Take JSON output from agent
bash(echo '{agent_json_output}' > {base_path}/layout-extraction/layout-templates.json)
# Verify output
bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_templates" && echo "valid")
```
**Output**: `layout-templates.json` created and verified
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
{content: "Layout research (explore mode)", status: "completed", activeForm: "Researching layout patterns"},
{content: "Layout analysis and synthesis (agent)", status: "completed", activeForm: "Generating layout templates"},
{content: "Write layout-templates.json", status: "completed", activeForm: "Saving templates"}
]});
```
### Output Message
```
✅ Layout extraction complete!
Configuration:
- Session: {session_id}
- Extraction Mode: {extraction_mode} (imitate/explore)
- Device Type: {device_type}
- Targets: {targets}
- Variants per Target: {variants_count}
- Total Templates: {targets.length × variants_count}
{IF has_urls AND dom_structure_available:
- 🔍 URL Mode: DOM structure extracted from {len(url_list)} URL(s)
- Accuracy: Real flex/grid properties from live pages
}
{IF has_urls AND NOT dom_structure_available:
- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
}
{IF extraction_mode == "explore":
Layout Research:
- {targets.length} inspiration files generated
- Pattern search focused on {device_type} layouts
}
Generated Templates:
{FOR each template: - Target: {template.target} | Variant: {template.variant_id} | Philosophy: {template.design_philosophy}}
Output File:
- {base_path}/layout-extraction/layout-templates.json
{IF dom_structure_available:
- {base_path}/.intermediates/layout-analysis/dom-structure-*.json ({len(url_list)} files)
}
Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
# Create output directories
bash(mkdir -p {base_path}/layout-extraction)
bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations) # explore mode only
```
### Validation Commands
```bash
# Check if already extracted
bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
# Validate JSON structure
bash(cat layout-templates.json | grep -q "layout_templates" && echo "valid")
# Count templates
bash(cat layout-templates.json | grep -c "\"target\":")
```
### File Operations
```bash
# Load image references
bash(ls {images_pattern})
Read({image_path})
# Write inspiration files (explore mode)
Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, content)
# Write layout templates
bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
```
## Output Structure
```
{base_path}/
├── .intermediates/ # Intermediate analysis files
│ └── layout-analysis/
│ ├── dom-structure-{target}.json # Extracted DOM structure (URL mode only)
│ └── inspirations/ # Explore mode only
│ └── {target}-layout-ideas.txt # Layout inspiration research
└── layout-extraction/ # Final layout templates
├── layout-templates.json # Structural layout templates
└── layout-space-analysis.json # Layout directions (explore mode only)
```
## layout-templates.json Format
```json
{
"extraction_metadata": {
"session_id": "...",
"input_mode": "image|url|prompt|hybrid",
"extraction_mode": "imitate|explore",
"device_type": "desktop|mobile|tablet|responsive",
"timestamp": "...",
"variants_count": 3,
"targets": ["home", "dashboard"]
},
"layout_templates": [
{
"target": "home",
"variant_id": "layout-1",
"source_image_path": "{base_path}/screenshots/home.png",
"device_type": "responsive",
"design_philosophy": "Responsive 3-column holy grail layout with fixed header and footer",
"dom_structure": {
"tag": "body",
"children": [
{
"tag": "header",
"attributes": {"class": "layout-header"},
"children": [{"tag": "nav"}]
},
{
"tag": "div",
"attributes": {"class": "layout-main-wrapper"},
"children": [
{"tag": "main", "attributes": {"class": "layout-main-content"}},
{"tag": "aside", "attributes": {"class": "layout-sidebar-left"}},
{"tag": "aside", "attributes": {"class": "layout-sidebar-right"}}
]
},
{"tag": "footer", "attributes": {"class": "layout-footer"}}
]
},
"component_hierarchy": [
"header",
"main-content",
"sidebar-left",
"sidebar-right",
"footer"
],
"css_layout_rules": ".layout-main-wrapper { display: grid; grid-template-columns: 1fr 3fr 1fr; gap: var(--spacing-6); } @media (max-width: var(--breakpoint-md)) { .layout-main-wrapper { grid-template-columns: 1fr; } }"
}
]
}
```
**Requirements**: Token-based CSS (var()), semantic HTML5, device-specific structure, accessibility attributes
## Error Handling
### Common Errors
```
ERROR: No inputs provided
→ Provide --images, --urls, or --prompt
ERROR: Invalid target name
→ Use lowercase, alphanumeric, hyphens only
ERROR: Agent task failed
→ Check agent output, retry with simplified prompt
ERROR: MCP search failed (explore mode)
→ Check network, retry
```
### Recovery Strategies
- **Partial success**: Keep successfully extracted templates
- **Invalid JSON**: Retry with stricter format requirements
- **Missing inspiration**: Works without (less informed exploration)
## Key Features
- **Auto-Trigger URL Mode** - Automatically extracts DOM structure when --urls provided (no manual flag needed)
- **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
- **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
- **Separation of Concerns** - Decouples layout (structure) from style (visuals)
- **Structural Exploration** - Explore mode enables A/B testing of different layouts
- **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
- **Device-Specific** - Tailored structures for different screen sizes
- **Graceful Fallback** - Falls back to visual analysis if Chrome DevTools unavailable
- **Foundation for Assembly** - Provides structural blueprint for refactored `generate` command
- **Agent-Powered** - Deep structural analysis with AI
## Integration
**Workflow Position**: Between style extraction and prototype generation
**New Workflow**:
1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md` (Complete design systems)
2. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
3. `/workflow:ui-design:generate` (Pure assembler):
- **Reads**: `design-tokens.json` + `layout-templates.json`
- **Action**: For each style × layout combination:
1. Build HTML from `dom_structure`
2. Create layout CSS from `css_layout_rules`
3. Link design tokens CSS
4. Inject placeholder content
- **Output**: Complete token-driven HTML/CSS prototypes
**Input**: Reference images, URLs, or text prompts
**Output**: `layout-templates.json` for `/workflow:ui-design:generate`
**Next**: `/workflow:ui-design:generate --session {session_id}`

671
.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md Normal file
View File

@@ -0,0 +1,671 @@
---
name: style-extract
description: Extract design style from reference images or text prompts using Claude analysis with variant generation
argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
---
# Style Extraction Command
## Overview
Extract design style from reference images or text prompts using Claude's built-in analysis. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
**Strategy**: AI-Driven Design Space Exploration
- **Claude-Native**: 100% Claude analysis, no external tools
- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
- **Flexible Input**: Images, text prompts, or both (hybrid mode)
- **Maximum Contrast**: AI generates maximally divergent design directions
- **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
## Phase 0: Setup & Input Validation
### Step 1: Detect Input Mode, Extraction Mode & Base Path
```bash
# Detect input source
# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
# Parse URLs if provided (format: "target:url,target:url,...")
IF --urls:
url_list = []
FOR pair IN split(--urls, ","):
IF ":" IN pair:
target, url = pair.split(":", 1)
url_list.append({target: target.strip(), url: url.strip()})
ELSE:
# Single URL without target
url_list.append({target: "page", url: pair.strip()})
has_urls = true
primary_url = url_list[0].url # First URL as primary source
ELSE:
has_urls = false
# Determine extraction mode
# Priority: --mode parameter → default "imitate"
extraction_mode = --mode OR "imitate" # "imitate" or "explore"
# Set variants count based on mode
IF extraction_mode == "imitate":
variants_count = 1 # Force single variant for imitate mode (ignore --variants)
ELSE IF extraction_mode == "explore":
variants_count = --variants OR 3 # Default to 3 for explore mode
VALIDATE: 1 <= variants_count <= 5
# Determine base path
bash(find .workflow -type d -name "design-*" | head -1) # Auto-detect
# OR use --base-path / --session parameters
```
### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
```bash
# AUTO-TRIGGER: If URLs are available (from --urls parameter or capture metadata), automatically extract real CSS values
# This provides accurate design tokens to supplement visual analysis
# Priority 1: Check for --urls parameter
IF has_urls:
url_to_extract = primary_url
url_source = "--urls parameter"
# Priority 2: Check for URL metadata from capture phase
ELSE IF exists({base_path}/.metadata/capture-urls.json):
capture_urls = Read({base_path}/.metadata/capture-urls.json)
url_to_extract = capture_urls[0] # Use first URL
url_source = "capture metadata"
ELSE:
url_to_extract = null
# Execute extraction if URL available
IF url_to_extract AND mcp_chrome_devtools_available:
REPORT: "🔍 Auto-triggering URL mode: Extracting computed styles from {url_source}"
REPORT: " URL: {url_to_extract}"
# Read extraction script
script_content = Read(~/.claude/scripts/extract-computed-styles.js)
# Open page in Chrome DevTools
mcp__chrome-devtools__navigate_page(url=url_to_extract)
# Execute extraction script directly
result = mcp__chrome-devtools__evaluate_script(function=script_content)
# Save computed styles to intermediates directory
bash(mkdir -p {base_path}/.intermediates/style-analysis)
Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
computed_styles_available = true
REPORT: " ✅ Computed styles extracted and saved"
ELSE:
computed_styles_available = false
IF url_to_extract:
REPORT: "⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
```
**Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
**Script returns**:
- `metadata`: Extraction timestamp, URL, method
- `tokens`: Organized design tokens (colors, borderRadii, shadows, fontSizes, fontWeights, spacing)
**Benefits**:
- ✅ Pixel-perfect accuracy for border-radius, box-shadow, padding, etc.
- ✅ Eliminates guessing from visual analysis
- ✅ Provides ground truth for design tokens
### Step 3: Load Inputs
```bash
# For image mode
bash(ls {images_pattern}) # Expand glob pattern
Read({image_path}) # Load each image
# For text mode
# Validate --prompt is non-empty
# Create output directory
bash(mkdir -p {base_path}/style-extraction/)
```
### Step 3: Memory Check
```bash
# 1. Check if inputs cached in session memory
IF session_has_inputs: SKIP Step 2 file reading
# 2. Check if output already exists
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
IF exists: SKIP to completion
```
---
**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`, `has_urls`, `url_list[]`, `computed_styles_available`
## Phase 1: Design Direction Generation (Explore Mode Only)
### Step 1: Check Extraction Mode
```bash
# Check extraction mode
# extraction_mode == "imitate" → skip this phase
# extraction_mode == "explore" → execute this phase
```
**If imitate mode**: Skip to Phase 2
### Step 2: Load Project Context (Explore Mode)
```bash
# Load brainstorming context if available
bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
```
### Step 3: Generate Design Direction Options (Agent Task 1)
**Executor**: `Task(ui-design-agent)`
Launch agent to generate `variants_count` design direction options with previews:
```javascript
Task(ui-design-agent): `
[DESIGN_DIRECTION_GENERATION_TASK]
Generate {variants_count} maximally contrasting design directions with visual previews
SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
## Input Analysis
- User prompt: {prompt_guidance}
- Visual references: {loaded_images if available}
- Project context: {brainstorming_context if available}
## Analysis Rules
- Analyze 6D attribute space: color saturation, visual weight, formality, organic/geometric, innovation, density
- Generate {variants_count} directions with MAXIMUM contrast
- Each direction must be distinctly different (min distance score: 0.7)
## Generate for EACH Direction
1. **Core Philosophy**:
- philosophy_name (2-3 words, e.g., "Minimalist & Airy")
- design_attributes (6D scores 0-1)
- search_keywords (3-5 keywords)
- anti_keywords (2-3 keywords to avoid)
- rationale (why this is distinct from others)
2. **Visual Preview Elements**:
- primary_color (OKLCH format)
- secondary_color (OKLCH format)
- accent_color (OKLCH format)
- font_family_heading (specific font name)
- font_family_body (specific font name)
- border_radius_base (e.g., "0.5rem")
- mood_description (1-2 sentences describing the feel)
## Output
Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
CRITICAL: Use Write() tool immediately after generating complete JSON
`
```
### Step 4: Verify Options File Created
```bash
bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
# Quick validation
bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep -q "design_directions" && echo "valid")
```
**Output**: `analysis-options.json` with design direction options
---
## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
### Step 1: Load and Present Options
```bash
# Read options file
options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
# Parse design directions
design_directions = options.design_directions
```
### Step 2: Present Options to User
```
📋 Design Direction Options
We've generated {variants_count} contrasting design directions for your review.
Please select the direction(s) you'd like to develop into complete design systems.
{FOR each direction in design_directions:
═══════════════════════════════════════════════════
Option {direction.index}: {direction.philosophy_name}
═══════════════════════════════════════════════════
Philosophy: {direction.rationale}
Visual Preview:
• Colors: {direction.preview.primary_color} (primary), {direction.preview.accent_color} (accent)
• Typography: {direction.preview.font_family_heading} (headings), {direction.preview.font_family_body} (body)
• Border Radius: {direction.preview.border_radius_base}
• Mood: {direction.preview.mood_description}
Design Attributes:
• Color Saturation: {direction.design_attributes.color_saturation * 100}%
• Visual Weight: {direction.design_attributes.visual_weight * 100}%
• Formality: {direction.design_attributes.formality * 100}%
• Innovation: {direction.design_attributes.innovation * 100}%
Keywords: {join(direction.search_keywords, ", ")}
Avoiding: {join(direction.anti_keywords, ", ")}
}
═══════════════════════════════════════════════════
```
### Step 3: Capture User Selection
```javascript
// Use AskUserQuestion tool for selection
AskUserQuestion({
questions: [{
question: "Which design direction would you like to develop into a complete design system?",
header: "Style Choice",
multiSelect: false, // Single selection for Phase 1
options: [
{FOR each direction:
label: "Option {direction.index}: {direction.philosophy_name}",
description: "{direction.mood_description}"
}
]
}]
})
// Parse user response (e.g., "Option 1: Minimalist & Airy")
selected_option_text = user_answer
// Check for user cancellation
IF selected_option_text == null OR selected_option_text == "":
REPORT: "⚠️ User canceled selection. Workflow terminated."
EXIT workflow
// Extract option index from response format "Option N: Name"
match = selected_option_text.match(/Option (\d+):/)
IF match:
selected_index = parseInt(match[1])
ELSE:
ERROR: "Invalid selection format. Expected 'Option N: ...' format"
EXIT workflow
```
### Step 4: Write User Selection File
```bash
# Create user selection JSON
selection_data = {
"metadata": {
"selected_at": "{current_timestamp}",
"selection_type": "single",
"session_id": "{session_id}"
},
"selected_indices": [selected_index],
"refinements": {
"enabled": false
}
}
# Write to file
bash(echo '{selection_data}' > {base_path}/.intermediates/style-analysis/user-selection.json)
# Verify
bash(test -f {base_path}/.intermediates/style-analysis/user-selection.json && echo "saved")
```
### Step 5: Confirmation Message
```
✅ Selection recorded!
You selected: Option {selected_index} - {selected_direction.philosophy_name}
Proceeding to generate complete design system based on your selection...
```
**Output**: `user-selection.json` with user's choice
## Phase 2: Design System Generation (Agent Task 2)
**Executor**: `Task(ui-design-agent)` for selected variant(s)
### Step 1: Load User Selection (Explore Mode)
```bash
# For explore mode, read user selection
IF extraction_mode == "explore":
selection = Read({base_path}/.intermediates/style-analysis/user-selection.json)
selected_indices = selection.selected_indices
refinements = selection.refinements
# Also read the selected direction details from options
options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
selected_directions = [options.design_directions[i-1] for i in selected_indices] # 0-indexed
# For Phase 1, we only allow single selection
selected_direction = selected_directions[0]
actual_variants_count = 1
ELSE:
# Imitate mode - generate single variant without selection
selected_direction = null
actual_variants_count = 1
```
### Step 2: Create Output Directory
```bash
# Create directory for selected variant only
bash(mkdir -p {base_path}/style-extraction/style-1)
```
### Step 3: Launch Agent Task
Generate design system for selected direction:
```javascript
Task(ui-design-agent): `
[DESIGN_SYSTEM_GENERATION_TASK]
Generate production-ready design system based on user-selected direction
SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
${extraction_mode == "explore" ? `
USER SELECTION:
- Selected Direction: ${selected_direction.philosophy_name}
- Design Attributes: ${JSON.stringify(selected_direction.design_attributes)}
- Search Keywords: ${selected_direction.search_keywords.join(", ")}
- Anti-keywords: ${selected_direction.anti_keywords.join(", ")}
- Rationale: ${selected_direction.rationale}
- Preview Colors: Primary=${selected_direction.preview.primary_color}, Accent=${selected_direction.preview.accent_color}
- Preview Typography: Heading=${selected_direction.preview.font_family_heading}, Body=${selected_direction.preview.font_family_body}
- Preview Border Radius: ${selected_direction.preview.border_radius_base}
${refinements.enabled ? `
USER REFINEMENTS:
${refinements.primary_color ? "- Primary Color Override: " + refinements.primary_color : ""}
${refinements.font_family_heading ? "- Heading Font Override: " + refinements.font_family_heading : ""}
${refinements.font_family_body ? "- Body Font Override: " + refinements.font_family_body : ""}
` : ""}
` : ""}
## Input Analysis
- Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
- Visual references: {loaded_images OR prompt_guidance}
${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
## Generation Rules
${extraction_mode == "explore" ? `
- **Explore Mode**: Develop the selected design direction into a complete design system
- Use preview elements as foundation and expand with full token coverage
- Apply design_attributes to all token values:
* color_saturation → OKLCH chroma values
* visual_weight → font weights, shadow depths
* density → spacing scale compression/expansion
* formality → typography choices, border radius
* organic_geometric → border radius, shape patterns
* innovation → token naming, experimental values
- Honor search_keywords for design inspiration
- Avoid anti_keywords patterns
` : `
- **Imitate Mode**: High-fidelity replication of reference design
${computed_styles_available ? "- Use computed styles as ground truth for all measurements" : "- Use visual inference for measurements"}
`}
- All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
- WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
## Generate
Create complete design system in {base_path}/style-extraction/style-1/
1. **design-tokens.json**:
- Complete token structure with ALL fields:
* colors (brand, surface, semantic, text, border) - OKLCH format
* typography (families, sizes, weights, line heights, letter spacing, combinations)
* typography.combinations: Predefined typography presets (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) using var() references
* spacing (0-24 scale)
* opacity (0, 10, 20, 40, 60, 80, 90, 100)
* border_radius (none to full)
* shadows (sm to xl)
* component_styles (button, card, input variants) - component presets using var() references
* breakpoints (sm to 2xl)
- All colors in OKLCH format
${extraction_mode == "explore" ? "- Start from preview colors and expand to full palette" : ""}
${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
- Common Tailwind CSS usage patterns in project (if extracting from existing project)
2. **style-guide.md**:
- Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
- Complete color system documentation with accessibility notes
- Typography scale and usage guidelines
- Typography Combinations section: Document each preset (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) with usage context and code examples
- Spacing system explanation
- Opacity & Transparency section: Opacity scale usage, common use cases (disabled states, overlays, hover effects), accessibility considerations
- Shadows & Elevation section: Shadow hierarchy and semantic usage
- Component Styles section: Document button, card, and input variants with code examples and visual descriptions
- Border Radius system and semantic usage
- Component examples and usage patterns
- Common Tailwind CSS patterns (if applicable)
## Critical Requirements
- ✅ Use Write() tool immediately for each file
- ✅ Write to style-1/ directory (single output)
- ❌ NO external research or MCP calls (pure AI generation)
- ✅ Maintain consistency with user-selected direction
${refinements.enabled ? "- ✅ Apply user refinements precisely" : ""}
`
```
**Output**: Agent generates 2 files (design-tokens.json, style-guide.md) for selected direction
## Phase 3: Verify Output
### Step 1: Check Files Created
```bash
# Verify all design systems created
bash(ls {base_path}/style-extraction/style-*/design-tokens.json | wc -l)
# Validate structure
bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
```
### Step 2: Verify File Sizes
```bash
bash(ls -lh {base_path}/style-extraction/style-1/)
```
**Output**: `variants_count × 2` files verified
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
{content: "Design space analysis (explore mode)", status: "completed", activeForm: "Analyzing design space"},
{content: "Design system generation (agent)", status: "completed", activeForm: "Generating design systems"},
{content: "Verify output files", status: "completed", activeForm: "Verifying files"}
]});
```
### Output Message
```
✅ Style extraction complete!
Configuration:
- Session: {session_id}
- Extraction Mode: {extraction_mode} (imitate/explore)
- Input Mode: {input_mode} (image/text/hybrid{"/url" if has_urls else ""})
- Variants: {variants_count}
- Production-Ready: Complete design systems generated
{IF has_urls AND computed_styles_available:
- 🔍 URL Mode: Computed styles extracted from {len(url_list)} URL(s)
- Accuracy: Pixel-perfect design tokens from DOM
}
{IF has_urls AND NOT computed_styles_available:
- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
}
{IF extraction_mode == "explore":
Design Direction Selection:
- You selected: Option {selected_index} - {selected_direction.philosophy_name}
- Generated from {variants_count} contrasting design direction options
}
Generated Files:
{base_path}/style-extraction/
└── style-1/ (design-tokens.json, style-guide.md)
{IF computed_styles_available:
Intermediate Analysis:
{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
}
{IF extraction_mode == "explore":
{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options)
{base_path}/.intermediates/style-analysis/user-selection.json (your selection)
}
Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
OR: /workflow:ui-design:generate --session {session_id}
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-*" | head -1)
# Expand image pattern
bash(ls {images_pattern})
# Create output directory
bash(mkdir -p {base_path}/style-extraction/)
```
### Validation Commands
```bash
# Check if already extracted
bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
# Count variants
bash(ls {base_path}/style-extraction/style-* -d | wc -l)
# Validate JSON structure
bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
```
### File Operations
```bash
# Load brainstorming context
bash(test -f .brainstorming/role analysis documents && cat it)
# Create directories
bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
# Verify output
bash(ls {base_path}/style-extraction/style-1/)
bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "saved")
```
## Output Structure
```
{base_path}/
├── .intermediates/ # Intermediate analysis files
│ └── style-analysis/
│ ├── computed-styles.json # Extracted CSS values from DOM (if URL available)
│ ├── analysis-options.json # Design direction options (explore mode only)
│ └── user-selection.json # User's selected direction (explore mode only)
└── style-extraction/ # Final design system
└── style-1/
├── design-tokens.json # Production-ready design tokens
└── style-guide.md # Design philosophy and usage guide
```
## design-tokens.json Format
```json
{
"colors": {
"brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
"surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
"semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
"text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
"border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
},
"typography": {
"font_family": {...},
"font_size": {...},
"font_weight": {...},
"line_height": {...},
"letter_spacing": {...},
"combinations": {
"heading-primary": {"family": "var(--font-family-heading)", "size": "var(--font-size-3xl)", "weight": "var(--font-weight-bold)", "line_height": "var(--line-height-tight)", "letter_spacing": "var(--letter-spacing-tight)"},
"heading-secondary": {...},
"body-regular": {...},
"body-emphasis": {...},
"caption": {...},
"label": {...}
}
},
"spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
"opacity": {"0": "0", "10": "0.1", "20": "0.2", "40": "0.4", "60": "0.6", "80": "0.8", "90": "0.9", "100": "1"},
"border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
"shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
"component_styles": {
"button": {
"primary": {"background": "var(--color-brand-primary)", "color": "var(--color-text-inverse)", "padding": "var(--spacing-3) var(--spacing-6)", "border_radius": "var(--border-radius-md)", "font_weight": "var(--font-weight-semibold)"},
"secondary": {...},
"tertiary": {...}
},
"card": {
"default": {"background": "var(--color-surface-elevated)", "padding": "var(--spacing-6)", "border_radius": "var(--border-radius-lg)", "shadow": "var(--shadow-md)"},
"interactive": {...}
},
"input": {
"default": {"border": "1px solid var(--color-border-default)", "padding": "var(--spacing-3)", "border_radius": "var(--border-radius-md)", "background": "var(--color-surface-background)"},
"focus": {...},
"error": {...}
}
},
"breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
}
```
**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance, typography combinations, component style presets, opacity scale
## Error Handling
### Common Errors
```
ERROR: No images found
→ Check glob pattern
ERROR: Invalid prompt
→ Provide non-empty string
ERROR: Claude JSON parsing error
→ Retry with stricter format
```
## Key Features
- **Auto-Trigger URL Mode** - Automatically extracts computed styles when --urls provided (no manual flag needed)
- **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
- **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
- **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
- **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
- **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
- **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
- **Flexible Input** - Images, text, URLs, or hybrid mode
- **Graceful Fallback** - Falls back to pure visual inference if Chrome DevTools unavailable
- **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
- **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
## Integration
**Input**: Reference images or text prompts
**Output**: `style-extraction/style-{N}/` with design-tokens.json + style-guide.md
**Next**: `/workflow:ui-design:layout-extract --session {session_id}` OR `/workflow:ui-design:generate --session {session_id}`
**Note**: This command extracts visual style (colors, typography, spacing) and generates production-ready design systems. For layout structure extraction, use `/workflow:ui-design:layout-extract`.

363
.claude/skills/command-guide/reference/commands/workflow/ui-design/update.md Normal file
View File

@@ -0,0 +1,363 @@
---
name: update
description: Update brainstorming artifacts with finalized design system references from selected prototypes
argument-hint: --session <session_id> [--selected-prototypes "<list>"]
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
---
# Design Update Command
## Overview
Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
## Core Philosophy
- **Reference-Only Updates**: Use @ references, no content duplication
- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
- **Synthesis Alignment**: Update role analysis documents UI/UX Guidelines section
- **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
- **Minimal Reading**: Verify file existence, don't read design content
## Execution Protocol
### Phase 1: Session & Artifact Validation
```bash
# Validate session
CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
# Verify design artifacts in latest design run
latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
# Detect design system structure
IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
design_system_mode = "separate"; design_tokens_path = "style-extraction/style-1/design-tokens.json"; style_guide_path = "style-extraction/style-1/style-guide.md"
ELSE:
ERROR: "No design tokens found. Run /workflow:ui-design:style-extract first"
VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
REPORT: "📋 Design system mode: {design_system_mode} | Tokens: {design_tokens_path}"
# Prototype selection
selected_list = --selected-prototypes ? parse_comma_separated(--selected-prototypes) : Glob({latest_design}/prototypes/*.html)
VALIDATE: Specified prototypes exist IF --selected-prototypes
REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```
### Phase 1.1: Memory Check (Skip if Already Updated)
```bash
# Check if role analysis documents contains current design run reference
synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents"
current_design_run = basename(latest_design) # e.g., "design-run-20250109-143022"
IF exists(synthesis_spec_path):
synthesis_content = Read(synthesis_spec_path)
IF "## UI/UX Guidelines" in synthesis_content AND current_design_run in synthesis_content:
REPORT: "✅ Design system references already updated (found in memory)"
REPORT: " Skipping: Phase 2-5 (Load Target Artifacts, Update Synthesis, Update UI Designer Guide, Completion)"
EXIT 0
```
### Phase 2: Load Target Artifacts Only
**What to Load**: Only the files we need to **update**, not the design files we're referencing.
```bash
# Load target brainstorming artifacts (files to be updated)
Read(.workflow/WFS-{session}/.brainstorming/role analysis documents)
IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
# Optional: Read prototype notes for descriptions (minimal context)
FOR each selected_prototype IN selected_list:
Read({latest_design}/prototypes/{selected_prototype}-notes.md) # Extract: layout_strategy, page_name only
# Note: Do NOT read design-tokens.json, style-guide.md, or prototype HTML. Only verify existence and generate @ references.
```
### Phase 3: Update Synthesis Specification
Update `.brainstorming/role analysis documents` with design system references.
**Target Section**: `## UI/UX Guidelines`
**Content Template**:
```markdown
## UI/UX Guidelines
### Design System Reference
**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
**Style Guide**: @../design-{run_id}/{style_guide_path}
**Design System Mode**: {design_system_mode}
### Implementation Requirements
**Token Adherence**: All UI implementations MUST use design token CSS custom properties
**Accessibility**: WCAG AA compliance validated in design-tokens.json
**Responsive**: Mobile-first design using token-based breakpoints
**Component Patterns**: Follow patterns documented in style-guide.md
### Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
}
### Design System Assets
```json
{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
```
```
**Implementation**:
```bash
# Option 1: Edit existing section
Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents",
old_string="## UI/UX Guidelines\n[existing content]",
new_string="## UI/UX Guidelines\n\n[new design reference content]")
# Option 2: Append if section doesn't exist
IF section not found:
Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
```
### Phase 4A: Update Relevant Role Analysis Documents
**Discovery**: Find role analysis.md files affected by design outputs
```bash
# Always update ui-designer
ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
# Conditionally update other roles
has_animations = exists({latest_design}/animation-extraction/animation-tokens.json)
has_layouts = exists({latest_design}/layout-extraction/layout-templates.json)
IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md")
IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md")
```
**Content Templates**:
**ui-designer/analysis.md** (append if not exists):
```markdown
## Design System Implementation Reference
**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
**Style Guide**: @../../design-{run_id}/{style_guide_path}
**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
*Reference added by /workflow:ui-design:update*
```
**ux-expert/analysis.md** (if animations):
```markdown
## Animation & Interaction Reference
**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
*Reference added by /workflow:ui-design:update*
```
**system-architect/analysis.md** (if layouts):
```markdown
## Layout Structure Reference
**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
*Reference added by /workflow:ui-design:update*
```
**product-manager/analysis.md** (if prototypes):
```markdown
## Prototype Validation Reference
**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
*Reference added by /workflow:ui-design:update*
```
**Implementation**:
```bash
FOR file IN [ui_designer_files, ux_expert_files, architect_files, pm_files]:
IF file exists AND section_not_exists(file):
Edit(file, old_string="[end of document]", new_string="\n\n{role-specific section}")
```
### Phase 4B: Create UI Designer Design System Reference
Create or update `.brainstorming/ui-designer/design-system-reference.md`:
```markdown
# UI Designer Design System Reference
## Design System Integration
This style guide references the finalized design system from the design refinement phase.
**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
**Style Guide**: @../../design-{run_id}/{style_guide_path}
**Design System Mode**: {design_system_mode}
## Implementation Guidelines
1. **Use CSS Custom Properties**: All styles reference design tokens
2. **Follow Semantic HTML**: Use HTML5 semantic elements
3. **Maintain Accessibility**: WCAG AA compliance required
4. **Responsive Design**: Mobile-first with token-based breakpoints
## Reference Prototypes
{FOR each selected_prototype:
- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
}
## Token System
For complete token definitions and usage examples, see:
- Design Tokens: @../../design-{run_id}/{design_tokens_path}
- Style Guide: @../../design-{run_id}/{style_guide_path}
---
*Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
```
**Implementation**:
```bash
Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
content="[generated content with @ references]")
```
### Phase 5: Completion
```javascript
TodoWrite({todos: [
{content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
{content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
{content: "Update role analysis documents with design references", status: "completed", activeForm: "Updating synthesis spec"},
{content: "Update relevant role analysis.md documents", status: "completed", activeForm: "Updating role analysis files"},
{content: "Create/update ui-designer/design-system-reference.md", status: "completed", activeForm: "Creating design system reference"}
]});
```
**Completion Message**:
```
✅ Design system references updated for session: WFS-{session}
Updated artifacts:
✓ role analysis documents - UI/UX Guidelines section with @ references
✓ {role_count} role analysis.md files - Design system references
✓ ui-designer/design-system-reference.md - Design system reference guide
Design system assets ready for /workflow:plan:
- design-tokens.json | style-guide.md | {prototype_count} reference prototypes
Next: /workflow:plan [--agent] "<task description>"
The plan phase will automatically discover and utilize the design system.
```
## Output Structure
**Updated Files**:
```
.workflow/WFS-{session}/.brainstorming/
├── role analysis documents # Updated with UI/UX Guidelines section
├── ui-designer/
│ ├── analysis*.md # Updated with design system references
│ └── design-system-reference.md # New or updated design reference guide
├── ux-expert/analysis*.md # Updated if animations exist
├── product-manager/analysis*.md # Updated if prototypes exist
└── system-architect/analysis*.md # Updated if layouts exist
```
**@ Reference Format** (role analysis documents):
```
@../design-{run_id}/style-extraction/style-1/design-tokens.json
@../design-{run_id}/style-extraction/style-1/style-guide.md
@../design-{run_id}/prototypes/{prototype}.html
```
**@ Reference Format** (ui-designer/design-system-reference.md):
```
@../../design-{run_id}/style-extraction/style-1/design-tokens.json
@../../design-{run_id}/style-extraction/style-1/style-guide.md
@../../design-{run_id}/prototypes/{prototype}.html
```
**@ Reference Format** (role analysis.md files):
```
@../../design-{run_id}/style-extraction/style-1/design-tokens.json
@../../design-{run_id}/animation-extraction/animation-tokens.json
@../../design-{run_id}/layout-extraction/layout-templates.json
@../../design-{run_id}/prototypes/{prototype}.html
```
## Integration with /workflow:plan
After this update, `/workflow:plan` will discover design assets through:
**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
- Reads role analysis documents → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
- Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
**Example Task JSON** (generated by task-generate):
```json
{
"task_id": "IMPL-001",
"context": {
"design_system": {
"tokens": "design-{run_id}/style-extraction/style-1/design-tokens.json",
"style_guide": "design-{run_id}/style-extraction/style-1/style-guide.md",
"prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
}
}
}
```
## Error Handling
- **Missing design artifacts**: Error with message "Run /workflow:ui-design:style-extract and /workflow:ui-design:generate first"
- **role analysis documents not found**: Warning, create minimal version with just UI/UX Guidelines
- **ui-designer/ directory missing**: Create directory and file
- **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
- **Invalid prototype names**: Skip invalid entries, continue with valid ones
## Validation Checks
After update, verify:
- [ ] role analysis documents contains UI/UX Guidelines section
- [ ] UI/UX Guidelines include @ references (not content duplication)
- [ ] ui-designer/analysis*.md updated with design system references
- [ ] ui-designer/design-system-reference.md created or updated
- [ ] Relevant role analysis.md files updated (ux-expert, product-manager, system-architect)
- [ ] All @ referenced files exist and are accessible
- [ ] @ reference paths are relative and correct
## Key Features
1. **Reference-Only Updates**: Uses @ notation for file references, no content duplication, lightweight and maintainable
2. **Main Claude Direct Execution**: No Agent handoff (preserves context), simple reference generation, reliable path resolution
3. **Plan-Ready Output**: `/workflow:plan` Phase 3 can discover design system, task generation includes design asset paths, clear integration points
4. **Minimal Reading**: Only reads target files to update, verifies design file existence (no content reading), optional prototype notes for descriptions
5. **Flexible Prototype Selection**: Auto-select all prototypes (default), manual selection via --selected-prototypes parameter, validates existence
## Integration Points
- **Input**: Design system artifacts from `/workflow:ui-design:style-extract` and `/workflow:ui-design:generate`
- **Output**: Updated role analysis documents, role analysis.md files, ui-designer/design-system-reference.md with @ references
- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
## Why Main Claude Execution?
This command is executed directly by main Claude (not delegated to an Agent) because:
1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
2. **Context Preservation**: Main Claude has full session and conversation context
3. **Minimal Transformation**: Primarily updating references, not analyzing content
4. **Path Resolution**: Requires precise relative path calculation
5. **Edit Operations**: Better error recovery for Edit conflicts
6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
This ensures reliable, lightweight integration without Agent handoff overhead.