diff --git a/.claude/WORKFLOW_MODULAR_REFACTOR.md b/.claude/WORKFLOW_MODULAR_REFACTOR.md deleted file mode 100644 index bc425ba2..00000000 --- a/.claude/WORKFLOW_MODULAR_REFACTOR.md +++ /dev/null @@ -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 -**状态**: 已实施并优化 \ No newline at end of file diff --git a/.claude/commands/enhance-prompt.md b/.claude/commands/enhance-prompt.md index ffdcf8e9..4a5f16b5 100644 --- a/.claude/commands/enhance-prompt.md +++ b/.claude/commands/enhance-prompt.md @@ -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 -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 -- ``: **(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 \ No newline at end of file diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md index e2bdc328..93692a17 100644 --- a/.claude/commands/workflow/brainstorm/artifacts.md +++ b/.claude/commands/workflow/brainstorm/artifacts.md @@ -1,12 +1,12 @@ --- name: artifacts -description: Generate structured topic-framework.md for role-based brainstorming analysis -usage: /workflow:brainstorm:artifacts "" +description: Generate role-specific topic-framework.md dynamically based on selected roles +usage: /workflow:brainstorm:artifacts "" [--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 "" +/workflow:brainstorm:artifacts "" [--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 diff --git a/.claude/commands/workflow/brainstorm/auto-parallel.md b/.claude/commands/workflow/brainstorm/auto-parallel.md index 0bac2fe0..45240156 100644 --- a/.claude/commands/workflow/brainstorm/auto-parallel.md +++ b/.claude/commands/workflow/brainstorm/auto-parallel.md @@ -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", diff --git a/.claude/commands/workflow/brainstorm/auto-squeeze.md b/.claude/commands/workflow/brainstorm/auto-squeeze.md index c14c0069..3a56d8cb 100644 --- a/.claude/commands/workflow/brainstorm/auto-squeeze.md +++ b/.claude/commands/workflow/brainstorm/auto-squeeze.md @@ -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 "" 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 "" -``` +## 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* \ No newline at end of file +✅ 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 \ No newline at end of file diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 0423d707..d9d91b1e 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -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] 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 \ No newline at end of file +✅ 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 \ No newline at end of file diff --git a/.claude/commands/workflow/tools/concept-enhanced.md b/.claude/commands/workflow/tools/concept-enhanced.md index 7c73c89b..bd596078 100644 --- a/.claude/commands/workflow/tools/concept-enhanced.md +++ b/.claude/commands/workflow/tools/concept-enhanced.md @@ -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` diff --git a/.claude/workflows/ANALYSIS_RESULTS.md b/.claude/workflows/ANALYSIS_RESULTS.md deleted file mode 100644 index a04ae3db..00000000 --- a/.claude/workflows/ANALYSIS_RESULTS.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/.claude/workflows/cli-templates/planning-roles/ui-designer.md b/.claude/workflows/cli-templates/planning-roles/ui-designer.md index b5fcb558..c2369e41 100644 --- a/.claude/workflows/cli-templates/planning-roles/ui-designer.md +++ b/.claude/workflows/cli-templates/planning-roles/ui-designer.md @@ -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: `` +3. **Tailwind**: Import via script: `` +4. **Flowbite**: Import via 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 \ No newline at end of file +- 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 \ No newline at end of file