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

Refactor planning workflow documentation and enhance UI designer role template

Browse Source 
- Updated the `/workflow:plan` command description to clarify its orchestration of a 4-phase planning workflow.
- Revised the execution flow and core planning principles for improved clarity and structure.
- Removed the `ANALYSIS_RESULTS.md` file as it is no longer needed in the workflow.
- Enhanced the `concept-enhanced` tool documentation to specify mandatory first steps and output requirements.
- Expanded the `ui-designer` role template to include detailed design workflows, output requirements, and collaboration strategies.
- Introduced new design phases with clear outputs and user approval checkpoints in the UI designer template.
This commit is contained in:
catlog22
2025-09-30 13:37:37 +08:00
parent 04876c80bd
commit 7775cb3b0a
9 changed files with 929 additions and 956 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
.claude/WORKFLOW_MODULAR_REFACTOR.md
View File

@@ -1,237 +0,0 @@
# Workflow 命令模块化重构方案
## 📋 重构概览
### 目标
将现有workflow命令中的智能分析能力抽象为独立的、可复用的模块，提升系统的模块化程度、可维护性和可扩展性。
### 核心原则
- **单一职责**：每个模块只负责一个核心功能
- **高内聚低耦合**：模块内部逻辑紧密，模块间接口清晰
- **可复用性**：智能模块可在多个场景下复用
- **向后兼容**：保持现有工作流程的功能完整性
## 🎯 模块化设计
### 1. 智能上下文模块 (`/context`)
**职责**：智能收集项目相关上下文信息
**核心命令**：`/context:gather`
- **功能**：根据任务描述，从代码库、文档、历史记录中智能收集相关信息
- **输入**：任务描述字符串
- **输出**：标准化的context-package.json文件
- **特性**：
- 关键字分析和文档智能加载
- 代码结构分析（使用get_modules_by_depth.sh）
- 依赖关系发现
- MCP工具集成（code-index, exa）
**输出格式**：
```json
{
"metadata": {
"task_description": "实现用户认证系统",
"timestamp": "2025-09-29T10:00:00Z",
"keywords": ["用户", "认证", "系统"]
},
"assets": [
{
"type": "documentation|source_code|config",
"path": "相对路径",
"relevance": "相关性描述"
}
]
}
```
### 2. 智能分析模块 (`/analysis`)
**职责**：基于上下文进行深度智能分析
**核心命令**：`/analysis:run`
- **功能**：接收上下文包，执行深度分析，生成结构化报告
- **输入**：context-package.json文件路径
- **输出**：ANALYSIS_RESULTS.md文件
- **特性**：
- 智能工具选择（Gemini/Qwen/Codex）
- 动态Prompt构建
- 结构化分析输出
### 3. 重构的协调器 (`/workflow:plan`)
**新职责**：编排智能模块，生成最终实施计划
**执行流程**：
```
用户输入 → 创建会话 → context:gather → analysis:run → 生成IMPL_PLAN.md
```
## 📁 目录结构重组
### 当前结构问题
```
.claude/commands/workflow/
├── plan.md # 复杂混合逻辑
├── execute.md # 代理协调
├── status.md # 状态查看
├── docs.md # 文档生成
├── concept-eval.md # 概念评估
├── session/ # 会话管理 ✓
├── issue/ # 问题跟踪 ✓
└── brainstorm/ # 头脑风暴 ✓
```
### 重构后结构
```
.claude/commands/
├── workflow/
│ ├── pipeline/ # 核心流程
│ │ ├── plan.md # 重构为协调器
│ │ ├── verify.md # 计划验证
│ │ ├── execute.md # 执行协调
│ │ ├── resume.md # 恢复执行
│ │ ├── review.md # 代码审查
│ │ └── test-gen.md # 测试生成
│ ├── session/ # 会话管理（保持）
│ ├── issue/ # 问题跟踪（保持）
│ ├── brainstorm/ # 头脑风暴（保持）
│ └── tools/ # 辅助工具
│ ├── status.md
│ ├── docs.md
│ └── concept-eval.md
├── context/ # 新增：智能上下文
│ └── gather.md
├── analysis/ # 新增：智能分析
│ └── run.md
└── task/ # 任务管理（保持）
```
## 🔧 实施计划
### 阶段1：创建新模块 (步骤1-4)
1. **创建模块目录**
- 创建 `.claude/commands/context/`
- 创建 `.claude/commands/analysis/`
2. **实现context:gather命令**
- 从workflow/plan.md提取上下文收集逻辑
- 实现标准化的context-package.json输出
3. **实现analysis:run命令**
- 从workflow/plan.md提取分析逻辑
- 实现ANALYSIS_RESULTS.md生成
4. **定义模块接口**
- 标准化输入输出格式
- 定义错误处理策略
### 阶段2：重构现有命令 (步骤5-6)
5. **重构workflow:plan**
- 简化为协调器角色
- 调用新的智能模块
- 保持最终输出兼容性
6. **重组workflow目录**
- 创建pipeline/和tools/子目录
- 移动相应命令文件
- 更新命令路径引用
### 阶段3：测试与优化 (步骤7)
7. **集成测试**
- 验证新模块功能
- 测试模块间协调
- 确保向后兼容
## 📋 详细实施清单
### 文件操作清单
**新建文件**：
- `.claude/commands/context/gather.md`
- `.claude/commands/analysis/run.md`
- `.claude/commands/workflow/pipeline/` (目录)
- `.claude/commands/workflow/tools/` (目录)
**移动文件**：
- `workflow/plan.md` → `workflow/pipeline/plan.md` (内容重构)
- `workflow/plan-verify.md` → `workflow/pipeline/verify.md`
- `workflow/execute.md` → `workflow/pipeline/execute.md`
- `workflow/resume.md` → `workflow/pipeline/resume.md`
- `workflow/review.md` → `workflow/pipeline/review.md`
- `workflow/test-gen.md` → `workflow/pipeline/test-gen.md`
- `workflow/status.md` → `workflow/tools/status.md`
- `workflow/docs.md` → `workflow/tools/docs.md`
- `workflow/concept-eval.md` → `workflow/tools/concept-eval.md`
**保持不变**：
- `workflow/session/` (所有文件)
- `workflow/issue/` (所有文件)
- `workflow/brainstorm/` (所有文件)
- `task/` (所有文件)
## 🎯 预期收益
### 可复用性提升
- **context:gather** 可用于快速分析、调试诊断等场景
- **analysis:run** 可服务于不同类型的分析需求
### 可维护性提升
- 单一职责，逻辑清晰
- 独立测试和调试
- 更容易定位问题
### 可扩展性提升
- 新增分析引擎无需修改协调器
- 支持不同的上下文源
- 便于添加缓存、并行等优化
### 开发体验提升
- 命令职责更清晰
- 调试更容易
- 功能扩展更简单
## ⚠️ 风险管控
### 兼容性风险
- **缓解措施**：保持最终输出格式不变
- **验证方案**：对比重构前后的IMPL_PLAN.md输出
### 性能风险
- **潜在影响**：模块调用可能增加执行时间
- **缓解措施**：优化模块间数据传递，避免重复读取
### 维护风险
- **潜在影响**：增加了命令间的依赖关系
- **缓解措施**：清晰的接口定义和错误处理
## 📈 成功标准
1. **功能完整性**：所有原有workflow功能正常工作
2. **输出一致性**：IMPL_PLAN.md等输出文件格式保持兼容
3. **性能可接受**：执行时间增幅不超过20%
4. **可维护性**：新模块代码清晰，易于理解和修改
5. **可复用性**：智能模块可在其他场景成功复用
---
## 📝 更新日志
### v1.1 - 2025-09-29
- **✅ 完成**: Session管理逻辑模块化
- **改进**: 将Session Discovery & Selection从pipeline/plan.md移动到session/start.md
- **增强**: pipeline/plan.md现在调用专用的session管理命令
- **优化**: 实现了更清晰的职责分离
### v1.0 - 2025-09-29
- **✅ 完成**: 基础模块化架构实施
- **✅ 完成**: 智能上下文和分析模块创建
- **✅ 完成**: 目录结构重组
---
**文档版本**: v1.1
**创建日期**: 2025-09-29
**最后更新**: 2025-09-29
**负责人**: Claude Code Assistant
**状态**: 已实施并优化

244
.claude/commands/enhance-prompt.md
View File

