brainstorm-with-file

Codex Brainstorm-With-File Workflow

Quick Start

Interactive brainstorming workflow with documented thought evolution. Expands initial ideas through questioning, parallel subagent analysis, and iterative refinement.

Core workflow: Seed Idea → Expand → Parallel Subagent Explore → Synthesize → Refine → Crystallize

Key features:

• brainstorm.md: Complete thought evolution timeline
• Parallel multi-perspective: Creative + Pragmatic + Systematic (concurrent subagents)
• Idea expansion: Progressive questioning and exploration
• Diverge-Converge cycles: Generate options then focus on best paths

Codex-Specific Features:

• Parallel subagent execution via spawn_agent + batch wait({ ids: [...] })
• Role loading via path (agent reads ~/.codex/agents/*.md itself)
• Deep interaction with send_input for multi-round refinement within single agent
• Explicit lifecycle management with close_agent

Overview

This workflow enables iterative exploration and refinement of ideas through parallel-capable phases:

1. Seed Understanding - Parse the initial idea and identify exploration vectors
2. Divergent Exploration - Gather codebase context and execute parallel multi-perspective analysis
3. Interactive Refinement - Multi-round idea selection, deep-dive, and refinement via send_input
4. Convergence & Crystallization - Synthesize final ideas and generate recommendations

The key innovation is documented thought evolution that captures how ideas develop, perspectives differ, and insights emerge across all phases.

Output Structure

{projectRoot}/.workflow/.brainstorm/BS-{slug}-{date}/
├── brainstorm.md                  # ⭐ Complete thought evolution timeline
├── exploration-codebase.json      # Phase 2: Codebase context
├── perspectives/                  # Phase 2: Individual perspective outputs
│   ├── creative.json
│   ├── pragmatic.json
│   └── systematic.json
├── perspectives.json              # Phase 2: Aggregated parallel findings with synthesis
├── synthesis.json                 # Phase 4: Final synthesis
└── ideas/                         # Phase 3: Individual idea deep-dives
    ├── idea-1.md
    ├── idea-2.md
    └── merged-idea-1.md

Output Artifacts

Phase 1: Seed Understanding

Artifact	Purpose
brainstorm.md	Initialized with session metadata, seed expansion, and exploration vectors
Session variables	Topic slug, brainstorm mode, dimensions, exploration vectors

Phase 2: Divergent Exploration

Artifact	Purpose
exploration-codebase.json	Codebase context: relevant files, patterns, architecture constraints
perspectives/*.json	Individual perspective outputs from parallel subagents
perspectives.json	Aggregated parallel findings with synthesis (convergent/conflicting themes)
Updated brainstorm.md	Round 2: Exploration results and multi-perspective analysis

Phase 3: Interactive Refinement

Artifact	Purpose
ideas/{idea-slug}.md	Deep-dive analysis for selected ideas
Updated brainstorm.md	Round 3-6: User feedback, idea selections, refinement cycles

Phase 4: Convergence & Crystallization

Artifact	Purpose
synthesis.json	Final synthesis: top ideas, recommendations, insights
Final brainstorm.md	Complete thought evolution with conclusions

---

Implementation Details

Session Initialization

Step 0: Determine Project Root

检测项目根目录，确保 .workflow/ 产物位置正确：

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

优先通过 git 获取仓库根目录；非 git 项目回退到 pwd 取当前绝对路径。 存储为 {projectRoot}，后续所有 .workflow/ 路径必须以此为前缀。

The workflow automatically generates a unique session identifier and directory structure based on the topic and current date (UTC+8).

Session ID Format: BS-{slug}-{date}

• slug: Lowercase alphanumeric + Chinese characters, max 40 chars
• date: YYYY-MM-DD format (UTC+8)

Session Directory: {projectRoot}/.workflow/.brainstorm/{sessionId}/

Auto-Detection: If session folder exists with brainstorm.md, automatically enters continue mode. Otherwise, creates new session.

Brainstorm Modes:

• creative: Emphasize novelty and innovation, relaxed constraints
• structured: Balance creativity with feasibility, realistic scope
• balanced: Default, moderate innovation with practical considerations

---

Phase 1: Seed Understanding

Objective: Parse the initial idea, identify exploration vectors, scope preferences, and initialize the brainstorm document.

Step 1.1: Parse Seed & Identify Dimensions

The workflow analyzes the topic text against predefined brainstorm dimensions.

Brainstorm Dimensions:

Dimension	Keywords
technical	技术, technical, implementation, code, 实现, architecture
ux	用户, user, experience, UX, UI, 体验, interaction
business	业务, business, value, ROI, 价值, market
innovation	创新, innovation, novel, creative, 新颖
feasibility	可行, feasible, practical, realistic, 实际
scalability	扩展, scale, growth, performance, 性能
security	安全, security, risk, protection, 风险

Matching Logic: Compare topic text against keyword lists to identify relevant dimensions.

Step 1.2: Role Selection

Recommend roles based on topic keywords, then let user confirm or override.

Professional Roles (recommended based on topic keywords):

Role	Perspective Agent Focus	Keywords
system-architect	Architecture, patterns	架构, architecture, system, 系统, design pattern
product-manager	Business value, roadmap	产品, product, feature, 功能, roadmap
ui-designer	Visual design, interaction	UI, 界面, interface, visual, 视觉
ux-expert	User research, usability	UX, 体验, experience, user, 用户
data-architect	Data modeling, storage	数据, data, database, 存储, storage
test-strategist	Quality, testing	测试, test, quality, 质量, QA
subject-matter-expert	Domain knowledge	领域, domain, industry, 行业, expert

Simple Perspectives (fallback - always available):

Perspective	Focus	Best For
creative	Innovation, cross-domain	Generating novel ideas
pragmatic	Implementation, feasibility	Reality-checking ideas
systematic	Architecture, structure	Organizing solutions

Selection Strategy:

1. Auto mode: Select top 3 recommended professional roles based on keyword matching
2. Manual mode: Present recommended roles + "Use simple perspectives" option
3. Continue mode: Use roles from previous session

Step 1.3: Initial Scoping (New Session Only)

For new brainstorm sessions, gather user preferences before exploration.

Brainstorm Mode (Single-select):

• 创意模式 (Creative mode - 15-20 minutes, 1 subagent)
• 平衡模式 (Balanced mode - 30-60 minutes, 3 parallel subagents)
• 深度模式 (Deep mode - 1-2+ hours, 3 parallel subagents + deep refinement)

Focus Areas (Multi-select):

• 技术方案 (Technical solutions)
• 用户体验 (User experience)
• 创新突破 (Innovation breakthroughs)
• 可行性评估 (Feasibility assessment)

Constraints (Multi-select):

• 现有架构 (Existing architecture constraints)
• 时间限制 (Time constraints)
• 资源限制 (Resource constraints)
• 无约束 (No constraints)

Step 1.4: Expand Seed into Exploration Vectors

Generate key questions that guide the brainstorming exploration. Use a subagent for vector generation.

Exploration Vectors:

1. Core question: What is the fundamental problem/opportunity?
2. User perspective: Who benefits and how?
3. Technical angle: What enables this technically?
4. Alternative approaches: What other ways could this be solved?
5. Challenges: What could go wrong or block success?
6. Innovation angle: What would make this 10x better?
7. Integration: How does this fit with existing systems/processes?

Subagent for Vector Generation:

const vectorAgent = spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)

---

## Context
Topic: ${idea_or_topic}
User focus areas: ${userFocusAreas.join(', ')}
Constraints: ${constraints.join(', ')}

## Task
Generate 5-7 exploration vectors (questions/directions) to expand this idea:
1. Core question: What is the fundamental problem/opportunity?
2. User perspective: Who benefits and how?
3. Technical angle: What enables this technically?
4. Alternative approaches: What other ways could this be solved?
5. Challenges: What could go wrong or block success?
6. Innovation angle: What would make this 10x better?
7. Integration: How does this fit with existing systems/processes?

## Deliverables
Return structured exploration vectors for multi-perspective analysis.
`
})

const result = wait({ ids: [vectorAgent], timeout_ms: 120000 })
close_agent({ id: vectorAgent })

Purpose: These vectors guide each perspective subagent's analysis and ensure comprehensive exploration.

Step 1.5: Initialize brainstorm.md

Create the main brainstorm document with session metadata and expansion content.

brainstorm.md Structure:

• Header: Session ID, topic, start time, brainstorm mode, dimensions
• Initial Context: Focus areas, depth level, constraints
• Roles: Selected roles (professional or simple perspectives)
• Seed Expansion: Original idea + exploration vectors
• Thought Evolution Timeline: Round-by-round findings
• Current Ideas: To be populated after exploration

Success Criteria:

• Session folder created successfully
• brainstorm.md initialized with all metadata
• 1-3 roles selected (professional or simple perspectives)
• Brainstorm mode and dimensions identified
• Exploration vectors generated
• User preferences captured

---

Phase 2: Divergent Exploration

**Object

---

Content truncated.