Claude-Code-Workflow/.claude/commands/workflow/brainstorm/CLAUDE.md

Module Analysis: workflow:brainstorm

1. Module-specific Implementation Patterns

Role-Based Command Structure

The brainstorm workflow is composed of multiple, distinct "role" commands. Each role is defined in its own Markdown file (e.g., product-manager.md, system-architect.md). This modular design allows for easy extension by adding new role files.

• Command Naming Convention: Each role is invoked via a consistent command structure: /workflow:brainstorm:<role-name> <topic>.
• File Naming Convention: The command's <role-name> corresponds directly to the filename (e.g., product-manager.md implements /workflow:brainstorm:product-manager).

Standardized Role Definition Structure

Each role's .md file follows a strict, standardized structure:

1. Frontmatter: Defines the command name, description, usage, argument-hint, examples, and allowed-tools. All roles consistently use Task(conceptual-planning-agent) and TodoWrite(*).
2. Role Overview: Defines the role's purpose, responsibilities, and success metrics.
3. Analysis Framework: References shared principles (brainstorming-principles.md, brainstorming-framework.md) and lists key questions specific to the role's perspective.
4. Execution Protocol: A multi-phase process detailing session detection, directory creation, task initialization (TodoWrite), and delegation to the conceptual-planning-agent.
5. Output Specification: Defines the directory structure and file templates for the analysis artifacts generated by the role.
6. Session Integration: Specifies how the role's output integrates with the parent session state (workflow-session.json).
7. Quality Assurance: Provides checklists and standards for validating the quality of the role's output.

2. Internal Architecture and Design Decisions

Session-Based Workflow

The entire workflow is stateful and session-based, managed within the .workflow/ directory.

• State Management: An active session is marked by a .workflow/.active-* file.
• Output Scaffolding: Each role command creates a dedicated output directory: .workflow/WFS-{topic-slug}/.brainstorming/<role-name>/. This isolates each perspective's artifacts.

"Map-Reduce" Architectural Pattern

The workflow follows a pattern analogous to Map-Reduce:

• Map Phase: Each individual role command (product-manager, ui-designer, etc.) acts as a "mapper". It takes the input {topic} and produces a detailed analysis from its unique perspective.
• Reduce Phase: The synthesis command acts as the "reducer". It collects the outputs from all completed roles, integrates them, identifies consensus and conflicts, and produces a single, comprehensive strategic report.

Delegation to conceptual-planning-agent

The core analytical work is not performed by the commands themselves. Instead, they act as templating engines that construct a detailed prompt for the conceptual-planning-agent. This design decision centralizes the complex reasoning and generation logic into a single, powerful tool, while the Markdown files serve as declarative "configurations" for that tool.

3. API Contracts and Interfaces

Command-Line Interface (CLI)

The primary user-facing interface is the set of CLI commands:

• Role Commands: /workflow:brainstorm:<role-name> <topic>
• Synthesis Command: /workflow:brainstorm:synthesis (no arguments)

conceptual-planning-agent Contract

The interface with the planning agent is a structured prompt passed to the Task() tool. This prompt consistently contains:

• ASSIGNED_ROLE / ROLE CONTEXT: Defines the persona for the agent.
• USER_CONTEXT: Injects user requirements from the session.
• ANALYSIS_REQUIREMENTS: A detailed, numbered list of tasks for the agent to perform.
• OUTPUT REQUIREMENTS: Specifies the exact file paths and high-level content structure for the generated artifacts.

Filesystem Contract

The workflow relies on a strict filesystem structure for state and outputs:

• Session State: .workflow/WFS-{topic-slug}/workflow-session.json is updated by each role to track progress.
• Role Outputs: Each role must produce a set of .md files in its designated directory (e.g., analysis.md, roadmap.md).
• Synthesis Input: The synthesis command expects to find these specific output files to perform its function.

4. Module Dependencies and Relationships

• Internal Dependencies:

  • The synthesis command is dependent on the outputs of all other role commands. It cannot function until one or more roles have completed their analysis.
  • Individual role commands are largely independent of one another.

• External Dependencies:

  • conceptual-planning-agent: All roles have a critical dependency on this tool for their core logic.
  • Shared Frameworks: All roles include and depend on @~/.claude/workflows/brainstorming-principles.md and @~/.claude/workflows/brainstorming-framework.md, ensuring a consistent analytical foundation.

5. Testing Strategies

This module does not contain automated tests. Validation relies on a set of quality assurance standards defined within each role's Markdown file.

• Checklist-Based Validation: Each file contains a "Quality Assurance" or "Quality Standards" section with checklists for:
  • Required Analysis Elements: Ensures all necessary components are present in the output.
  • Core Principles: Validates that the analysis adheres to the role's guiding principles (e.g., "User-Centric", "Data-Driven").
  • Quality Metrics: Provides criteria for assessing the quality of the output (e.g., "Requirements completeness", "Feasibility of implementation plan").

This approach serves as a form of manual, requirement-based testing for the output generated by the conceptual-planning-agent.