From aa3413cd6e5a3780da850b0d88e36ea45b9904e9 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 24 Sep 2025 10:21:25 +0800 Subject: [PATCH] feat: Add brainstorm artifacts command with unified document structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create dedicated /workflow:brainstorm:artifacts command for topic discussion and decomposition - Unify document structure between auto.md and artifacts.md commands - Fix .brainstorming path references to use proper .workflow/WFS-[topic]/ structure - Add discussion-summary.md and component-analysis.md as shared foundation documents - Separate synthesis/ folder generation to dedicated synthesis command - Update auto.md workflow to include Interactive Discussion → Topic Decomposition phases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../commands/workflow/brainstorm/artifacts.md | 193 ++++++++++++++++++ .claude/commands/workflow/brainstorm/auto.md | 31 +-- 2 files changed, 211 insertions(+), 13 deletions(-) create mode 100644 .claude/commands/workflow/brainstorm/artifacts.md diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md new file mode 100644 index 00000000..f6f60121 --- /dev/null +++ b/.claude/commands/workflow/brainstorm/artifacts.md @@ -0,0 +1,193 @@ +--- +name: artifacts +description: Topic discussion, decomposition, and analysis artifacts generation through structured inquiry +usage: /workflow:brainstorm:artifacts "" +argument-hint: "topic or challenge description for discussion and analysis" +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" +allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*) +--- + +# Workflow Brainstorm Artifacts Command + +## Usage +```bash +/workflow:brainstorm:artifacts "" +``` + +## Purpose +Dedicated command for topic discussion, decomposition, and analysis artifacts generation. This command focuses on interactive exploration and documentation creation without complex agent workflows. + +## Core Workflow + +### Discussion & Artifacts Generation Process + +**0. Session Management** ⚠️ FIRST STEP +- **Active session detection**: Check `.workflow/.active-*` markers +- **Session selection**: Prompt user if multiple active sessions found +- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists +- **Context isolation**: Each session maintains independent analysis state + +**1. Topic Discussion & Inquiry** +- **Interactive exploration**: Direct conversation about topic aspects +- **Structured questioning**: Key areas of investigation +- **Context gathering**: User input and requirements clarification +- **Perspective collection**: Multiple viewpoints and considerations + +**2. Topic Decomposition** +- **Component identification**: Break down topic into key areas +- **Relationship mapping**: Connections between components +- **Priority assessment**: Importance and urgency evaluation +- **Constraint analysis**: Limitations and requirements + +**3. Analysis Artifacts Generation** +- **Discussion summary**: `.workflow/WFS-[topic]/.brainstorming/discussion-summary.md` - Key points and insights +- **Component analysis**: `.workflow/WFS-[topic]/.brainstorming/component-analysis.md` - Detailed decomposition + +## Implementation Standards + +### Discussion-Driven Analysis +**Interactive Approach**: Direct conversation and exploration without predefined role constraints + +**Process Flow**: +1. **Topic introduction**: Understanding scope and context +2. **Exploratory questioning**: Open-ended investigation +3. **Component identification**: Breaking down into manageable pieces +4. **Relationship analysis**: Understanding connections and dependencies +5. **Documentation generation**: Structured capture of insights + +**Key Areas of Investigation**: +- **Functional aspects**: What the topic needs to accomplish +- **Technical considerations**: Implementation constraints and requirements +- **User perspectives**: How different stakeholders are affected +- **Business implications**: Cost, timeline, and strategic considerations +- **Risk assessment**: Potential challenges and mitigation strategies + +### Document Generation Standards + +**Always Created**: +- **discussion-summary.md**: Main conversation points and key insights +- **component-analysis.md**: Detailed breakdown of topic components + +## Document Generation + +**Workflow**: Topic Discussion → Component Analysis → Documentation + +**Document Structure**: +``` +.workflow/WFS-[topic]/.brainstorming/ +├── discussion-summary.md # Main conversation and insights +└── component-analysis.md # Detailed topic breakdown +``` + +**Document Templates**: + +### discussion-summary.md +```markdown +# Topic Discussion Summary: [topic] + +## Overview +Brief description of the topic and its scope. + +## Key Insights +- Major points discovered during discussion +- Important considerations identified +- Critical success factors + +## Questions Explored +- Primary areas of investigation +- User responses and clarifications +- Open questions requiring further research + +## Next Steps +- Recommended follow-up actions +- Areas needing deeper analysis +``` + +### component-analysis.md +```markdown +# Component Analysis: [topic] + +## Core Components +Detailed breakdown of main topic elements: + +### Component 1: [Name] +- **Purpose**: What it does +- **Dependencies**: What it relies on +- **Interfaces**: How it connects to other components + +### Component 2: [Name] +- **Purpose**: +- **Dependencies**: +- **Interfaces**: + +## Component Relationships +- How components interact +- Data flow between components +- Critical dependencies +``` + +## Session Management ⚠️ CRITICAL +- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing +- **Multiple sessions support**: Different Claude instances can have different active sessions +- **User selection**: If multiple active sessions found, prompt user to select which one to work with +- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists +- **Session continuity**: MUST use selected active session for all processing +- **Context preservation**: All discussion and analysis stored in session directory +- **Session isolation**: Each session maintains independent state + +## Discussion Areas + +### Core Investigation Topics +- **Purpose & Goals**: What are we trying to achieve? +- **Scope & Boundaries**: What's included and excluded? +- **Success Criteria**: How do we measure success? +- **Constraints**: What limitations exist? +- **Stakeholders**: Who is affected or involved? + +### Technical Considerations +- **Requirements**: What must the solution provide? +- **Dependencies**: What does it rely on? +- **Integration**: How does it connect to existing systems? +- **Performance**: What are the speed/scale requirements? +- **Security**: What protection is needed? + +### Implementation Factors +- **Timeline**: When is it needed? +- **Resources**: What people/budget/tools are available? +- **Risks**: What could go wrong? +- **Alternatives**: What other approaches exist? +- **Migration**: How do we transition from current state? + +## Quality Standards + +### Discussion Excellence +- **Comprehensive exploration**: Cover all relevant aspects of the topic +- **Clear documentation**: Capture insights in structured, readable format +- **Actionable outcomes**: Generate practical next steps and recommendations +- **User-driven**: Follow user interests and priorities in the discussion + +### Documentation Quality +- **Structured format**: Use consistent templates for easy navigation +- **Complete coverage**: Document all important discussion points +- **Clear language**: Avoid jargon, explain technical concepts +- **Practical focus**: Emphasize actionable insights and recommendations + +## Error Handling +- **Session creation failure**: Provide clear error message and retry option +- **Discussion stalling**: Offer structured prompts to continue exploration +- **Documentation issues**: Graceful handling of file creation problems +- **Missing context**: Prompt for additional information when needed + +## Reference Information + +### File Structure Reference +**Architecture**: @~/.claude/workflows/workflow-architecture.md +**Session Management**: Standard workflow session protocols + +### Integration Points +- **Compatible with**: Other brainstorming commands in the same session +- **Builds foundation for**: More detailed planning and implementation phases +- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration \ No newline at end of file diff --git a/.claude/commands/workflow/brainstorm/auto.md b/.claude/commands/workflow/brainstorm/auto.md index d8ea6fda..b2ac2bb0 100644 --- a/.claude/commands/workflow/brainstorm/auto.md +++ b/.claude/commands/workflow/brainstorm/auto.md @@ -59,10 +59,10 @@ The command performs dedicated role analysis through: - **Progress tracking**: Real-time TodoWrite updates per role **3. Analysis Artifacts Generated** -- **Role contexts**: `.brainstorming/[role]-context.md` - User responses per role -- **Agent outputs**: `.brainstorming/[role]/analysis.md` - Dedicated role analysis -- **Session metadata**: `.brainstorming/auto-session.json` - Agent assignments and validation -- **Synthesis**: `.brainstorming/synthesis/integrated-analysis.md` - Multi-role integration +- **Role contexts**: `.workflow/WFS-[topic]/.brainstorming/[role]-context.md` - User responses per role +- **Agent outputs**: `.workflow/WFS-[topic]/.brainstorming/[role]/analysis.md` - Dedicated role analysis +- **Session metadata**: `.workflow/WFS-[topic]/.brainstorming/auto-session.json` - Agent assignments and validation +- **Synthesis**: `.workflow/WFS-[topic]/.brainstorming/synthesis/integrated-analysis.md` - Multi-role integration ## Implementation Standards @@ -73,8 +73,8 @@ Agents receive dedicated role assignments with complete context isolation: "agent_assignment": { "role": "system-architect", "agent_id": "conceptual-planning-agent-system-architect", - "context_source": ".brainstorming/system-architect-context.md", - "output_location": ".brainstorming/system-architect/", + "context_source": ".workflow/WFS-[topic]/.brainstorming/system-architect-context.md", + "output_location": ".workflow/WFS-[topic]/.brainstorming/system-architect/", "flow_control": { "pre_analysis": [ { @@ -86,19 +86,19 @@ Agents receive dedicated role assignments with complete context isolation: { "step": "load_user_context", "action": "Load user responses and context for role analysis", - "command": "bash(cat .brainstorming/system-architect-context.md)", + "command": "bash(cat .workflow/WFS-[topic]/.brainstorming/system-architect-context.md)", "output_to": "user_context" }, { "step": "load_content_analysis", "action": "Load existing content analysis documents if available", - "command": "bash(find .brainstorming/ -name '*.md' -path '*/analysis/*' -o -name 'content-analysis.md' | head -5 | xargs cat 2>/dev/null || echo 'No content analysis found')", + "command": "bash(find .workflow/*/.brainstorming/ -name '*.md' -path '*/analysis/*' -o -name 'content-analysis.md' | head -5 | xargs cat 2>/dev/null || echo 'No content analysis found')", "output_to": "content_analysis" }, { "step": "load_session_metadata", "action": "Load session metadata and previous analysis state", - "command": "bash(cat .brainstorming/auto-session.json 2>/dev/null || echo '{}')", + "command": "bash(cat .workflow/WFS-[topic]/.brainstorming/auto-session.json 2>/dev/null || echo '{}')", "output_to": "session_metadata" } ], @@ -122,9 +122,9 @@ Agents receive dedicated role assignments with complete context isolation: **Content Sources**: - Role templates: `bash($(cat ~/.claude/workflows/cli-templates/planning-roles/.md))` from `.claude/workflows/cli-templates/planning-roles/` -- User responses: `bash(cat .brainstorming/-context.md)` from interactive questioning phase -- Content analysis: `bash(find .brainstorming/ -name '*.md' -path '*/analysis/*')` existing analysis documents -- Session metadata: `bash(cat .brainstorming/auto-session.json)` for analysis state and context +- User responses: `bash(cat .workflow/WFS-[topic]/.brainstorming/-context.md)` from interactive questioning phase +- Content analysis: `bash(find .workflow/*/.brainstorming/ -name '*.md' -path '*/analysis/*')` existing analysis documents +- Session metadata: `bash(cat .workflow/WFS-[topic]/.brainstorming/auto-session.json)` for analysis state and context - Conceptual focus: Strategic and planning perspective without technical implementation **Trigger Conditions**: Topic analysis matches role domains, user provides adequate context responses, role template successfully loaded @@ -161,9 +161,11 @@ Agents receive dedicated role assignments with complete context isolation: ## Document Generation -**Workflow**: Role Selection → Context Gathering → Agent Delegation → Documentation → Synthesis +**Workflow**: Interactive Discussion → Topic Decomposition → Role Selection → Context Gathering → Agent Delegation → Documentation → Synthesis **Always Created**: +- **discussion-summary.md**: Main conversation points and key insights from interactive discussion +- **component-analysis.md**: Detailed breakdown of topic components from discussion phase - **auto-session.json**: Agent assignments, context validation, completion tracking - **[role]-context.md**: User responses per role with question-answer pairs @@ -180,6 +182,8 @@ Agents receive dedicated role assignments with complete context isolation: **Document Structure**: ``` .workflow/WFS-[topic]/.brainstorming/ +├── discussion-summary.md # Main conversation and insights +├── component-analysis.md # Detailed topic breakdown ├── auto-session.json # Session metadata and agent tracking ├── system-architect-context.md # User responses for system-architect ├── system-architect-template.md# Loaded role template @@ -217,6 +221,7 @@ Documents created for synthesis and action planning: - **[role]/analysis.md**: Role-specific analysis outputs - **synthesis/**: Multi-role integration for comprehensive planning + ## Error Handling - **Role selection failure**: Default to `product-manager` with explanation - **Context validation failure**: Re-prompt with minimum requirements