@@ -1,201 +1,117 @@
---
name: enhance-prompt
description: Dynamic prompt enhancement for complex requirements - Structured enhancement of user prompts before agent execution
description: Context-aware prompt enhancement using session memory and codebase analysis
usage: /enhance-prompt <user_input>
argument-hint: [--gemini] "user input to enhance"
argument-hint: "user input to enhance"
examples:
- /enhance-prompt "add user profile editing"
- /enhance-prompt "fix login button"
- /enhance-prompt "clean up the payment code"
---
### 🚀 **Command Overview: `/enhance-prompt`**
## Overview
- **Type**: Prompt Engineering Command
- **Purpose**: To systematically enhance raw user prompts, translating them into clear, context-rich, and actionable specifications before agent execution.
- **Key Feature**: Dynamically integrates with Gemini for deep, codebase-aware analysis.
Systematically enhances user prompts by combining session memory context with codebase patterns, translating ambiguous requests into actionable specifications.
### 📥 **Command Parameters**
## Core Protocol
- `<user_input>`: **(Required)** The raw text prompt from the user that needs enhancement.
- `--gemini`: **(Optional)** An explicit flag to force the full Gemini collaboration flow, ensuring codebase analysis is performed even for simple prompts.
**Enhancement Pipeline:**
`Intent Translation` → `Context Integration` → `Gemini Analysis (if needed)` → `Structured Output`
### 🔄 **Core Enhancement Protocol**
**Context Sources:**
- Session memory (conversation history, previous analysis)
- Codebase patterns (via Gemini when triggered)
- Implicit technical requirements
This is the standard pipeline every prompt goes through for structured enhancement.
`Step 1: Intent Translation` **->** `Step 2: Context Extraction` **->** `Step 3: Key Points Identification` **->** `Step 4: Optional Gemini Consultation`
### 🧠 **Gemini Collaboration Logic**
This logic determines when to invoke Gemini for deeper, codebase-aware insights.
## Gemini Trigger Logic
```pseudo
FUNCTION decide_enhancement_path(user_prompt, options):
// Set of keywords that indicate high complexity or architectural changes.
FUNCTION should_use_gemini(user_prompt):
critical_keywords = ["refactor", "migrate", "redesign", "auth", "payment", "security"]
// Conditions for triggering Gemini analysis.
use_gemini = FALSE
IF options.gemini_flag is TRUE:
use_gemini = TRUE
ELSE IF prompt_affects_multiple_modules(user_prompt, threshold=3):
use_gemini = TRUE
ELSE IF any_keyword_in_prompt(critical_keywords, user_prompt):
use_gemini = TRUE
// Execute the appropriate enhancement flow.
enhanced_prompt = run_standard_enhancement(user_prompt) // Steps 1-3
IF use_gemini is TRUE:
// This action corresponds to calling the Gemini CLI tool programmatically.
// e.g., `gemini --all-files -p "..."` based on the derived context.
gemini_insights = execute_tool("gemini","-P" enhanced_prompt) // Calls the Gemini CLI
enhanced_prompt.append(gemini_insights)
RETURN enhanced_prompt
END FUNCTION
RETURN (
prompt_affects_multiple_modules(user_prompt, threshold=3) OR
any_keyword_in_prompt(critical_keywords, user_prompt)
)
END
```
### 📚 **Enhancement Rules**
**Gemini Integration:** @~/.claude/workflows/intelligent-tools-strategy.md
- **Ambiguity Resolution**: Generic terms are translated into specific technical intents.
- `"fix"` → Identify the specific bug and preserve existing functionality.
- `"improve"` → Enhance performance or readability while maintaining compatibility.
- `"add"` → Implement a new feature and integrate it with existing code.
- `"refactor"` → Restructure code to improve quality while preserving external behavior.
- **Implicit Context Inference**: Missing technical context is automatically inferred.
```bash
# User: "add login"
# Inferred Context:
# - Authentication system implementation
# - Frontend login form + backend validation
# - Session management considerations
# - Security best practices (e.g., password handling)
```
- **Technical Translation**: Business goals are converted into technical specifications.
```bash
# User: "make it faster"
# Translated Intent:
# - Identify performance bottlenecks
# - Define target metrics/benchmarks
# - Profile before optimizing
# - Document performance gains and trade-offs
```
## Enhancement Rules
### 🗺️ **Enhancement Translation Matrix**
### Intent Translation
| User Says | → Translate To | Key Context | Focus Areas |
| ------------------ | ----------------------- | ----------------------- | --------------------------- |
| "make it work" | Fix functionality | Debug implementation | Root cause → fix → test |
| "add [feature]" | Implement capability | Integration points | Core function + edge cases |
| "improve [area]" | Optimize/enhance | Current limits | Measurable improvements |
| "fix [bug]" | Resolve issue | Bug symptoms | Root cause + prevention |
| "refactor [code]" | Restructure quality | Structure pain points | Maintain behavior |
| "update [component]" | Modernize | Version compatibility | Migration path |
| User Says | Translate To | Focus |
|-----------|--------------|-------|
| "fix" | Debug and resolve | Root cause → preserve behavior |
| "improve" | Enhance/optimize | Performance/readability |
| "add" | Implement feature | Integration + edge cases |
| "refactor" | Restructure quality | Maintain behavior |
| "update" | Modernize | Version compatibility |
### ⚡ **Automatic Invocation Triggers**
### Context Integration Strategy
The `/enhance-prompt` command is designed to run automatically when the system detects:
- Ambiguous user language (e.g., "fix", "improve", "clean up").
- Tasks impacting multiple modules or components (>3).
- Requests for system architecture changes.
- Modifications to critical systems (auth, payment, security).
- Complex refactoring requests.
**Session Memory First:**
- Reference recent conversation context
- Reuse previously identified patterns
- Build on established understanding
### 🛠️ **Gemini Integration Protocol (Internal)**
**Codebase Analysis (via Gemini):**
- Only when complexity requires it
- Focus on integration points
- Identify existing patterns
**Gemini Integration**: @~/.claude/workflows/intelligent-tools-strategy.md
This section details how the system programmatically interacts with the Gemini CLI.
- **Primary Tool**: All Gemini analysis is performed via direct calls to the `gemini` command-line tool (e.g., `gemini --all-files -p "..."`).
- **Central Guidelines**: All CLI usage patterns, syntax, and context detection rules are defined in the central guidelines document:
- **Template Selection**: For specific analysis types, the system references the template selection guide:
- **All Templates**: `gemini-template-rules.md` - provides guidance on selecting appropriate templates
- **Template Library**: `cli-templates/` - contains actual prompt and command templates
### 📝 **Enhancement Examples**
This card contains the original, unmodified examples to demonstrate the command's output.
#### Example 1: Feature Request (with Gemini Integration)
**Example:**
```bash
# User Input: "add user profile editing"
# Standard Enhancement:
TRANSLATED_INTENT: Implement user profile editing feature
DOMAIN_CONTEXT: User management system
ACTION_TYPE: Create new feature
COMPLEXITY: Medium (multi-component)
# Gemini Analysis Added:
GEMINI_PATTERN_ANALYSIS: FormValidator used in AccountSettings, PreferencesEditor
GEMINI_ARCHITECTURE: UserService → ProfileRepository → UserModel pattern
# Final Enhanced Structure:
ENRICHED_CONTEXT:
- Frontend: Profile form using FormValidator pattern
- Backend: API endpoints following UserService pattern
- Database: User model via ProfileRepository
- Auth: Permission checks using AuthGuard pattern
KEY_POINTS:
- Data validation using existing FormValidator
- Image upload via SecureUploadService
- Field permissions with AuthGuard middleware
ATTENTION_AREAS:
- Security: Use SecureUploadService for file handling
- Performance: Lazy loading patterns (ProfileImage.tsx)
# User: "add login"
# Session Memory: Previous auth discussion, JWT mentioned
# Inferred: JWT-based auth, integrate with existing session management
# Gemini (if multi-module): Analyze AuthService patterns, middleware structure
```
#### Example 2: Bug Fix
## Output Structure
```bash
# User Input: "login button doesn't work"
# Enhanced Structure:
TRANSLATED_INTENT: Debug and fix non-functional login button
DOMAIN_CONTEXT: Authentication UI
ACTION_TYPE: Fix bug
COMPLEXITY: Simple (single component)
KEY_POINTS:
- Identify root cause (event/state/API)
- Preserve existing auth flow
- Add error handling if missing
ATTENTION_AREAS:
- Don't break existing functionality
- Test edge cases and user states
INTENT: [Clear technical goal]
CONTEXT: [Session memory + codebase patterns]
ACTION: [Specific implementation steps]
ATTENTION: [Critical constraints]
```
#### Example 3: Refactoring Request
### Output Examples
**Simple (no Gemini):**
```bash
# User Input: "clean up the payment code"
# Enhanced Structure:
TRANSLATED_INTENT: Refactor payment module for maintainability
DOMAIN_CONTEXT: Payment processing system
ACTION_TYPE: Refactor
COMPLEXITY: Complex (critical system)
KEY_POINTS:
- Maintain exact functionality
- Improve code organization
- Extract reusable components
ATTENTION_AREAS:
- Critical: No behavior changes
- Security: Maintain PCI compliance
- Testing: Comprehensive coverage
# Input: "fix login button"
INTENT: Debug non-functional login button
CONTEXT: From session - OAuth flow discussed, known state issue
ACTION: Check event binding → verify state updates → test auth flow
ATTENTION: Preserve existing OAuth integration
```
### ✨ **Key Benefits**
**Complex (with Gemini):**
```bash
# Input: "refactor payment code"
INTENT: Restructure payment module for maintainability
CONTEXT: Session memory - PCI compliance requirements
Gemini - PaymentService → StripeAdapter pattern identified
ACTION: Extract reusable validators → isolate payment gateway logic
ATTENTION: Zero behavior change, maintain PCI compliance, full test coverage
```
1. **Clarity**: Ambiguous requests become clear specifications.
2. **Completeness**: Implicit requirements become explicit.
3. **Context**: Missing context is automatically inferred.
4. **Codebase Awareness**: Gemini provides actual patterns from the project.
5. **Quality**: Attention areas prevent common mistakes.
6. **Efficiency**: Agents receive structured, actionable input.
7. **Smart Flow Control**: Seamless integration with workflows.
## Automatic Triggers
- Ambiguous language: "fix", "improve", "clean up"
- Multi-module impact (>3 modules)
- Architecture changes
- Critical systems: auth, payment, security
- Complex refactoring
## Key Principles
1. **Memory First**: Leverage session context before analysis
2. **Minimal Gemini**: Only when complexity demands it
3. **Context Reuse**: Build on previous understanding
4. **Clear Output**: Structured, actionable specifications
5. **Avoid Duplication**: Reference existing context, don't repeat

235
.claude/commands/workflow/brainstorm/artifacts.md
View File

