# 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`.