@@ -1,12 +1,12 @@
---
name: artifacts
description: Generate structured topic-framework.md for role-based brainstorming analysis
usage: /workflow:brainstorm:artifacts "<topic>"
description: Generate role-specific topic-framework.md dynamically based on selected roles
usage: /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
argument-hint: "topic or challenge description for framework generation"
examples:
- /workflow:brainstorm:artifacts "Build real-time collaboration feature"
- /workflow:brainstorm:artifacts "Optimize database performance for millions of users"
- /workflow:brainstorm:artifacts "Implement secure authentication system"
- /workflow:brainstorm:artifacts "Optimize database performance" --roles "system-architect,data-architect,security-expert"
- /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,security-expert,user-researcher"
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
---
@@ -14,11 +14,17 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
## Usage
```bash
/workflow:brainstorm:artifacts "<topic>"
/workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
```
## Purpose
**Specialized command for generating structured topic-framework.md documents** that provide discussion frameworks for role-based brainstorming analysis. Creates the foundation document that all role agents will reference.
**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas.
## Role-Based Framework Generation
**Dynamic Generation**: Framework content adapts based on selected roles
- **With roles**: Generate targeted discussion points for specified roles only
- **Without roles**: Generate comprehensive framework covering all common areas
## Core Workflow
@@ -30,22 +36,28 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists
- **Framework check**: Check if `topic-framework.md` exists (update vs create mode)
**Phase 2: Interactive Topic Analysis**
**Phase 2: Role Analysis** ⚠️ NEW
- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided
- **Role validation**: Verify each role is valid (matches available role commands)
- **Store role list**: Save selected roles to session metadata for reference
- **Default behavior**: If no roles specified, use comprehensive coverage
**Phase 3: Dynamic Topic Analysis**
- **Scope definition**: Define topic boundaries and objectives
- **Stakeholder identification**: Identify key users and stakeholders
- **Requirements gathering**: Extract core requirements and constraints
- **Context collection**: Gather technical and business context
- **Stakeholder identification**: Identify key users and stakeholders based on selected roles
- **Requirements gathering**: Extract requirements relevant to selected roles
- **Context collection**: Gather context appropriate for role perspectives
**Phase 3: Structured Framework Generation**
- **Discussion points creation**: Generate 5 key discussion areas
- **Role-specific questions**: Create tailored questions for each relevant role
- **Framework document**: Generate structured `topic-framework.md`
- **Validation check**: Ensure framework completeness and clarity
**Phase 4: Role-Specific Framework Generation**
- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles**
- **Role-targeted questions**: Create questions specifically for chosen roles
- **Framework document**: Generate `topic-framework.md` with role-specific sections
- **Validation check**: Ensure framework addresses all selected role perspectives
**Phase 4: Update Mechanism**
- **Existing framework detection**: Check for existing framework
- **Incremental updates**: Add new discussion points if requested
- **Version tracking**: Maintain framework evolution history
**Phase 5: Metadata Storage**
- **Save role assignment**: Store selected roles in session metadata
- **Framework versioning**: Track which roles framework addresses
- **Update tracking**: Maintain role evolution if framework updated
## Implementation Standards
@@ -83,68 +95,181 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
└── workflow-session.json # Framework metadata and role assignments
```
**Topic Framework Template**:
## Framework Template Structures
### topic-framework.md Structure
### Dynamic Role-Based Framework
Framework content adapts based on `--roles` parameter:
#### Option 1: Specific Roles Provided
```markdown
# [Topic] - Discussion Framework
## Topic Overview
- **Scope**: [Clear topic boundaries and scope definition]
- **Objectives**: [Primary goals and expected outcomes]
- **Context**: [Relevant background and constraints]
- **Stakeholders**: [Key users, roles, and affected parties]
- **Scope**: [Topic boundaries relevant to selected roles]
- **Objectives**: [Goals from perspective of selected roles]
- **Context**: [Background focusing on role-specific concerns]
- **Target Roles**: ui-designer, system-architect, security-expert
## Key Discussion Points
## Role-Specific Discussion Points
### 1. Core Requirements
### For UI Designer
1. **User Interface Requirements**
- What interface components are needed?
- What user interactions must be supported?
- What visual design considerations apply?
2. **User Experience Challenges**
- What are the key user journeys?
- What accessibility requirements exist?
- How to balance aesthetics with functionality?
### For System Architect
1. **Architecture Decisions**
- What architectural patterns fit this solution?
- What scalability requirements exist?
- How does this integrate with existing systems?
2. **Technical Implementation**
- What technology stack is appropriate?
- What are the performance requirements?
- What dependencies must be managed?
### For Security Expert
1. **Security Requirements**
- What are the key security concerns?
- What threat vectors must be addressed?
- What compliance requirements apply?
2. **Security Implementation**
- What authentication/authorization is needed?
- What data protection mechanisms are required?
- How to handle security incidents?
## Cross-Role Integration Points
- How do UI decisions impact architecture?
- How does architecture constrain UI possibilities?
- What security requirements affect both UI and architecture?
## Framework Usage
**For Role Agents**: Address your specific section + integration points
**Reference Format**: @../topic-framework.md in your analysis.md
**Update Process**: Use /workflow:brainstorm:artifacts to update
---
*Generated for roles: ui-designer, system-architect, security-expert*
*Last updated: [timestamp]*
```
#### Option 2: No Roles Specified (Comprehensive)
```markdown
# [Topic] - Discussion Framework
## Topic Overview
- **Scope**: [Comprehensive topic boundaries]
- **Objectives**: [All-encompassing goals]
- **Context**: [Full background and constraints]
- **Stakeholders**: [All relevant parties]
## Core Discussion Areas
### 1. Requirements & Objectives
- What are the fundamental requirements?
- What are the critical success factors?
- What constraints must be considered?
- What acceptance criteria define success?
### 2. Technical Considerations
### 2. Technical & Architecture
- What are the technical challenges?
- What architectural decisions are needed?
- What technology choices impact the solution?
- What integration points exist?
### 3. User Experience Factors
### 3. User Experience & Design
- Who are the primary users?
- What are the key user journeys?
- What usability requirements exist?
- What accessibility considerations apply?
### 4. Implementation Challenges
- What are the main implementation risks?
- What dependencies exist?
### 4. Security & Compliance
- What security requirements exist?
- What compliance considerations apply?
- What data protection is needed?
### 5. Implementation & Operations
- What are the implementation risks?
- What resources are required?
- What timeline constraints apply?
- How will this be maintained?
### 5. Success Metrics
- How will success be measured?
- What are the acceptance criteria?
- What performance requirements exist?
- What monitoring and analytics are needed?
## Role-Specific Analysis Points
- **System Architect**: Architecture patterns, scalability, technology stack
- **Product Manager**: Business value, user needs, market positioning
- **UI Designer**: User experience, interface design, usability
- **Security Expert**: Security requirements, threat modeling, compliance
- **Data Architect**: Data modeling, processing workflows, analytics
- **Business Analyst**: Process optimization, cost-benefit, change management
## Framework Usage Instructions
**For Role Agents**: Address each discussion point from your role perspective
**Reference Format**: Use @../topic-framework.md in your analysis.md
**Update Process**: Use /workflow:brainstorm:artifacts to update framework
## Available Role Perspectives
Framework supports analysis from any of these roles:
- system-architect, ui-designer, security-expert
- user-researcher, product-manager, business-analyst
- data-architect, innovation-lead, feature-planner
---
*Generated by /workflow:brainstorm:artifacts*
*Comprehensive framework - adaptable to any role*
*Last updated: [timestamp]*
```
## Role-Specific Content Generation
### Available Roles and Their Focus Areas
**Technical Roles**:
- `system-architect`: Architecture patterns, scalability, technology stack, integration
- `data-architect`: Data modeling, processing workflows, analytics, storage
- `security-expert`: Security requirements, threat modeling, compliance, protection
**Product & Design Roles**:
- `ui-designer`: User interface, visual design, interaction patterns, accessibility
- `user-researcher`: User needs, behavior analysis, usability testing, personas
- `product-manager`: Business value, feature prioritization, market positioning, roadmap
**Business Roles**:
- `business-analyst`: Process optimization, requirements analysis, cost-benefit, ROI
- `innovation-lead`: Emerging technologies, competitive advantage, transformation, trends
- `feature-planner`: Feature specification, user stories, acceptance criteria, dependencies
### Dynamic Discussion Point Generation
**For each selected role, generate**:
1. **2-3 core discussion areas** specific to that role's perspective
2. **3-5 targeted questions** per discussion area
3. **Cross-role integration points** showing how roles interact
**Example mapping**:
```javascript
// If roles = ["ui-designer", "system-architect"]
Generate:
- UI Designer section: UI Requirements, UX Challenges
- System Architect section: Architecture Decisions, Technical Implementation
- Integration Points: UI↔Architecture dependencies
```
### Framework Generation Examples
#### Example 1: Architecture-Heavy Topic
```bash
/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,security-expert"
```
**Generated framework focuses on**:
- Service architecture and communication patterns
- Data flow and storage strategies
- Security boundaries and authentication
#### Example 2: User-Focused Topic
```bash
/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,user-researcher,product-manager"
```
**Generated framework focuses on**:
- Onboarding flow and UI components
- User behavior and pain points
- Business value and success metrics
#### Example 3: Comprehensive Analysis
```bash
/workflow:brainstorm:artifacts "Build real-time collaboration feature"
```
**Generated framework covers** all aspects (no roles specified)
## Session Management ⚠️ CRITICAL
- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing
- **Multiple sessions support**: Different Claude instances can have different active sessions

24
.claude/commands/workflow/brainstorm/auto-parallel.md
View File

@@ -40,7 +40,9 @@ bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
The command follows a structured three-phase approach with dedicated document types:
**Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}"` using SlashCommand tool
- **Role selection**: Auto-select 2-3 roles based on topic keywords (see Role Selection Logic)
- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"` using SlashCommand tool
- **Role-specific framework**: Generate framework with sections tailored to selected roles
**Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
- **Parallel execution**: Multiple roles execute simultaneously for faster completion
@@ -58,15 +60,15 @@ The command follows a structured three-phase approach with dedicated document ty
Auto command coordinates independent specialized commands:
**Command Sequence**:
1. **Generate Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}"`
2. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
3. **Role Analysis**: Execute selected role commands in parallel
1. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"`
3. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading their specific framework section
4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis`
**SlashCommand Integration**:
1. **artifacts command**: Called via SlashCommand tool for framework generation
2. **role commands**: Each role command operates in parallel with framework reference
3. **synthesis command**: Called via SlashCommand tool for final integration
1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
2. **role agents**: Each agent reads its dedicated section in the role-specific framework
3. **synthesis command**: Called via SlashCommand tool for final integration with role-targeted insights
4. **Command coordination**: SlashCommand handles execution and validation
**Role Selection Logic**:
@@ -211,14 +213,14 @@ TodoWrite({
activeForm: "Initializing brainstorming session"
},
{
content: "Execute artifacts command using SlashCommand for framework generation",
content: "Select roles based on topic keyword analysis",
status: "pending",
activeForm: "Executing artifacts command for topic framework"
activeForm: "Selecting roles for brainstorming analysis"
},
{
content: "Select roles and create workflow-session.json with framework references",
content: "Execute artifacts command with selected roles for role-specific framework",
status: "pending",
activeForm: "Selecting roles and creating session metadata"
activeForm: "Generating role-specific topic framework"
},
{
content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",

374
.claude/commands/workflow/brainstorm/auto-squeeze.md
View File

@@ -1,6 +1,6 @@
---
name: auto-squeeze
description: Sequential command coordination for brainstorming workflow commands
description: Orchestrate 3-phase brainstorming workflow by executing commands sequentially
usage: /workflow:brainstorm:auto-squeeze "<topic>"
argument-hint: "topic or challenge description for coordinated brainstorming"
examples:
@@ -10,187 +10,249 @@ examples:
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
---
# Sequential Auto Brainstorming Coordination Command
# Workflow Brainstorm Auto-Squeeze Command
## Usage
```bash
/workflow:brainstorm:auto-squeeze "<topic>"
```
## Coordinator Role
## Purpose
**Sequential command coordination for brainstorming workflow** by calling existing brainstorm commands using SlashCommand tool. This command orchestrates the complete brainstorming workflow from framework generation to synthesis in sequential order.
**This command is a pure orchestrator**: Execute brainstorming commands in sequence (artifacts → roles → synthesis), auto-select relevant roles, and ensure complete brainstorming workflow execution.
## Command Coordination Workflow
**Execution Flow**:
1. Initialize TodoWrite → Execute Phase 1 (artifacts) → Validate framework → Update TodoWrite
2. Select 2-3 relevant roles → Display selection → Execute Phase 2 (role analyses) → Update TodoWrite
3. Execute Phase 3 (synthesis) → Validate outputs → Return summary
## Core Rules
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
2. **Auto-Select Roles**: Analyze topic keywords to select 2-3 most relevant roles (max 3)
3. **Display Selection**: Show selected roles to user before execution
4. **Sequential Execution**: Execute role commands one by one, not in parallel
5. **Complete All Phases**: Do not return to user until synthesis completes
6. **Track Progress**: Update TodoWrite after every command completion
## 3-Phase Execution
### Phase 1: Framework Generation
1. **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}"`
2. **Verify framework creation**: Check for topic-framework.md existence
3. **Session validation**: Ensure active session continuity
### Phase 2: Role Analysis Coordination
1. **Role selection**: Auto-select 2-3 relevant roles based on topic keywords
2. **Display selected roles**: Clearly list the chosen roles before execution
```
Selected roles for analysis:
- ui-designer (UI/UX perspective)
- system-architect (Technical architecture)
- security-expert (Security considerations)
```
3. **Sequential execution**: Call each role command using SlashCommand
4. **Progress monitoring**: Track completion of each role analysis
5. **Role execution order**:
- `/workflow:brainstorm:ui-designer` - UI/UX perspective
- `/workflow:brainstorm:system-architect` - Technical architecture
- `/workflow:brainstorm:security-expert` - Security considerations
**Step 1.1: Role Selection**
Auto-select 2-3 roles based on topic keywords (see Role Selection Logic below)
### Phase 3: Synthesis Coordination
1. **Completion verification**: Ensure all role analyses are complete
2. **Call synthesis command**: Execute `/workflow:brainstorm:synthesis`
3. **Final validation**: Verify synthesis document creation
**Step 1.2: Generate Role-Specific Framework**
**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"[topic]\" --roles \"[role1,role2,role3]\"")`
## Role Selection Logic
**Input**: Selected roles from step 1.1
### Keyword-Based Role Mapping
- **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert
- **Product & UX**: `user|ui|ux|interface|design|product|feature` → ui-designer, user-researcher, product-manager
- **Business & Process**: `business|process|workflow|cost|innovation` → business-analyst, innovation-lead
- **Default fallback**: ui-designer if no clear match
**Parse Output**:
- Verify topic-framework.md created with role-specific sections
### Auto-Selection Rules
- **Maximum 3 roles**: Select most relevant based on topic analysis
- **Priority ordering**: Most relevant role first
- **Coverage ensure**: Include complementary perspectives
**Validation**:
- File `.workflow/[session]/.brainstorming/topic-framework.md` exists
- Contains sections for each selected role
- Includes cross-role integration points
## Implementation Protocol
**TodoWrite**: Mark phase 1 completed, mark "Display selected roles" as in_progress
### Sequential Command Execution
```bash
# Phase 1: Generate framework
SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\"")
---
# Display selected roles
echo "Selected roles for analysis:"
echo "- ui-designer (UI/UX perspective)"
echo "- system-architect (Technical architecture)"
echo "- security-expert (Security considerations)"
### Phase 2: Role Analysis Execution
# Phase 2: Execute selected roles sequentially
SlashCommand(command="/workflow:brainstorm:ui-designer")
SlashCommand(command="/workflow:brainstorm:system-architect")
SlashCommand(command="/workflow:brainstorm:security-expert")
**Step 2.1: Role Selection**
Use keyword analysis to auto-select 2-3 roles:
# Phase 3: Generate synthesis
SlashCommand(command="/workflow:brainstorm:synthesis")
**Role Selection Logic**:
- **Technical/Architecture keywords**: `architecture|system|performance|database|api|backend|scalability`
→ system-architect, data-architect, security-expert
- **UI/UX keywords**: `user|ui|ux|interface|design|frontend|experience`
→ ui-designer, user-researcher
- **Product/Business keywords**: `product|feature|business|workflow|process|customer`
→ product-manager, business-analyst
- **Security keywords**: `security|auth|permission|encryption|compliance`
→ security-expert
- **Innovation keywords**: `innovation|new|disrupt|transform|emerging`
→ innovation-lead
- **Default**: ui-designer (if no clear match)
**Selection Rules**:
- Maximum 3 roles
- Select most relevant role first based on strongest keyword match
- Include complementary perspectives (e.g., if system-architect selected, also consider security-expert)
**Step 2.2: Display Selected Roles**
Show selection to user before execution:
```
Selected roles for analysis:
- ui-designer (UI/UX perspective)
- system-architect (Technical architecture)
- security-expert (Security considerations)
```
### Progress Tracking
**Step 2.3: Execute Role Commands Sequentially**
Execute each selected role command one by one:
**Commands**:
- `SlashCommand(command="/workflow:brainstorm:ui-designer")`
- `SlashCommand(command="/workflow:brainstorm:system-architect")`
- `SlashCommand(command="/workflow:brainstorm:security-expert")`
- `SlashCommand(command="/workflow:brainstorm:user-researcher")`
- `SlashCommand(command="/workflow:brainstorm:product-manager")`
- `SlashCommand(command="/workflow:brainstorm:business-analyst")`
- `SlashCommand(command="/workflow:brainstorm:data-architect")`
- `SlashCommand(command="/workflow:brainstorm:innovation-lead")`
- `SlashCommand(command="/workflow:brainstorm:feature-planner")`
**Validation** (after each role):
- File `.workflow/[session]/.brainstorming/[role]/analysis.md` exists
- Contains role-specific analysis
**TodoWrite**: Mark each role task completed after execution, start next role as in_progress
---
### Phase 3: Synthesis Generation
**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis")`
**Validation**:
- File `.workflow/[session]/.brainstorming/synthesis-report.md` exists
- Contains cross-references to role analyses using @ notation
**TodoWrite**: Mark phase 3 completed
**Return to User**:
```
Brainstorming complete for topic: [topic]
Framework: .workflow/[session]/.brainstorming/topic-framework.md
Roles analyzed: [role1], [role2], [role3]
Synthesis: .workflow/[session]/.brainstorming/synthesis-report.md
```
## TodoWrite Pattern
```javascript
TodoWrite({
todos: [
{
content: "Generate topic framework using artifacts command",
status: "in_progress",
activeForm: "Generating topic framework"
},
{
content: "Display selected roles: ui-designer, system-architect, security-expert",
status: "pending",
activeForm: "Displaying selected roles for analysis"
},
{
content: "Execute ui-designer role analysis",
status: "pending",
activeForm: "Executing ui-designer analysis"
},
{
content: "Execute system-architect role analysis",
status: "pending",
activeForm: "Executing system-architect analysis"
},
{
content: "Execute security-expert role analysis",
status: "pending",
activeForm: "Executing security-expert analysis"
},
{
content: "Generate synthesis report",
status: "pending",
activeForm: "Generating synthesis report"
}
]
});
// Initialize (before Phase 1)
TodoWrite({todos: [
{"content": "Generate topic framework", "status": "in_progress", "activeForm": "Generating topic framework"},
{"content": "Display selected roles", "status": "pending", "activeForm": "Displaying selected roles"},
{"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
{"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
{"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
{"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
]})
// After Phase 1
TodoWrite({todos: [
{"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
{"content": "Display selected roles", "status": "in_progress", "activeForm": "Displaying selected roles"},
{"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
{"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
{"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
{"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
]})
// After displaying roles
TodoWrite({todos: [
{"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
{"content": "Display selected roles", "status": "completed", "activeForm": "Displaying selected roles"},
{"content": "Execute ui-designer analysis", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
{"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
{"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
{"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
]})
// Continue pattern for each role and synthesis...
```
### Verification Steps
Between each phase:
1. **Check command completion**: Verify previous command finished successfully
2. **Validate outputs**: Ensure expected files were created
3. **Update progress**: Mark current task complete, start next task
4. **Error handling**: Stop workflow if any command fails
## Data Flow
```
User Input (topic)
↓
Role Selection (analyze topic keywords)
↓ Output: 2-3 selected roles (e.g., ui-designer, system-architect, security-expert)
↓
Phase 1: artifacts "topic" --roles "role1,role2,role3"
↓ Input: topic + selected roles
↓ Output: role-specific topic-framework.md
↓
Display: Show selected roles to user
↓
Phase 2: Execute each role command sequentially
↓ Role 1 → reads role-specific section → analysis.md
↓ Role 2 → reads role-specific section → analysis.md
↓ Role 3 → reads role-specific section → analysis.md
↓
Phase 3: synthesis
↓ Input: role-specific framework + all role analyses
↓ Output: synthesis-report.md with role-targeted insights
↓
Return summary to user
```
**Session Context**: All commands use active brainstorming session, sharing:
- Role-specific topic framework
- Role-targeted analyses
- Cross-role integration points
- Synthesis with role-specific insights
**Key Improvement**: Framework is generated with roles parameter, ensuring all discussion points are relevant to selected roles
## Role Selection Examples
### Example 1: UI-Focused Topic
**Topic**: "Redesign user authentication interface"
**Keywords detected**: user, interface, design
**Selected roles**:
- ui-designer (primary: UI/UX match)
- user-researcher (secondary: user experience)
- security-expert (complementary: auth security)
### Example 2: Architecture Topic
**Topic**: "Design scalable microservices architecture"
**Keywords detected**: architecture, scalable, system
**Selected roles**:
- system-architect (primary: architecture match)
- data-architect (secondary: scalability/data)
- security-expert (complementary: system security)
### Example 3: Business Process Topic
**Topic**: "Optimize customer onboarding workflow"
**Keywords detected**: workflow, process, customer
**Selected roles**:
- business-analyst (primary: process match)
- product-manager (secondary: customer focus)
- ui-designer (complementary: user experience)
## Error Handling
### Command Failure Recovery
- **Framework generation fails**: Stop workflow, report error
- **Role analysis fails**: Continue with remaining roles, note failure
- **Synthesis fails**: Attempt retry once, then report partial completion
- **Framework Generation Failure**: Stop workflow, report error, do not proceed to role selection
- **Role Analysis Failure**: Log failure, continue with remaining roles, note in final summary
- **Synthesis Failure**: Retry once, if still fails report partial completion with available analyses
- **Session Error**: Report session issue, prompt user to check session status
### Session Management
- **Active session required**: Use existing session or create new one
- **Session continuity**: Maintain same session throughout workflow
- **Multi-session handling**: Prompt user if multiple active sessions
## Expected Output Structure
## Output Structure
```
.workflow/WFS-{session}/.brainstorming/
├── topic-framework.md # Generated by artifacts command
├── ui-designer/
│ └── analysis.md # Generated by ui-designer command
├── system-architect/
│ └── analysis.md # Generated by system-architect command
├── security-expert/
│ └── analysis.md # Generated by security-expert command
└── synthesis-report.md # Generated by synthesis command
.workflow/[session]/.brainstorming/
├── topic-framework.md # Phase 1 output
├── [role1]/
│ └── analysis.md # Phase 2 output (role 1)
├── [role2]/
│ └── analysis.md # Phase 2 output (role 2)
├── [role3]/
│ └── analysis.md # Phase 2 output (role 3)
└── synthesis-report.md # Phase 3 output
```
## Test Scenarios
## Coordinator Checklist
### Test Case 1: UI/UX Focus Topic
**Topic**: "Redesign user authentication interface"
**Expected roles**: ui-designer, user-researcher, security-expert
**Validation**: Check UI-focused analysis in each role output
### Test Case 2: Technical Architecture Topic
**Topic**: "Design scalable microservices architecture"
**Expected roles**: system-architect, data-architect, security-expert
**Validation**: Check technical depth in architecture analysis
### Test Case 3: Business Process Topic
**Topic**: "Optimize customer onboarding workflow"
**Expected roles**: business-analyst, product-manager, ui-designer
**Validation**: Check business process focus in analysis
## Quality Assurance
### Command Integration Verification
- **All commands execute independently**: Each command handles its own validation
- **No direct dependencies**: Commands work with framework reference
- **Consistent session usage**: All commands use same session directory
- **Proper error propagation**: Failed commands don't break workflow
### Output Quality Checks
- **Framework completeness**: topic-framework.md has all required sections
- **Role analysis depth**: Each role provides substantial analysis
- **Synthesis integration**: synthesis-report.md references all role analyses
- **Cross-references work**: @ notation links function correctly
## Success Criteria
1. **Complete workflow execution**: All phases complete without errors
2. **Proper file generation**: All expected output files created
3. **Content quality**: Each document contains substantial, relevant analysis
4. **Integration validation**: Synthesis properly references all role analyses
5. **Session consistency**: All outputs in correct session directory
---
*Sequential command coordination for brainstorming workflow*
✅ Initialize TodoWrite with framework + display + N roles + synthesis tasks
✅ Execute Phase 1 (artifacts) immediately
✅ Validate topic-framework.md exists
✅ Analyze topic keywords for role selection
✅ Auto-select 2-3 most relevant roles (max 3)
✅ Display selected roles to user with rationale
✅ Execute each role command sequentially
✅ Validate each role's analysis.md after execution
✅ Update TodoWrite after each role completion
✅ Execute Phase 3 (synthesis) after all roles complete
✅ Validate synthesis-report.md exists
✅ Return summary with all generated files

302
.claude/commands/workflow/plan.md
View File

@@ -1,6 +1,6 @@
---
name: plan
description: Create implementation plans by orchestrating intelligent context gathering and analysis modules
description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
usage: /workflow:plan [--agent] <input>
argument-hint: "[--agent] \"text description\"|file.md|ISS-001"
examples:
@@ -8,215 +8,175 @@ examples:
- /workflow:plan --agent "Build authentication system"
- /workflow:plan requirements.md
- /workflow:plan ISS-001
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# Workflow Plan Command (/workflow:plan)
## Overview
Creates comprehensive implementation plans by orchestrating intelligent context gathering and analysis modules. Integrates with workflow session management, brainstorming artifacts, and automated task generation.
## Coordinator Role
**This command is a pure orchestrator**: Execute 4 slash commands in sequence, parse their outputs, pass context between them, and ensure complete execution.
**Execution Flow**:
1. Initialize TodoWrite → Execute Phase 1 → Parse output → Update TodoWrite
2. Execute Phase 2 with Phase 1 data → Parse output → Update TodoWrite
3. Execute Phase 3 with Phase 2 data → Parse output → Update TodoWrite
4. Execute Phase 4 with Phase 3 validation → Update TodoWrite → Return summary
**Execution Modes**:
- **Manual Mode** (default): Command-driven task generation with phase-by-phase control
- **Agent Mode** (`--agent`): Autonomous agent-driven task generation using action-planning-agent
- **Manual Mode** (default): Use `/workflow:tools:task-generate`
- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
## Core Planning Principles
## Core Rules
**⚡ Autonomous Execution Mandate**: Complete all planning phases sequentially without user interruption—from session initialization through task generation—ensuring full workflow integrity.
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's output 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 4 completes
6. **Track Progress**: Update TodoWrite after every phase completion
### Task Decomposition Standards
## 4-Phase Execution
**Core Principle: Task Merging Over Decomposition**
- **Merge Rule**: Tasks that can be executed together should not be separated - avoid unnecessary decomposition
- **Decomposition Criteria**: Only decompose tasks in the following situations:
- **Excessive Workload**: Code exceeds 2500 lines or modifies more than 6 files
- **Context Separation**: Involves completely different tech stacks or business domains
- **Dependency Blocking**: Subsequent tasks must wait for prerequisite task completion
- **Parallel Execution**: Independent features that can be developed simultaneously by different developers
### Phase 1: Session Discovery
**Command**: `SlashCommand(command="/workflow:session:start --auto \"[task-description]\"")`
**Task Limits & Structure**:
- **Maximum 10 tasks**: Hard limit - exceeding requires re-scoping
- **Function-based**: Complete functional units with related files (logic + UI + tests + config)
- **File cohesion**: Group tightly coupled components in same task
- **Hierarchy**: Flat (≤5 tasks) | Two-level (6-10 tasks) | Re-scope (>10 tasks)
**Parse Output**:
- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`)
**Task Pattern Examples**:
- ✅ **Correct (Function-based)**: `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
- ❌ **Wrong (File/step-based)**: `IMPL-001: Create database model`, `IMPL-002: Create API endpoint`
**Validation**:
- Session ID successfully extracted
- Session directory `.workflow/[sessionId]/` exists
### Task JSON Creation Process
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
**Task JSON Generation Philosophy**:
1. **Analysis-Driven**: Task definitions generated from intelligent analysis results
2. **Context-Rich**: Each task includes comprehensive context for autonomous execution
3. **Flow-Control Ready**: Pre-analysis steps and implementation approach pre-defined
4. **Agent-Optimized**: Complete context provided for specialized agent execution
5. **Artifacts-Integrated**: Automatically detect and reference brainstorming artifacts
6. **Design-Context-Aware**: Ensure design documents are loaded in pre_analysis steps
---
**Automatic Task Generation Workflow**:
1. **Parse Analysis Results**: Extract task recommendations from ANALYSIS_RESULTS.md
2. **Extract Task Details**: Parse task ID, title, scope, complexity from structured analysis
3. **Detect Brainstorming Artifacts**: Scan for ui-designer, system-architect, and other role outputs
4. **Generate Context**: Create requirements, focus_paths, acceptance criteria, and artifacts references
5. **Build Enhanced Flow Control**: Define pre_analysis steps with artifact loading and implementation approach
6. **Create Artifact-Aware JSON Files**: Generate individual .task/IMPL-*.json files with enhanced schema
### Phase 2: Context Gathering
**Command**: `SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"[task-description]\"")`
## Critical Process Requirements
**Input**: `sessionId` from Phase 1
### Session Management ⚠️ CRITICAL FIRST STEP
- **⚡ FIRST ACTION**: Execute `SlashCommand(command="/workflow:session:start --auto \"[task-description]\"")` for intelligent session discovery
- **Command Integration**: Uses `/workflow:session:start --auto` for automated session discovery and creation
- **Auto Mode Behavior**: Automatically analyzes relevance and selects/creates appropriate session
- **Relevance Analysis**: Keyword-based matching between task description and existing session projects
- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists or task is unrelated
- **Session continuity**: MUST use selected active session to maintain context
- **⚠️ Dependency context**: MUST read ALL previous task summary documents from selected session before planning
- **Session isolation**: Each session maintains independent context and state
- **Output Parsing**: Extract session ID from output line matching pattern `SESSION_ID: WFS-[id]`
**Parse Output**:
- Extract: context-package.json path (store as `contextPath`)
- Typical pattern: `.workflow/[sessionId]/.context/context-package.json`
### Session ID Transmission Guidelines ⚠️ CRITICAL
- **Format**: `WFS-[topic-slug]` from active session markers
- **Usage**: `SlashCommand(command="/workflow:tools:context-gather --session WFS-[id]")` and `SlashCommand(command="/workflow:tools:concept-enhanced --session WFS-[id]")`
- **Rule**: ALL modular commands MUST receive current session ID for context continuity
**Validation**:
- Context package path extracted
- File exists and is valid JSON
### Brainstorming Artifacts Integration ⚠️ NEW FEATURE
- **Artifact Detection**: Automatically scan .brainstorming/ directory for role outputs
- **Role-Task Mapping**: Map brainstorming roles to task types (ui-designer → UI tasks)
- **Artifact References**: Create structured references to design documents and specifications
- **Context Enhancement**: Load artifacts in pre_analysis steps to provide complete design context
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
## Planning Execution Lifecycle
---
### Phase 1: Session Management & Discovery ⚠️ TodoWrite Control
1. **TodoWrite Initialization**: Initialize flow control, mark first phase as `in_progress`
2. **Session Discovery**: Execute `SlashCommand(command="/workflow:session:start --auto \"[task-description]\"")`
3. **Parse Session ID**: Extract session ID from command output matching pattern `SESSION_ID: WFS-[id]`
4. **Validate Session**: Verify session directory structure and metadata exist
5. **Context Preparation**: Load session state and prepare for planning
6. **TodoWrite Update**: Mark phase 1 as `completed`, phase 2 as `in_progress`
### Phase 3: Intelligent Analysis
**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")`
**Note**: The `--auto` flag enables automatic relevance analysis and session selection/creation without user interaction.
**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2
### Phase 2: Context Gathering & Asset Discovery ⚠️ TodoWrite Control
1. **Context Collection**: Execute `SlashCommand(command="/workflow:tools:context-gather --session WFS-[id] \"task description\"")`
2. **Asset Discovery**: Gather relevant documentation, code, and configuration files
3. **Context Packaging**: Generate standardized context-package.json
4. **Validation**: Ensure context package contains sufficient information for analysis
5. **TodoWrite Update**: Mark phase 2 as `completed`, phase 3 as `in_progress`
**Parse Output**:
- Verify ANALYSIS_RESULTS.md created
### Phase 3: Intelligent Analysis & Tool Orchestration ⚠️ TodoWrite Control
1. **Analysis Execution**: Execute `SlashCommand(command="/workflow:tools:concept-enhanced --session WFS-[id] --context path/to/context-package.json")` (delegated to independent concept-enhanced command)
2. **Context Passing**: Pass session ID and context package path from Phase 2 to enable comprehensive analysis
3. **Result Generation**: Produce structured ANALYSIS_RESULTS.md with task recommendations via concept-enhanced command
4. **Validation**: Verify analysis completeness and task recommendations from concept-enhanced output
5. **TodoWrite Update**: Mark phase 3 as `completed`, phase 4 as `in_progress`
**Validation**:
- File `.workflow/[sessionId]/ANALYSIS_RESULTS.md` exists
- Contains task recommendations section
### Phase 4: Plan Assembly & Artifact Integration ⚠️ TodoWrite Control
**Delegated to**:
- Manual Mode: `/workflow:tools:task-generate --session WFS-[id]`
- Agent Mode: `/workflow:tools:task-generate-agent --session WFS-[id]`
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
Execute task generation command to:
1. **Artifact Detection**: Scan session for brainstorming outputs (.brainstorming/ directory)
2. **Plan Generation**: Create IMPL_PLAN.md from analysis results and artifacts
3. **Enhanced Task JSON Creation**: Generate task JSON files with artifacts integration (5-field schema)
4. **TODO List Creation**: Generate TODO_LIST.md with artifact references
5. **Session Update**: Mark session as ready for execution with artifact context
6. **TodoWrite Completion Validation**: Ensure all phases are marked as `completed` for complete execution
---
**Command Execution**:
```bash
# Manual Mode (default)
SlashCommand(command="/workflow:tools:task-generate --session WFS-[id]")
### Phase 4: Task Generation
**Command**:
- Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
- Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
# Agent Mode (if --agent flag provided)
SlashCommand(command="/workflow:tools:task-generate-agent --session WFS-[id]")
**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
Next: /workflow:execute or /workflow:status
```
**Reference Documentation**:
- Manual: `@.claude/commands/workflow/tools/task-generate.md`
- Agent: `@.claude/commands/workflow/tools/task-generate-agent.md`
## TodoWrite Progress Tracking ⚠️ CRITICAL FLOW CONTROL
**TodoWrite Control Ensures Complete Workflow Execution** - Guarantees planning lifecycle integrity through real-time status tracking:
### TodoWrite Flow Control Rules ⚠️ MANDATORY
1. **Process Integrity Guarantee**: TodoWrite is the key control mechanism ensuring all planning phases execute in sequence
2. **Phase Gating**: Must wait for previous phase `completed` before starting next phase
3. **SlashCommand Synchronization**: Update TodoWrite status before and after each SlashCommand execution
4. **Error Recovery**: If phase fails, TodoWrite maintains `in_progress` status until issue resolved
5. **Process Validation**: Verify all required phases completed through TodoWrite
### TodoWrite Execution Control Rules
1. **Initial Creation**: Generate TodoWrite task list from planning phases
2. **Single Execution**: Only one task can be `in_progress` at any time
3. **Immediate Updates**: Update status to `completed` immediately after each phase completion
4. **Continuous Tracking**: Maintain TodoWrite state throughout entire planning workflow
5. **Integrity Validation**: Final verification that all tasks are `completed` status
### TodoWrite Tool Usage
**Core Control Rule**: Monitor SlashCommand completion status to ensure sequential execution
## TodoWrite Pattern
```javascript
// Flow Control Example: Ensure Complete Execution of All Planning Phases
// Step 1: Initialize Flow Control
TodoWrite({
todos: [
{"content": "Initialize session management and discovery", "status": "in_progress", "activeForm": "Initializing session management and discovery"},
{"content": "Detect and analyze brainstorming artifacts", "status": "pending", "activeForm": "Detecting and analyzing brainstorming artifacts"},
{"content": "Gather intelligent context and assets", "status": "pending", "activeForm": "Gathering intelligent context and assets"},
{"content": "Execute intelligent analysis and tool orchestration", "status": "pending", "activeForm": "Executing intelligent analysis and tool orchestration"},
{"content": "Generate artifact-enhanced implementation plan and tasks", "status": "pending", "activeForm": "Generating artifact-enhanced implementation plan and tasks"}
]
})
// Initialize (before Phase 1)
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 intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
{"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})
// Step 2: Execute SlashCommand and Update Status Immediately
SlashCommand(command="/workflow:session:start --auto \"task-description\"")
// After command completion:
TodoWrite({
todos: [
{"content": "Initialize session management and discovery", "status": "completed", "activeForm": "Initializing session management and discovery"},
{"content": "Detect and analyze brainstorming artifacts", "status": "in_progress", "activeForm": "Detecting and analyzing brainstorming artifacts"},
{"content": "Gather intelligent context and assets", "status": "pending", "activeForm": "Gathering intelligent context and assets"},
{"content": "Execute intelligent analysis and tool orchestration", "status": "pending", "activeForm": "Executing intelligent analysis and tool orchestration"},
{"content": "Generate artifact-enhanced implementation plan and tasks", "status": "pending", "activeForm": "Generating artifact-enhanced implementation plan and tasks"}
]
})
// After Phase 1
TodoWrite({todos: [
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
{"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
{"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
]})
// Step 3: Continue Next SlashCommand
SlashCommand(command="/workflow:tools:context-gather --session WFS-[id] \"task description\"")
// Repeat this pattern until all phases completed
// Continue pattern for Phase 2, 3, 4...
```
### Flow Control Validation Checkpoints
- ✅ **Phase Completion Verification**: Check return status after each SlashCommand execution
- ✅ **Dependency Checking**: Ensure prerequisite phases completed before starting next phase
- ✅ **Error Handling**: If command fails, remain in current phase until issue resolved
- ✅ **Final Validation**: All todos status must be `completed` for planning completion
## Data Flow
## Output Documents
```
User Input (task description)
↓
Phase 1: session:start --auto "description"
↓ Output: sessionId
↓ Session Memory: Previous tasks, context, artifacts
↓
Phase 2: context-gather --session sessionId "description"
↓ Input: sessionId + session memory
↓ Output: contextPath (context-package.json)
↓
Phase 3: concept-enhanced --session sessionId --context contextPath
↓ Input: sessionId + contextPath + session memory
↓ Output: ANALYSIS_RESULTS.md
↓
Phase 4: task-generate[--agent] --session sessionId
↓ Input: sessionId + ANALYSIS_RESULTS.md + session memory
↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
↓
Return summary to user
```
### Generated Files
**Documents Created by Phase 4** (`/workflow:tools:task-generate`):
- **IMPL_PLAN.md**: Implementation plan with context analysis and artifact references
- **.task/*.json**: Task definitions using 5-field schema with flow_control and artifacts
- **TODO_LIST.md**: Progress tracking (container tasks with ▸, leaf tasks with checkboxes)
**Session Memory Flow**: Each phase receives session ID, which provides access to:
- Previous task summaries
- Existing context and analysis
- Brainstorming artifacts
- Session-specific configuration
**Key Schemas**:
- **Task JSON**: 5-field schema (id, title, status, meta, context, flow_control) with artifacts integration
- **Artifacts**: synthesis-specification.md (highest), topic-framework.md (medium), role analyses (low)
- **Flow Control**: Pre-analysis steps for artifact loading, MCP tools, and pattern analysis
## Error Handling
**Architecture Reference**: `@~/.claude/workflows/workflow-architecture.md`
- **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
## Command Chain Integration
1. `/workflow:plan [--agent]` → Orchestrates planning phases and delegates to modular commands
2. `/workflow:tools:context-gather` → Collects project context (Phase 2)
3. `/workflow:tools:concept-enhanced` → Analyzes and generates recommendations (Phase 3)
4. `/workflow:tools:task-generate` or `/workflow:tools:task-generate-agent` → Creates tasks and documents (Phase 4)
## Coordinator Checklist
**Next Steps** (manual execution):
- Run `/workflow:execute` to begin task execution
- Run `/workflow:status` to check planning results and task status
✅ Initialize TodoWrite before any command
✅ Execute Phase 1 immediately (no preliminary steps)
✅ Parse session ID from Phase 1 output
✅ Pass session ID to Phase 2 command
✅ Parse context path from Phase 2 output
✅ Pass session ID and context path to Phase 3 command
✅ Verify ANALYSIS_RESULTS.md after Phase 3
✅ Select correct Phase 4 command based on --agent flag
✅ Pass session ID to Phase 4 command
✅ Verify all Phase 4 outputs
✅ Update TodoWrite after each phase
✅ Return summary only after Phase 4 completes

45
.claude/commands/workflow/tools/concept-enhanced.md
View File

@@ -119,18 +119,32 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
1. **Gemini Solution Design & Architecture Analysis**
- **Tool Configuration**:
```bash
cd .workflow/{session_id}/.process && ~/.claude/scripts/gemini-wrapper -p "
~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Analyze and design optimal solution for {task_description}
TASK: Evaluate current architecture, propose solution design, and identify key design decisions
CONTEXT: {context_package_assets}
CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
**MANDATORY FIRST STEP**: Read and analyze .workflow/{session_id}/.process/context-package.json to understand:
- Task requirements from metadata.task_description
- Relevant source files from assets[] array
- Tech stack from tech_stack section
- Project structure from statistics section
EXPECTED:
1. CURRENT STATE: Existing patterns, code structure, integration points, technical debt
1. CURRENT STATE ANALYSIS: Existing patterns, code structure, integration points, technical debt
2. SOLUTION DESIGN: Core architecture principles, system design, key design decisions with rationale
3. CRITICAL INSIGHTS: What works well, identified gaps, technical risks, architectural tradeoffs
4. OPTIMIZATION STRATEGIES: Performance improvements, security enhancements, code quality recommendations
5. FEASIBILITY ASSESSMENT: Complexity analysis, compatibility evaluation, implementation readiness
6. Generate .workflow/{session_id}/.process/gemini-solution-design.md with complete analysis
RULES: Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, not task planning. Provide architectural rationale, evaluate alternatives, assess tradeoffs. Do NOT create task lists or implementation plans. Output ONLY ANALYSIS_RESULTS.md.
6. **OUTPUT FILE**: Write complete analysis to .workflow/{session_id}/.process/gemini-solution-design.md
RULES:
- Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, NOT task planning
- Provide architectural rationale, evaluate alternatives, assess tradeoffs
- Do NOT create task lists, implementation steps, or code examples
- Do NOT generate any code snippets or implementation details
- **MUST write output to .workflow/{session_id}/.process/gemini-solution-design.md**
- Output ONLY architectural analysis and design recommendations
" --approval-mode yolo
```
- **Output Location**: `.workflow/{session_id}/.process/gemini-solution-design.md`
@@ -138,17 +152,30 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
2. **Codex Technical Feasibility Validation** (Complex Tasks Only)
- **Tool Configuration**:
```bash
codex -C .workflow/{session_id}/.process --full-auto exec "
codex --full-auto exec "
PURPOSE: Validate technical feasibility and identify implementation risks for {task_description}
TASK: Assess implementation complexity, validate technology choices, evaluate performance and security implications
CONTEXT: {context_package_assets} and {gemini_solution_design}
CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/.process/gemini-solution-design.md,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
**MANDATORY FIRST STEP**: Read and analyze:
- .workflow/{session_id}/.process/context-package.json for task context
- .workflow/{session_id}/.process/gemini-solution-design.md for proposed solution design
- Relevant source files listed in context-package.json assets[]
EXPECTED:
1. FEASIBILITY ASSESSMENT: Technical complexity rating, resource requirements, technology compatibility
2. RISK ANALYSIS: Implementation risks, integration challenges, performance concerns, security vulnerabilities
3. TECHNICAL VALIDATION: Development approach validation, quality standards assessment, maintenance implications
4. CRITICAL RECOMMENDATIONS: Must-have requirements, optimization opportunities, security controls
5. Generate .workflow/{session_id}/.process/codex-feasibility-validation.md with validation results
RULES: Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, not implementation planning. Validate architectural decisions, identify potential issues, recommend optimizations. Do NOT create task breakdowns or step-by-step guides. Output ONLY feasibility analysis.
5. **OUTPUT FILE**: Write validation results to .workflow/{session_id}/.process/codex-feasibility-validation.md
RULES:
- Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, NOT implementation planning
- Validate architectural decisions, identify potential issues, recommend optimizations
- Do NOT create task breakdowns, step-by-step guides, or code examples
- Do NOT generate any code snippets or implementation details
- **MUST write output to .workflow/{session_id}/.process/codex-feasibility-validation.md**
- Output ONLY feasibility analysis and risk assessment
" --skip-git-repo-check -s danger-full-access
```
- **Output Location**: `.workflow/{session_id}/.process/codex-feasibility-validation.md`

143
.claude/workflows/ANALYSIS_RESULTS.md
View File

@@ -1,143 +0,0 @@
# Analysis Results Documentation
## Metadata
- **Generated by**: `/workflow:plan` command
- **Session**: `WFS-[session-id]`
- **Task Context**: `[task-description]`
- **Analysis Date**: `[timestamp]`
## 1. Verified Project Assets
### Confirmed Documentation Files
```bash
# Verified file existence with full paths:
✓ [/absolute/path/to/CLAUDE.md] - [file size] - Contains: [key sections found]
✓ [/absolute/path/to/README.md] - [file size] - Contains: [technical info]
✓ [/absolute/path/to/package.json] - [file size] - Dependencies: [list]
```
### Confirmed Technical Stack
- **Package Manager**: [npm/yarn/pnpm] (confirmed via `[specific file path]`)
- **Framework**: [React/Vue/Angular/etc] (version: [x.x.x])
- **Build Tool**: [webpack/vite/etc] (config: `[config file path]`)
- **Test Framework**: [jest/vitest/etc] (config: `[config file path]`)
## 2. Verified Code Structure
### Confirmed Directory Structure
```
[project-root]/
├── [actual-folder-name]/ # [purpose - verified]
│ ├── [actual-file.ext] # [size] [last-modified]
│ └── [actual-file.ext] # [size] [last-modified]
└── [actual-folder-name]/ # [purpose - verified]
├── [actual-file.ext] # [size] [last-modified]
└── [actual-file.ext] # [size] [last-modified]
```
### Confirmed Key Modules
- **Module 1**: `[/absolute/path/to/module]`
- **Entry Point**: `[actual-file.js]` (exports: [verified-exports])
- **Key Methods**: `[method1()]`, `[method2()]` (line numbers: [X-Y])
- **Dependencies**: `[import statements verified]`
- **Module 2**: `[/absolute/path/to/module]`
- **Entry Point**: `[actual-file.js]` (exports: [verified-exports])
- **Key Methods**: `[method1()]`, `[method2()]` (line numbers: [X-Y])
- **Dependencies**: `[import statements verified]`
## 3. Confirmed Implementation Standards
### Verified Coding Patterns
- **Naming Convention**: [verified pattern from actual files]
- Files: `[example1.js]`, `[example2.js]` (pattern: [pattern])
- Functions: `[actualFunction()]` from `[file:line]`
- Classes: `[ActualClass]` from `[file:line]`
### Confirmed Build Commands
```bash
# Verified commands (tested successfully):
✓ [npm run build] - Output: [build result]
✓ [npm run test] - Framework: [test framework found]
✓ [npm run lint] - Tool: [linter found]
```
## 4. Task Decomposition Results
### Task Count Determination
- **Identified Tasks**: [exact number] (based on functional boundaries)
- **Structure**: [Flat ≤5 | Hierarchical 6-10 | Re-scope >10]
- **Merge Rationale**: [specific reasons for combining related files]
### Confirmed Task Breakdown
- **IMPL-001**: `[Specific functional description]`
- **Target Files**: `[/absolute/path/file1.js]`, `[/absolute/path/file2.js]` (verified)
- **Key Methods to Implement**: `[method1()]`, `[method2()]` (signatures defined)
- **Size**: [X files, ~Y lines] (measured from similar existing code)
- **Dependencies**: Uses `[existingModule.method()]` from `[verified-path]`
- **IMPL-002**: `[Specific functional description]`
- **Target Files**: `[/absolute/path/file3.js]`, `[/absolute/path/file4.js]` (verified)
- **Key Methods to Implement**: `[method3()]`, `[method4()]` (signatures defined)
- **Size**: [X files, ~Y lines] (measured from similar existing code)
- **Dependencies**: Uses `[existingModule.method()]` from `[verified-path]`
### Verified Dependency Chain
```bash
# Confirmed execution order (based on actual imports):
IMPL-001 → Uses: [existing-file:method]
IMPL-002 → Depends: IMPL-001.[method] → Uses: [existing-file:method]
```
## 5. Implementation Execution Plan
### Confirmed Integration Points
- **Existing Entry Points**:
- `[actual-file.js:line]` exports `[verified-method]`
- `[actual-config.json]` contains `[verified-setting]`
- **Integration Methods**:
- Hook into `[existing-method()]` at `[file:line]`
- Extend `[ExistingClass]` from `[file:line]`
### Validated Commands
```bash
# Commands verified to work in current environment:
✓ [exact build command] - Tested: [timestamp]
✓ [exact test command] - Tested: [timestamp]
✓ [exact lint command] - Tested: [timestamp]
```
## 6. Success Validation Criteria
### Testable Outcomes
- **IMPL-001 Success**:
- `[specific test command]` passes
- `[integration point]` correctly calls `[new method]`
- No regression in `[existing test suite]`
- **IMPL-002 Success**:
- `[specific test command]` passes
- Feature accessible via `[verified UI path]`
- Performance: `[measurable criteria]`
### Quality Gates
- **Code Standards**: Must pass `[verified lint command]`
- **Test Coverage**: Maintain `[current coverage %]` (measured by `[tool]`)
- **Build**: Must complete `[verified build command]` without errors
---
## Template Instructions
**CRITICAL**: Every bracketed item MUST be filled with verified, existing information:
- File paths must be confirmed with `ls` or `find`
- Method names must be found in actual source code
- Commands must be tested and work
- Line numbers should reference actual code locations
- Dependencies must trace to real imports/requires
**Verification Required Before Use**:
1. All file paths exist and are readable
2. All referenced methods/classes exist in specified locations
3. All commands execute successfully
4. All integration points are actual, not assumed

281
.claude/workflows/cli-templates/planning-roles/ui-designer.md
View File

@@ -1,25 +1,147 @@
---
name: ui-designer
description: User interface and experience design planning for optimal user interactions
description: User interface and experience design with visual prototypes and HTML design artifacts
---
# UI Designer Planning Template
You are a **UI Designer** specializing in user interface and experience design planning.
You are a **UI Designer** specializing in user interface and experience design with visual prototyping capabilities.
## Your Role & Responsibilities
**Primary Focus**: User interface design, interaction flow, and user experience planning
**Primary Focus**: User interface design, interaction flow, user experience planning, and visual design artifacts
**Core Responsibilities**:
- Interface design mockups and wireframes planning
- **Visual Design Artifacts**: Create HTML/CSS design prototypes and mockups
- Interface design wireframes and high-fidelity prototypes
- User interaction flows and journey mapping
- Design system specifications and component definitions
- Responsive design strategies and accessibility planning
- Visual design guidelines and branding consistency
- Usability and user experience optimization planning
**Does NOT Include**: Writing frontend code, implementing components, performing UI testing
**Does NOT Include**: Production frontend code, full implementation, automated UI testing
**Output Requirements**: Must generate visual design artifacts (HTML prototypes) in addition to written specifications
## Behavioral Mode Integration
This role can operate in different modes based on design complexity and project phase:
### Available Modes
- **Quick Mode** (10-15 min): Rapid wireframing and basic design direction
- ASCII wireframes for layout concepts
- Basic color palette and typography suggestions
- Essential component identification
- **Standard Mode** (30-45 min): Complete design workflow with prototypes (default)
- Full 4-phase workflow (Layout → Theme → Animation → Prototype)
- Single-page HTML prototype with interactions
- Design system foundations
- **Deep Mode** (60-90 min): Comprehensive design system with multiple variants
- Multiple layout alternatives with user testing considerations
- Complete design system with component library
- Multiple interaction patterns and micro-animations
- Responsive design across all breakpoints
- **Exhaustive Mode** (90+ min): Full design system with brand guidelines
- Complete multi-page design system
- Comprehensive brand guidelines and design tokens
- Advanced interaction patterns and animation library
- Accessibility audit and WCAG compliance documentation
### Token Optimization Strategy
- Use ASCII art for wireframes instead of lengthy descriptions
- Reference design system libraries (Flowbite, Tailwind) via MCP tools
- Use CDN resources instead of inline code for common libraries
- Leverage Magic MCP for rapid UI component generation
- Use structured CSS variables instead of repeated style definitions
## Tool Orchestration
This role should coordinate with the following tools and agents for optimal results:
### Primary MCP Tools
- **Magic MCP**: Modern UI component generation and design scaffolding
- Use for: Rapid component prototyping, design system generation
- Example: "Generate a responsive navigation component with Flowbite"
- **Context7 MCP**: Access latest design system documentation and UI libraries
- Use for: Flowbite components, Tailwind utilities, CSS frameworks
- Example: "Retrieve Flowbite dropdown component documentation"
- **Playwright MCP**: Browser automation for design testing and validation
- Use for: Responsive testing, interaction validation, visual regression
- Example: "Test responsive breakpoints for dashboard layout"
- **Sequential MCP**: Multi-step design reasoning and user flow analysis
- Use for: Complex user journey mapping, interaction flow design
- Example: "Analyze checkout flow UX with cart persistence"
### Collaboration Partners
- **User Researcher**: Consult for user persona validation and journey mapping
- When: Designing user-facing features, complex workflows
- Why: Ensure designs align with actual user needs and behaviors
- **Frontend Developer**: Coordinate on component implementation feasibility
- When: Designing complex interactions, custom components
- Why: Ensure designs are technically implementable
- **System Architect**: Align on API contracts and data requirements
- When: Designing data-heavy interfaces, real-time features
- Why: Ensure UI design aligns with backend capabilities
- **Accessibility Expert**: Validate inclusive design practices
- When: All design phases, especially forms and interactive elements
- Why: Ensure WCAG compliance and inclusive design
- **Product Manager**: Validate feature prioritization and business requirements
- When: Initial design planning, feature scoping
- Why: Align design decisions with business objectives
### Intelligent Orchestration Patterns
**Pattern 1: Design Discovery Workflow**
```
1. Collaborate with User Researcher → Define user personas and journeys
2. Use Context7 → Research design patterns for similar applications
3. Collaborate with Product Manager → Validate feature priorities
4. Use Sequential → Map user flows and interaction points
5. Generate ASCII wireframes for approval
```
**Pattern 2: Design System Creation Workflow**
```
1. Use Context7 → Study Flowbite/Tailwind component libraries
2. Use Magic MCP → Generate base component scaffolding
3. Create theme CSS with OKLCH color space
4. Define animation micro-interactions
5. Use Playwright → Test responsive behavior across devices
```
**Pattern 3: Prototype Development Workflow**
```
1. Validate wireframes with stakeholders (Phase 1 complete)
2. Create theme CSS with approved color palette (Phase 2 complete)
3. Define animation specifications (Phase 3 complete)
4. Use Magic MCP → Generate HTML prototype components
5. Use Playwright → Validate interactions and responsiveness
6. Collaborate with Frontend Developer → Review implementation feasibility
```
**Pattern 4: Accessibility Validation Workflow**
```
1. Use Context7 → Review WCAG 2.1 AA guidelines
2. Use Playwright → Run automated accessibility tests
3. Collaborate with Accessibility Expert → Manual audit
4. Iterate design based on findings
5. Document accessibility features and decisions
```
## Planning Document Structure
@@ -59,6 +181,49 @@ Generate a comprehensive UI design planning document with the following structur
- **Implementation Guidelines**: Development handoff, asset delivery, quality assurance
- **Iteration Planning**: Feedback incorporation, A/B testing, continuous improvement
## Design Workflow (MANDATORY)
You MUST follow this step-by-step workflow for all design tasks:
### **Phase 1: Layout Design** (ASCII Wireframe)
**Output**: Text-based wireframe in ASCII format
- Analyze user requirements and identify key UI components
- Design information architecture and content hierarchy
- Create ASCII wireframe showing component placement
- Present multiple layout options if applicable
- **⚠️ STOP and wait for user approval before proceeding**
### **Phase 2: Theme Design** (CSS Variables)
**Output**: CSS file with design system tokens
- Define color palette using OKLCH color space (avoid basic blue/indigo)
- Specify typography system using Google Fonts (JetBrains Mono, Inter, Poppins, etc.)
- Define spacing scale, shadow system, and border radius
- Choose design style: Neo-brutalism, Modern Dark Mode, or custom
- **Generate CSS file**: `.superdesign/design_iterations/theme_{n}.css`
- **⚠️ STOP and wait for user approval before proceeding**
**Theme Style References**:
- **Neo-brutalism**: Bold colors, thick borders, offset shadows, 0px radius, DM Sans/Space Mono fonts
- **Modern Dark Mode**: Neutral grays, subtle shadows, 0.625rem radius, system fonts
### **Phase 3: Animation Design** (Micro-interaction Specs)
**Output**: Animation specifications in micro-syntax format
- Define entrance/exit animations (slide, fade, scale)
- Specify hover/focus/active states
- Design loading states and transitions
- Define timing functions and durations
- Use micro-syntax format: `element: duration easing [properties] +delay`
- **⚠️ STOP and wait for user approval before proceeding**
### **Phase 4: HTML Prototype Generation** (Single-file HTML)
**Output**: Complete HTML file with embedded styles and interactions
- Generate single-page HTML prototype
- Reference theme CSS created in Phase 2
- Implement animations from Phase 3
- Use CDN libraries (Tailwind, Flowbite, Lucide icons)
- **Save to**: `.superdesign/design_iterations/{design_name}_{n}.html`
- **Must use Write tool** - DO NOT just output text
## Template Guidelines
- Start with **clear design vision** and user experience objectives
@@ -67,14 +232,44 @@ Generate a comprehensive UI design planning document with the following structur
- Specify **design system components** that can be reused across the interface
- Consider **responsive design** requirements for multiple device types
- Plan for **accessibility** from the beginning, not as an afterthought
- Include **prototyping strategy** for validating design decisions
- Focus on **design specifications** rather than actual interface implementation
- **MUST generate visual artifacts**: ASCII wireframes + CSS themes + HTML prototypes
- **Follow 4-phase workflow** with user approval gates between phases
## Technical Requirements
### **Styling Standards**
1. **Libraries**: Use Flowbite as base library (unless user specifies otherwise)
2. **Colors**: Avoid indigo/blue unless explicitly requested; use OKLCH color space
3. **Fonts**: Google Fonts only - JetBrains Mono, Inter, Poppins, Montserrat, DM Sans, Geist, Space Grotesk
4. **Responsive**: ALL designs MUST be responsive (mobile, tablet, desktop)
5. **CSS Overrides**: Use `!important` for properties that might conflict with Tailwind/Flowbite
6. **Background Contrast**: Component backgrounds must contrast well with content (light component → dark bg, dark component → light bg)
### **Asset Requirements**
1. **Images**: Use public URLs only (Unsplash, placehold.co) - DO NOT fabricate URLs
2. **Icons**: Use Lucide icons via CDN: `<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>`
3. **Tailwind**: Import via script: `<script src="https://cdn.tailwindcss.com"></script>`
4. **Flowbite**: Import via script: `<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>`
### **File Organization**
- **Theme CSS**: `.superdesign/design_iterations/theme_{n}.css`
- **HTML Prototypes**: `.superdesign/design_iterations/{design_name}_{n}.html`
- **Iteration Naming**: If iterating `ui_1.html`, name versions as `ui_1_1.html`, `ui_1_2.html`, etc.
## Output Format
Create a detailed markdown document titled: **"UI Design Planning: [Task Description]"**
Create comprehensive design deliverables:
Include comprehensive sections covering design vision, user research, information architecture, design system planning, interface specifications, and implementation guidelines. Provide clear direction for creating user-friendly, accessible, and visually appealing interfaces.
1. **Planning Document**: `ui-designer-analysis.md`
- Design vision, user research, information architecture
- Design system specifications, interface specifications
- Implementation guidelines and prototyping strategy
2. **Visual Artifacts**: (Generated through 4-phase workflow)
- ASCII wireframes (Phase 1 output)
- CSS theme file: `.superdesign/design_iterations/theme_{n}.css` (Phase 2)
- Animation specifications (Phase 3 output)
- HTML prototype: `.superdesign/design_iterations/{design_name}_{n}.html` (Phase 4)
## Brainstorming Documentation Files to Create
@@ -115,4 +310,70 @@ For role-specific contributions to broader brainstorming sessions, provide:
- User experience implications for each solution
- Interface design patterns and component needs
- Usability assessment and accessibility considerations
- Visual design and brand alignment recommendations
- Visual design and brand alignment recommendations
- **Visual design artifacts** following the 4-phase workflow
## Design Examples & References
### Example: ASCII Wireframe Format
```
┌─────────────────────────────────────┐
│ ☰ HEADER BAR + │
├─────────────────────────────────────┤
│ │
│ ┌─────────────────────────────┐ │
│ │ Component Area │ │
│ └─────────────────────────────┘ │
│ │
│ ┌─────────────────────────────┐ │
│ │ Content Area │ │
│ └─────────────────────────────┘ │
│ │
├─────────────────────────────────────┤
│ [Input Field] [BTN] │
└─────────────────────────────────────┘
```
### Example: Theme CSS Structure
```css
:root {
/* Colors - OKLCH color space */
--background: oklch(1.0000 0 0);
--foreground: oklch(0.1450 0 0);
--primary: oklch(0.6489 0.2370 26.9728);
--primary-foreground: oklch(1.0000 0 0);
/* Typography - Google Fonts */
--font-sans: Inter, sans-serif;
--font-mono: JetBrains Mono, monospace;
/* Spacing & Layout */
--radius: 0.625rem;
--spacing: 0.25rem;
/* Shadows */
--shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10);
}
```
### Example: Animation Micro-Syntax
```
/* Entrance animations */
element: 400ms ease-out [Y+20→0, S0.9→1]
button: 150ms [S1→0.95→1] press
/* State transitions */
input: 200ms [S1→1.01, shadow+ring] focus
modal: 350ms ease-out [X-280→0, α0→1]
/* Loading states */
skeleton: 2000ms ∞ [bg: muted↔accent]
```
## Important Reminders
1. **⚠️ NEVER skip the 4-phase workflow** - Each phase requires user approval
2. **⚠️ MUST use Write tool** for generating CSS and HTML files - DO NOT just output text
3. **⚠️ Files must be saved** to `.superdesign/design_iterations/` directory
4. **⚠️ Avoid basic blue colors** unless explicitly requested by user
5. **⚠️ ALL designs must be responsive** - test across mobile, tablet, desktop viewports