feat: Implement parallel collaborative planning workflow with Plan Note

- Updated collaborative planning prompt to support parallel task generation with subagents. - Enhanced workflow to include explicit lifecycle management for agents and conflict detection. - Revised output structure to accommodate parallel planning results. - Added new LocaleDropdownNavbarItem component for language selection in the documentation site. - Introduced styles for the language icon in the dropdown. - Modified issue execution process to streamline commit messages and report completion with full solution metadata.
2026-02-11 02:33:51 +08:00 · 2026-02-05 18:24:35 +08:00
parent a59baf2473
commit 1480873008
7 changed files with 1653 additions and 359 deletions
--- a/.claude/commands/issue/execute.md
+++ b/.claude/commands/issue/execute.md
@@ -341,31 +341,59 @@ For each task:
 - Do NOT commit after each task
 ### Step 3: Commit Solution (Once)
-After ALL tasks pass, commit once with formatted summary.
+After ALL tasks pass, commit once with clean conventional format.
 Command:
  git add -A
-  git commit -m "<type>(<scope>): <description>
+  git commit -m "<type>(<scope>): <brief description>"
-  Solution: ${SOLUTION_ID}
+Examples:
-  Tasks completed: <list task IDs>
+  git commit -m "feat(auth): add token refresh mechanism"
  git commit -m "fix(payment): resolve timeout in checkout flow"
  git commit -m "refactor(api): simplify error handling"
-  Changes:
+Replace <type> with: feat|fix|refactor|docs|test|chore
  - <file1>: <what changed>
  - <file2>: <what changed>
  Verified: all tests passed"
 Replace <type> with: feat|fix|refactor|docs|test
 Replace <scope> with: affected module name
-Replace <description> with: brief summary from solution
+Replace <description> with: brief summary (NO solution/issue IDs)
 ### Step 4: Report Completion
 On success, run:
-  ccw issue done ${SOLUTION_ID} --result '{"summary": "<brief>", "files_modified": ["<file1>", "<file2>"], "commit": {"hash": "<hash>", "type": "<type>"}, "tasks_completed": <N>}'
+  ccw issue done ${SOLUTION_ID} --result '{
    "solution_id": "<solution-id>",
    "issue_id": "<issue-id>",
    "commit": {
      "hash": "<commit-hash>",
      "type": "<commit-type>",
      "scope": "<commit-scope>",
      "message": "<commit-message>"
    },
    "analysis": {
      "risk": "<low|medium|high>",
      "impact": "<low|medium|high>",
      "complexity": "<low|medium|high>"
    },
    "tasks_completed": [
      {"id": "T1", "title": "...", "action": "...", "scope": "..."},
      {"id": "T2", "title": "...", "action": "...", "scope": "..."}
    ],
    "files_modified": ["<file1>", "<file2>"],
    "tests_passed": true,
    "verification": {
      "all_tests_passed": true,
      "acceptance_criteria_met": true,
      "regression_checked": true
    },
    "summary": "<brief description of accomplishment>"
  }'
 On failure, run:
-  ccw issue done ${SOLUTION_ID} --fail --reason '{"task_id": "<TX>", "error_type": "<test_failure|build_error|other>", "message": "<error details>"}'
+  ccw issue done ${SOLUTION_ID} --fail --reason '{
    "task_id": "<TX>",
    "error_type": "<test_failure|build_error|other>",
    "message": "<error details>",
    "files_attempted": ["<file1>", "<file2>"],
    "commit": null
  }'
 ### Important Notes
 - Do NOT cleanup worktree - it is shared by all solutions in the queue
--- a/.codex/prompts/analyze-with-file.md
+++ b/.codex/prompts/analyze-with-file.md
@@ -1,6 +1,6 @@
 ---
 name: analyze-with-file
-description: Interactive collaborative analysis with documented discussions, CLI-assisted exploration, and evolving understanding. Serial analysis for Codex.
+description: Interactive collaborative analysis with documented discussions, parallel subagent exploration, and evolving understanding. Parallel analysis for Codex.
 argument-hint: "TOPIC=\"<question or topic>\" [--depth=quick|standard|deep] [--continue]"
 ---
@@ -8,21 +8,27 @@ argument-hint: "TOPIC=\"<question or topic>\" [--depth=quick|standard|deep] [--c
 ## Quick Start
-Interactive collaborative analysis workflow with **documented discussion process**. Records understanding evolution, facilitates multi-round Q&A, and uses CLI tools for deep exploration.
+Interactive collaborative analysis workflow with **documented discussion process**. Records understanding evolution, facilitates multi-round Q&A, and uses **parallel subagent exploration** for deep analysis.
-**Core workflow**: Topic → Explore → Discuss → Document → Refine → Conclude
+**Core workflow**: Topic → Parallel Explore → Discuss → Document → Refine → Conclude
 ## Overview
-This workflow enables iterative exploration and refinement of complex topics through sequential phases:
+This workflow enables iterative exploration and refinement of complex topics through parallel-capable phases:
 1. **Topic Understanding** - Parse the topic and identify analysis dimensions
-2. **CLI Exploration** - Gather codebase context and perform deep analysis via Gemini
+2. **Parallel Exploration** - Gather codebase context via parallel subagents (up to 4)
 3. **Interactive Discussion** - Multi-round Q&A with user feedback and direction adjustments
 4. **Synthesis & Conclusion** - Consolidate insights and generate actionable recommendations
 The key innovation is **documented discussion timeline** that captures the evolution of understanding across all phases, enabling users to track how insights develop and assumptions are corrected.
 **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 within single agent
 - Explicit lifecycle management with `close_agent`
 ## Analysis Flow
 ```
@@ -34,18 +40,21 @@ Session Detection
 Phase 1: Topic Understanding
   ├─ Parse topic/question
   ├─ Identify analysis dimensions (architecture, implementation, performance, security, concept, comparison, decision)
-   ├─ Initial scoping with user (focus areas, analysis depth)
+   ├─ Initial scoping with user (focus areas, perspectives, analysis depth)
   └─ Initialize discussion.md
-Phase 2: CLI Exploration (Serial Execution)
+Phase 2: Parallel Exploration (Subagent Execution)
-   ├─ Codebase context gathering (project structure, related files, constraints)
+   ├─ Determine exploration mode (single vs multi-perspective)
-   ├─ Gemini CLI analysis (build on codebase findings)
+   ├─ Parallel: spawn_agent × N (up to 4 perspectives)
-   └─ Aggregate findings into explorations.json
+   ├─ Batch wait: wait({ ids: [agent1, agent2, ...] })
   ├─ Aggregate findings from all perspectives
   ├─ Synthesize convergent/conflicting themes (if multi-perspective)
   └─ Write explorations.json or perspectives.json
 Phase 3: Interactive Discussion (Multi-Round)
   ├─ Present exploration findings to user
   ├─ Gather user feedback (deepen, adjust direction, ask questions, complete)
-   ├─ Execute targeted CLI analysis based on user direction
+   ├─ Execute targeted analysis via send_input or new subagent
   ├─ Update discussion.md with each round
   └─ Repeat until clarity achieved (max 5 rounds)
@@ -61,8 +70,13 @@ Phase 4: Synthesis & Conclusion
 ```
 .workflow/.analysis/ANL-{slug}-{date}/
 ├── discussion.md                # ⭐ Evolution of understanding & discussions
-├── exploration-codebase.json    # Phase 2: Codebase context and project structure
+├── exploration-codebase.json    # Phase 2: Codebase context (single perspective)
-├── explorations.json            # Phase 2: CLI analysis findings aggregated
+├── explorations/                # Phase 2: Multi-perspective explorations (if selected)
 │   ├── technical.json
 │   ├── architectural.json
 │   └── ...
 ├── explorations.json            # Phase 2: Single perspective findings
 ├── perspectives.json            # Phase 2: Multi-perspective findings with synthesis
 └── conclusions.json             # Phase 4: Final synthesis with recommendations
 ```
@@ -73,22 +87,24 @@ Phase 4: Synthesis & Conclusion
 | Artifact | Purpose |
 |----------|---------|
 | `discussion.md` | Initialized with session metadata and initial questions |
-| Session variables | Topic slug, dimensions, focus areas, analysis depth |
+| Session variables | Topic slug, dimensions, focus areas, perspectives, analysis depth |
-### Phase 2: CLI Exploration
+### Phase 2: Parallel Exploration
 | Artifact | Purpose |
 |----------|---------|
-| `exploration-codebase.json` | Codebase context: relevant files, patterns, constraints |
+| `exploration-codebase.json` | Single perspective: Codebase context (relevant files, patterns, constraints) |
-| `explorations.json` | CLI analysis findings: key findings, discussion points, open questions |
+| `explorations/*.json` | Multi-perspective: Individual exploration results per perspective |
-| Updated `discussion.md` | Round 1-2: Exploration results and initial analysis |
+| `explorations.json` | Single perspective: Aggregated findings |
 | `perspectives.json` | Multi-perspective: Findings with synthesis (convergent/conflicting themes) |
 | Updated `discussion.md` | Round 1: Exploration results and initial analysis |
 ### Phase 3: Interactive Discussion
 | Artifact | Purpose |
 |----------|---------|
-| Updated `discussion.md` | Round N (3-5): User feedback, direction adjustments, corrected assumptions |
+| Updated `discussion.md` | Round N (2-5): User feedback, direction adjustments, corrected assumptions |
-| CLI analysis results | Deepened analysis, adjusted perspective, or specific question answers |
+| Subagent analysis results | Deepened analysis, adjusted perspective, or specific question answers |
 ### Phase 4: Synthesis & Conclusion
@@ -155,10 +171,18 @@ For new analysis sessions, gather user preferences before exploration:
 - 最佳实践 (Best practices)
 - 问题诊断 (Problem diagnosis)
 **Analysis Perspectives** (Multi-select, max 4 for parallel exploration):
 - 技术视角 (Technical - implementation patterns, code structure)
 - 架构视角 (Architectural - system design, component interactions)
 - 安全视角 (Security - vulnerabilities, access control)
 - 性能视角 (Performance - bottlenecks, optimization)
 **Selection Note**: Single perspective = 1 subagent. Multiple perspectives = parallel subagents (up to 4).
 **Analysis Depth** (Single-select):
- 快速概览 (Quick overview, 10-15 minutes)
+- 快速概览 (Quick overview, 10-15 minutes, 1 agent)
- 标准分析 (Standard analysis, 30-60 minutes)
+- 标准分析 (Standard analysis, 30-60 minutes, 1-2 agents)
- 深度挖掘 (Deep dive, 1-2+ hours)
+- 深度挖掘 (Deep dive, 1-2+ hours, up to 4 parallel agents)
 ### Step 1.3: Initialize discussion.md
@@ -185,103 +209,234 @@ Create the main discussion document with session metadata, context, and placehol
 ---
-## Phase 2: CLI Exploration
+## Phase 2: Parallel Exploration
-**Objective**: Gather codebase context and execute deep analysis via CLI tools to build understanding of the topic.
+**Objective**: Gather codebase context and execute deep analysis via parallel subagents to build understanding of the topic.
-**Execution Model**: Sequential (serial) execution - gather codebase context first, then perform CLI analysis building on those findings.
+**Execution Model**: Parallel subagent execution - spawn multiple agents for different perspectives, batch wait for all results, then aggregate.
-### Step 2.1: Codebase Context Gathering
+**Key API Pattern**:
 ```
 spawn_agent × N → wait({ ids: [...] }) → aggregate → close_agent × N
 ```
-Use built-in tools to understand the codebase structure and identify relevant code related to the topic.
+### Step 2.1: Determine Exploration Mode
-**Context Gathering Activities**:
+Based on user's perspective selection in Phase 1, choose exploration mode:
 1. **Get project structure** - Execute `ccw tool exec get_modules_by_depth '{}'` to understand module organization
 2. **Search for related code** - Use Grep/Glob to find files matching topic keywords
 3. **Read project tech context** - Load `.workflow/project-tech.json` if available for constraints and integration points
 4. **Analyze patterns** - Identify common code patterns and architecture decisions
-**exploration-codebase.json Structure**:
+| Mode | Condition | Subagents | Output |
- `relevant_files[]`: Files related to the topic with relevance indicators
+|------|-----------|-----------|--------|
- `patterns[]`: Common code patterns and architectural styles identified
+| Single | Default or 1 perspective selected | 1 agent | `exploration-codebase.json`, `explorations.json` |
- `constraints[]`: Project-level constraints that affect the analysis
+| Multi-perspective | 2-4 perspectives selected | 2-4 agents | `explorations/*.json`, `perspectives.json` |
 - `integration_points[]`: Key integration points between modules
 - `_metadata`: Timestamp and context information
-**Key Information to Capture**:
+### Step 2.2: Parallel Subagent Exploration
 - Top 5-10 most relevant files with brief descriptions
 - Recurring patterns in code organization and naming
 - Project constraints (frameworks, architectural styles, tech stack)
 - Integration patterns between modules
 - Existing solutions or similar implementations
-### Step 2.2: Gemini CLI Analysis
+**⚠️ IMPORTANT**: Role files are NOT read by main process. Pass path in message, agent reads itself.
-Execute a comprehensive CLI analysis building on the codebase context gathered in Step 2.1.
+**Single Perspective Exploration**:
-**CLI Execution**: Synchronous analysis via Gemini with mode=analysis
+```javascript
 // spawn_agent with role path (agent reads itself)
 const explorationAgent = spawn_agent({
  message: `
 ## TASK ASSIGNMENT
-**Prompt Structure**:
+### MANDATORY FIRST STEPS (Agent Execute)
- **PURPOSE**: Clear goal and success criteria for the analysis
+1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
- **PRIOR CODEBASE CONTEXT**: Incorporate findings from Step 2.1 (top files, patterns, constraints)
+2. Read: .workflow/project-tech.json
- **TASK**: Specific investigation steps (analyze patterns, identify issues, generate insights, create discussion points)
+3. Read: .workflow/project-guidelines.json
 - **MODE**: analysis (read-only)
 - **CONTEXT**: Full codebase context with topic reference
 - **EXPECTED**: Structured output with evidence-based insights and confidence levels
 - **CONSTRAINTS**: Focus dimensions, ignore test files
-**Analysis Output Should Include**:
+---
 - Structured analysis organized by analysis dimensions
 - Specific insights tied to evidence (file references)
 - Questions to deepen understanding
 - Recommendations with clear rationale
 - Confidence levels (high/medium/low) for conclusions
 - 3-5 key findings with supporting details
-**Execution Guideline**: Wait for CLI analysis to complete before proceeding to aggregation.
+## Analysis Context
 Topic: ${topic_or_question}
 Dimensions: ${dimensions.join(', ')}
 Session: ${sessionFolder}
 ## Exploration Tasks
 1. Run: ccw tool exec get_modules_by_depth '{}'
 2. Execute relevant searches based on topic keywords
 3. Analyze identified files for patterns and constraints
 ## Deliverables
 Write findings to: ${sessionFolder}/exploration-codebase.json
 Schema: {relevant_files, patterns, constraints, integration_points, key_findings, _metadata}
 ## Success Criteria
 - [ ] Role definition read
 - [ ] At least 5 relevant files identified
 - [ ] Patterns and constraints documented
 - [ ] JSON output follows schema
 `
 })
 // Wait for single agent
 const result = wait({ ids: [explorationAgent], timeout_ms: 600000 })
 // Clean up
 close_agent({ id: explorationAgent })
 ```
 **Multi-Perspective Parallel Exploration** (up to 4 agents):
 ```javascript
 // Define perspectives based on user selection
 const selectedPerspectives = [
  { name: 'technical', focus: 'Implementation patterns and code structure' },
  { name: 'architectural', focus: 'System design and component interactions' },
  { name: 'security', focus: 'Security patterns and vulnerabilities' },
  { name: 'performance', focus: 'Performance bottlenecks and optimization' }
 ].slice(0, userSelectedCount)  // Max 4
 // Parallel spawn - all agents start immediately
 const agentIds = selectedPerspectives.map(perspective => {
  return spawn_agent({
    message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: .workflow/project-tech.json
 3. Read: .workflow/project-guidelines.json
 ---
 ## Analysis Context
 Topic: ${topic_or_question}
 Perspective: ${perspective.name} - ${perspective.focus}
 Session: ${sessionFolder}
 ## Perspective-Specific Exploration
 Focus on ${perspective.focus} aspects of the topic.
 ## Exploration Tasks
 1. Run: ccw tool exec get_modules_by_depth '{}'
 2. Execute searches focused on ${perspective.name} patterns
 3. Identify ${perspective.name}-specific findings
 ## Deliverables
 Write findings to: ${sessionFolder}/explorations/${perspective.name}.json
 Schema: {
  perspective: "${perspective.name}",
  relevant_files, patterns, key_findings,
  perspective_insights, open_questions,
  _metadata
 }
 ## Success Criteria
 - [ ] Role definition read
 - [ ] Perspective-specific insights identified
 - [ ] At least 3 relevant findings
 - [ ] JSON output follows schema
 `
  })
 })
 // Batch wait - TRUE PARALLELISM (key Codex advantage)
 const results = wait({
  ids: agentIds,
  timeout_ms: 600000  // 10 minutes for all
 })
 // Handle timeout
 if (results.timed_out) {
  // Some agents may still be running
  // Decide: continue waiting or use completed results
 }
 // Collect results from all perspectives
 const completedFindings = {}
 agentIds.forEach((agentId, index) => {
  const perspective = selectedPerspectives[index]
  if (results.status[agentId].completed) {
    completedFindings[perspective.name] = results.status[agentId].completed
  }
 })
 // Batch cleanup
 agentIds.forEach(id => close_agent({ id }))
 ```
 ### Step 2.3: Aggregate Findings
-Consolidate results from codebase context gathering and CLI analysis into a unified findings document.
+**Single Perspective Aggregation**:
-**explorations.json Structure**:
+Create `explorations.json` from single agent output:
- `session_id`: Reference to the analysis session
+- Extract key findings from exploration-codebase.json
 - Organize by analysis dimensions
 - Generate discussion points and open questions
 **Multi-Perspective Synthesis**:
 Create `perspectives.json` from parallel agent outputs:
 ```javascript
 const synthesis = {
  session_id: sessionId,
  timestamp: new Date().toISOString(),
  topic: topic_or_question,
  dimensions: dimensions,
  // Individual perspective findings
  perspectives: selectedPerspectives.map(p => ({
    name: p.name,
    findings: completedFindings[p.name]?.key_findings || [],
    insights: completedFindings[p.name]?.perspective_insights || [],
    questions: completedFindings[p.name]?.open_questions || []
  })),
  // Cross-perspective synthesis
  synthesis: {
    convergent_themes: extractConvergentThemes(completedFindings),
    conflicting_views: extractConflicts(completedFindings),
    unique_contributions: extractUniqueInsights(completedFindings)
  },
  // Aggregated for discussion
  aggregated_findings: mergeAllFindings(completedFindings),
  discussion_points: generateDiscussionPoints(completedFindings),
  open_questions: mergeOpenQuestions(completedFindings)
 }
 ```
 **perspectives.json Schema**:
 - `session_id`: Session identifier
 - `timestamp`: Completion time
 - `topic`: Original topic/question
- `dimensions[]`: Identified analysis dimensions
+- `dimensions[]`: Analysis dimensions
- `sources[]`: List of information sources (codebase exploration, CLI analysis)
+- `perspectives[]`: [{name, findings, insights, questions}]
- `key_findings[]`: Main insights with evidence
+- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
- `discussion_points[]`: Questions to engage user
+- `aggregated_findings[]`: Main insights across all perspectives
- `open_questions[]`: Unresolved or partially answered questions
+- `discussion_points[]`: Questions for user engagement
- `_metadata`: Processing metadata
+- `open_questions[]`: Unresolved questions
 **Aggregation Activities**:
 1. Extract key findings from CLI analysis output
 2. Cross-reference with codebase context
 3. Identify discussion points that benefit from user input
 4. Note open questions for follow-up investigation
 5. Organize findings by analysis dimension
 ### Step 2.4: Update discussion.md
-Append exploration results to the discussion timeline.
+Append Round 1 with exploration results.
-**Round 1-2 Sections** (Initial Understanding + Exploration Results):
+**Single Perspective Round 1**:
- **Codebase Findings**: Top relevant files and identified patterns
+- Sources analyzed (files, patterns)
- **Analysis Results**: Key findings, discussion points, recommendations
+- Key findings with evidence
- **Sources Analyzed**: Files and code patterns examined
+- Discussion points for user
 - Open questions
-**Documentation Standards**:
+**Multi-Perspective Round 1**:
- Include direct references to analyzed files (file:line format)
+- Per-perspective summary (brief)
- List discussion points as questions or open items
+- Synthesis section:
- Highlight key conclusions with confidence indicators
+  - Convergent themes (what all perspectives agree on)
- Note any constraints that affect the analysis
+  - Conflicting views (where perspectives differ)
  - Unique contributions (insights from specific perspectives)
 - Discussion points
 - Open questions
 **Success Criteria**:
- `exploration-codebase.json` created with comprehensive context
+- All subagents spawned and completed (or timeout handled)
- `explorations.json` created with aggregated findings
+- `exploration-codebase.json` OR `explorations/*.json` created
- `discussion.md` updated with Round 1-2 results
+- `explorations.json` OR `perspectives.json` created with aggregated findings
- All explorations completed successfully
+- `discussion.md` updated with Round 1 results
 - All agents closed properly
 - Ready for interactive discussion phase
 ---
@@ -292,6 +447,8 @@ Append exploration results to the discussion timeline.
 **Max Rounds**: 5 discussion rounds (can exit earlier if user indicates analysis is complete)
 **Execution Model**: Use `send_input` for deep interaction within same agent context, or spawn new agent for significantly different analysis angles.
 ### Step 3.1: Present Findings & Gather Feedback
 Display current understanding and exploration findings to the user.
@@ -306,69 +463,192 @@ Display current understanding and exploration findings to the user.
 | Option | Purpose | Next Action |
 |--------|---------|------------|
-| **继续深入** | Analysis direction is correct, deepen investigation | Execute deeper CLI analysis on same topic |
+| **继续深入** | Analysis direction is correct, deepen investigation | `send_input` to existing agent OR spawn new deepening agent |
-| **调整方向** | Different understanding or focus needed | Ask for adjusted focus, rerun CLI analysis |
+| **调整方向** | Different understanding or focus needed | Spawn new agent with adjusted focus |
-| **有具体问题** | Specific questions to ask about the topic | Capture questions, use CLI to answer them |
+| **有具体问题** | Specific questions to ask about the topic | `send_input` with specific questions OR spawn Q&A agent |
 | **分析完成** | Sufficient information obtained | Exit discussion loop, proceed to synthesis |
-### Step 3.2: Deepen Analysis
+### Step 3.2: Deepen Analysis (via send_input or new agent)
-When user selects "continue deepening", execute more detailed investigation in the same direction.
+When user selects "continue deepening", execute more detailed investigation.
-**Deepening Strategy**:
+**Option A: send_input to Existing Agent** (preferred if agent still active)
 - Focus on previously identified findings
 - Investigate edge cases and special scenarios
 - Identify patterns not yet discussed
 - Suggest implementation or improvement approaches
 - Provide risk/impact assessments
-**CLI Execution**: Synchronous analysis via Gemini with emphasis on elaboration and detail.
+```javascript
 // Continue with existing agent context (if not closed)
 send_input({
  id: explorationAgent,
  message: `
 ## CONTINUATION: Deepen Analysis
-**Analysis Scope**:
+Based on your initial exploration, the user wants deeper investigation.
 - Expand on prior findings with more specifics
 - Investigate corner cases and limitations
 - Propose concrete improvement strategies
 - Provide risk/impact ratings for findings
 - Generate follow-up questions
-### Step 3.3: Adjust Direction
+## Focus Areas for Deepening
 ${previousFindings.discussion_points.map(p => `- ${p}`).join('\n')}
-When user indicates a different focus is needed, shift the analysis angle.
+## Additional Tasks
 1. Investigate edge cases and special scenarios
 2. Identify patterns not yet discussed
 3. Suggest implementation or improvement approaches
 4. Provide risk/impact assessments
 ## Deliverables
 Append to: ${sessionFolder}/explorations.json (add "deepening_round_N" section)
 ## Success Criteria
 - [ ] Prior findings expanded with specifics
 - [ ] Corner cases and limitations identified
 - [ ] Concrete improvement strategies proposed
 `
 })
 const deepenResult = wait({ ids: [explorationAgent], timeout_ms: 600000 })
 ```
 **Option B: Spawn New Deepening Agent** (if prior agent closed)
 ```javascript
 const deepeningAgent = spawn_agent({
  message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/explorations.json (prior findings)
 3. Read: .workflow/project-tech.json
 ---
 ## Context
 Topic: ${topic_or_question}
 Prior Findings Summary: ${previousFindings.key_findings.slice(0,3).join('; ')}
 ## Deepening Task
 Expand on prior findings with more detailed investigation.
 ## Focus Areas
 ${previousFindings.discussion_points.map(p => `- ${p}`).join('\n')}
 ## Deliverables
 Update: ${sessionFolder}/explorations.json (add deepening insights)
 `
 })
 const result = wait({ ids: [deepeningAgent], timeout_ms: 600000 })
 close_agent({ id: deepeningAgent })
 ```
 ### Step 3.3: Adjust Direction (new agent)
 When user indicates a different focus is needed, spawn new agent with adjusted perspective.
 **Direction Adjustment Process**:
 1. Ask user for adjusted focus area (through AskUserQuestion)
-2. Determine new analysis angle (different dimension or perspective)
+2. Spawn new agent with different dimension/perspective
-3. Execute CLI analysis from new perspective
+3. Compare new insights with prior analysis
-4. Compare new insights with prior analysis
+4. Identify what was missed and why
 5. Identify what was missed and why
-**CLI Execution**: Synchronous analysis via Gemini with new perspective.
+```javascript
 // Spawn agent with adjusted focus
 const adjustedAgent = spawn_agent({
  message: `
 ## TASK ASSIGNMENT
-**Analysis Scope**:
+### MANDATORY FIRST STEPS (Agent Execute)
- Analyze topic from different dimension or angle
+1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
- Identify gaps in prior analysis
+2. Read: ${sessionFolder}/explorations.json (prior findings)
- Generate insights specific to new focus
+3. Read: .workflow/project-tech.json
 - Cross-reference with prior findings
 - Suggest investigation paths forward
-### Step 3.4: Answer Specific Questions
+---
 ## Context
 Topic: ${topic_or_question}
 Previous Focus: ${previousDimensions.join(', ')}
 **New Focus**: ${userAdjustedFocus}
 ## Adjusted Analysis Task
 Analyze the topic from ${userAdjustedFocus} perspective.
 ## Tasks
 1. Identify gaps in prior analysis
 2. Generate insights specific to new focus
 3. Cross-reference with prior findings
 4. Explain what was missed and why
 ## Deliverables
 Update: ${sessionFolder}/explorations.json (add adjusted_direction section)
 `
 })
 const result = wait({ ids: [adjustedAgent], timeout_ms: 600000 })
 close_agent({ id: adjustedAgent })
 ```
 ### Step 3.4: Answer Specific Questions (send_input preferred)
 When user has specific questions, address them directly.
-**Question Handling Process**:
+**Preferred: send_input to Active Agent**
 1. Capture user questions (through AskUserQuestion)
 2. Use CLI analysis or direct investigation to answer
 3. Provide evidence-based answers with supporting details
 4. Offer related follow-up investigations
-**CLI Execution**: Synchronous analysis via Gemini focused on specific questions.
+```javascript
 // Capture user questions first
 const userQuestions = await AskUserQuestion({
  question: "What specific questions do you have?",
  options: [/* predefined + custom */]
 })
-**Analysis Scope**:
+// Send questions to active agent
 send_input({
  id: activeAgent,
  message: `
 ## USER QUESTIONS
 Please answer the following questions based on your analysis:
 ${userQuestions.map((q, i) => `Q${i+1}: ${q}`).join('\n\n')}
 ## Requirements
 - Answer each question directly and clearly
- Provide evidence and examples
+- Provide evidence and file references
- Clarify ambiguous or complex points
+- Rate confidence for each answer (high/medium/low)
 - Suggest related investigation areas
- Rate confidence for each answer
+`
 })
 const answerResult = wait({ ids: [activeAgent], timeout_ms: 300000 })
 ```
 **Alternative: Spawn Q&A Agent**
 ```javascript
 const qaAgent = spawn_agent({
  message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/explorations.json (context)
 ---
 ## Q&A Task
 Answer user's specific questions:
 ${userQuestions.map((q, i) => `Q${i+1}: ${q}`).join('\n\n')}
 ## Requirements
 - Evidence-based answers with file references
 - Confidence rating for each answer
 - Suggest related investigation areas
 ## Deliverables
 Append to: ${sessionFolder}/explorations.json (add qa_round_N section)
 `
 })
 const result = wait({ ids: [qaAgent], timeout_ms: 300000 })
 close_agent({ id: qaAgent })
 ```
 ### Step 3.5: Document Each Round
@@ -498,6 +778,21 @@ Offer user follow-up actions based on analysis results.
 ## Configuration
 ### Analysis Perspectives
 Optional multi-perspective parallel exploration (single perspective is default, max 4):
 | Perspective | Role File | Focus | Best For |
 |------------|-----------|-------|----------|
 | **Technical** | `~/.codex/agents/cli-explore-agent.md` | Implementation, code patterns, technical feasibility | Understanding how and technical details |
 | **Architectural** | `~/.codex/agents/cli-explore-agent.md` | System design, scalability, component interactions | Understanding structure and organization |
 | **Security** | `~/.codex/agents/cli-explore-agent.md` | Security patterns, vulnerabilities, access control | Identifying security risks |
 | **Performance** | `~/.codex/agents/cli-explore-agent.md` | Bottlenecks, optimization, resource utilization | Finding performance issues |
 **Selection**: User can multi-select up to 4 perspectives in Phase 1, or default to single comprehensive view.
 **Subagent Assignment**: Each perspective gets its own subagent for true parallel exploration.
 ### Analysis Dimensions Reference
 Dimensions guide the scope and focus of analysis:
@@ -514,11 +809,11 @@ Dimensions guide the scope and focus of analysis:
 ### Analysis Depth Levels
-| Depth | Duration | Scope | Questions |
+| Depth | Duration | Scope | Subagents |
 |-------|----------|-------|-----------|
-| Quick (快速概览) | 10-15 min | Surface level understanding | 3-5 key questions |
+| Quick (快速概览) | 10-15 min | Surface level understanding | 1 agent, short timeout |
-| Standard (标准分析) | 30-60 min | Moderate depth with good coverage | 5-8 key questions |
+| Standard (标准分析) | 30-60 min | Moderate depth with good coverage | 1-2 agents |
-| Deep (深度挖掘) | 1-2+ hours | Comprehensive detailed analysis | 10+ key questions |
+| Deep (深度挖掘) | 1-2+ hours | Comprehensive detailed analysis | Up to 4 parallel agents |
 ### Focus Areas
@@ -537,27 +832,70 @@ Common focus areas that guide the analysis direction:
 | Situation | Action | Recovery |
 |-----------|--------|----------|
-| CLI timeout | Retry with shorter, focused prompt | Skip analysis or reduce depth |
+| **Subagent timeout** | Check `results.timed_out`, continue `wait()` or use partial results | Reduce scope, spawn single agent instead of parallel |
-| No relevant findings | Broaden search keywords or adjust scope | Ask user for clarification |
+| **Agent closed prematurely** | Cannot recover closed agent | Spawn new agent with prior context from explorations.json |
-| User disengaged | Summarize progress and offer break point | Save state for later continuation |
+| **Parallel agent partial failure** | Some agents complete, some fail | Use completed results, note gaps in synthesis |
-| Max rounds reached (5) | Force synthesis phase | Highlight remaining questions in conclusions |
+| **send_input to closed agent** | Error: agent not found | Spawn new agent with prior findings as context |
-| Session folder conflict | Append timestamp suffix to session ID | Create unique folder and continue |
+| **No relevant findings** | Broaden search keywords or adjust scope | Ask user for clarification |
 | **User disengaged** | Summarize progress and offer break point | Save state, keep agents alive for resume |
 | **Max rounds reached (5)** | Force synthesis phase | Highlight remaining questions in conclusions |
 | **Session folder conflict** | Append timestamp suffix to session ID | Create unique folder and continue |
 ### Codex-Specific Error Patterns
 ```javascript
 // Safe parallel execution with error handling
 try {
  const agentIds = perspectives.map(p => spawn_agent({ message: buildPrompt(p) }))
  const results = wait({ ids: agentIds, timeout_ms: 600000 })
  if (results.timed_out) {
    // Handle partial completion
    const completed = agentIds.filter(id => results.status[id].completed)
    const pending = agentIds.filter(id => !results.status[id].completed)
    // Option 1: Continue waiting for pending
    // const moreResults = wait({ ids: pending, timeout_ms: 300000 })
    // Option 2: Use partial results
    // processPartialResults(completed, results)
  }
  // Process all results
  processResults(agentIds, results)
 } finally {
  // ALWAYS cleanup, even on errors
  agentIds.forEach(id => {
    try { close_agent({ id }) } catch (e) { /* ignore */ }
  })
 }
 ```
 ---
 ## Iteration Patterns
-### First Analysis Session
+### First Analysis Session (Parallel Mode)
 ```
 User initiates: TOPIC="specific question"
   ├─ No session exists → New session mode
   ├─ Parse topic and identify dimensions
-   ├─ Scope analysis with user (focus areas, depth)
+   ├─ Scope analysis with user (focus areas, perspectives, depth)
   ├─ Create discussion.md
-   ├─ Gather codebase context
+   │
-   ├─ Execute Gemini CLI analysis
+   ├─ Determine exploration mode:
-   ├─ Aggregate findings
+   │   ├─ Single perspective → 1 subagent
   │   └─ Multi-perspective → 2-4 parallel subagents
   │
   ├─ Execute parallel exploration:
   │   ├─ spawn_agent × N (perspectives)
   │   ├─ wait({ ids: [...] })  ← TRUE PARALLELISM
   │   └─ close_agent × N
   │
   ├─ Aggregate findings (+ synthesis if multi-perspective)
   └─ Enter multi-round discussion loop
 ```
@@ -567,32 +905,50 @@ User initiates: TOPIC="specific question"
 User resumes: TOPIC="same topic" with --continue flag
   ├─ Session exists → Continue mode
   ├─ Load previous discussion.md
-   ├─ Load explorations.json
+   ├─ Load explorations.json or perspectives.json
   └─ Resume from last discussion round
 ```
-### Discussion Loop (Rounds 3-5)
+### Discussion Loop (Rounds 2-5)
 ```
 Each round:
   ├─ Present current findings
   ├─ Gather user feedback
   ├─ Process response:
-   │   ├─ Deepen → Deeper CLI analysis on same topic
+   │   ├─ Deepen → send_input to active agent OR spawn deepening agent
-   │   ├─ Adjust → New CLI analysis with adjusted focus
+   │   ├─ Adjust → spawn new agent with adjusted focus
-   │   ├─ Questions → CLI analysis answering specific questions
+   │   ├─ Questions → send_input with questions OR spawn Q&A agent
   │   └─ Complete → Exit loop for synthesis
   ├─ wait({ ids: [...] }) for result
   ├─ Update discussion.md
   └─ Repeat until user selects complete or max rounds reached
 ```
 ### Agent Lifecycle Management
 ```
 Subagent lifecycle:
   ├─ spawn_agent({ message }) → Create with role path + task
   ├─ wait({ ids, timeout_ms }) → Get results (ONLY way to get output)
   ├─ send_input({ id, message }) → Continue interaction (if not closed)
   └─ close_agent({ id }) → Cleanup (MUST do, cannot recover)
 Key rules:
   ├─ NEVER close before you're done with an agent
   ├─ ALWAYS use wait() to get results, NOT close_agent()
   ├─ Batch wait for parallel agents: wait({ ids: [a, b, c] })
   └─ Delay close_agent until all rounds complete (for send_input reuse)
 ```
 ### Completion Flow
 ```
 Final synthesis:
-   ├─ Consolidate all insights
+   ├─ Consolidate all insights from all rounds
   ├─ Generate conclusions.json
   ├─ Update discussion.md with final synthesis
   ├─ close_agent for any remaining active agents
   ├─ Offer follow-up options
   └─ Archive session artifacts
 ```
@@ -605,7 +961,8 @@ Final synthesis:
 1. **Clear Topic Definition**: Detailed topics lead to better dimension identification
 2. **User Context**: Understanding focus preferences helps scope the analysis
-3. **Scope Understanding**: Being clear about depth expectations sets correct analysis intensity
+3. **Perspective Selection**: Choose 2-4 perspectives for complex topics, single for focused queries
 4. **Scope Understanding**: Being clear about depth expectations sets correct analysis intensity
 ### During Analysis
@@ -615,6 +972,15 @@ Final synthesis:
 4. **Embrace Corrections**: Track wrong→right transformations as valuable learnings
 5. **Iterate Thoughtfully**: Each discussion round should meaningfully refine understanding
 ### Codex Subagent Best Practices
 1. **Role Path, Not Content**: Pass `~/.codex/agents/*.md` path in message, let agent read itself
 2. **Delay close_agent**: Keep agents active for `send_input` reuse during discussion rounds
 3. **Batch wait**: Use `wait({ ids: [a, b, c] })` for parallel agents, not sequential waits
 4. **Handle Timeouts**: Check `results.timed_out` and decide: continue waiting or use partial results
 5. **Explicit Cleanup**: Always `close_agent` when done, even on errors (use try/finally pattern)
 6. **send_input vs spawn**: Prefer `send_input` for same-context continuation, `spawn` for new angles
 ### Documentation Practices
 1. **Evidence-Based**: Every conclusion should reference specific code or patterns
@@ -622,6 +988,7 @@ Final synthesis:
 3. **Timeline Clarity**: Use clear timestamps for traceability
 4. **Evolution Tracking**: Document how understanding changed across rounds
 5. **Action Items**: Generate specific, actionable recommendations
 6. **Multi-Perspective Synthesis**: When using parallel perspectives, document convergent/conflicting themes
 ---
--- a/.codex/prompts/brainstorm-with-file.md
+++ b/.codex/prompts/brainstorm-with-file.md
@@ -1,5 +1,5 @@
 ---
-description: Interactive brainstorming with serial CLI collaboration, idea expansion, and documented thought evolution. Sequential multi-perspective analysis for Codex.
+description: Interactive brainstorming with parallel subagent collaboration, idea expansion, and documented thought evolution. Parallel multi-perspective analysis for Codex.
 argument-hint: "TOPIC=\"<idea or topic>\" [--perspectives=creative,pragmatic,systematic] [--max-ideas=<n>]"
 ---
@@ -7,23 +7,29 @@ argument-hint: "TOPIC=\"<idea or topic>\" [--perspectives=creative,pragmatic,sys
 ## Quick Start
-Interactive brainstorming workflow with **documented thought evolution**. Expands initial ideas through questioning, multi-perspective analysis, and iterative refinement.
+Interactive brainstorming workflow with **documented thought evolution**. Expands initial ideas through questioning, **parallel subagent analysis**, and iterative refinement.
-**Core workflow**: Seed Idea → Expand → Serial CLI Explore → Synthesize → Refine → Crystallize
+**Core workflow**: Seed Idea → Expand → Parallel Subagent Explore → Synthesize → Refine → Crystallize
 **Key features**:
 - **brainstorm.md**: Complete thought evolution timeline
- **Serial multi-perspective**: Creative → Pragmatic → Systematic (sequential)
+- **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 sequential phases:
+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 serial multi-perspective analysis
+2. **Divergent Exploration** - Gather codebase context and execute parallel multi-perspective analysis
-3. **Interactive Refinement** - Multi-round idea selection, deep-dive, and refinement
+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.
@@ -34,7 +40,11 @@ The key innovation is **documented thought evolution** that captures how ideas d
 .workflow/.brainstorm/BS-{slug}-{date}/
 ├── brainstorm.md                  # ⭐ Complete thought evolution timeline
 ├── exploration-codebase.json      # Phase 2: Codebase context
-├── perspectives.json              # Phase 2: Serial CLI findings
+├── 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
@@ -56,7 +66,8 @@ The key innovation is **documented thought evolution** that captures how ideas d
 | Artifact | Purpose |
 |----------|---------|
 | `exploration-codebase.json` | Codebase context: relevant files, patterns, architecture constraints |
-| `perspectives.json` | Serial CLI findings: creative, pragmatic, systematic perspectives |
+| `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
@@ -118,14 +129,43 @@ The workflow analyzes the topic text against predefined brainstorm dimensions.
 **Matching Logic**: Compare topic text against keyword lists to identify relevant dimensions.
-### Step 1.2: Initial Scoping (New Session Only)
+### 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)
+- 创意模式 (Creative mode - 15-20 minutes, 1 subagent)
- 平衡模式 (Balanced mode - 30-60 minutes)
+- 平衡模式 (Balanced mode - 30-60 minutes, 3 parallel subagents)
- 深度模式 (Deep mode - 1-2+ hours)
+- 深度模式 (Deep mode - 1-2+ hours, 3 parallel subagents + deep refinement)
 **Focus Areas** (Multi-select):
 - 技术方案 (Technical solutions)
@@ -133,9 +173,15 @@ For new brainstorm sessions, gather user preferences before exploration.
 - 创新突破 (Innovation breakthroughs)
 - 可行性评估 (Feasibility assessment)
-### Step 1.3: Expand Seed into Exploration Vectors
+**Constraints** (Multi-select):
 - 现有架构 (Existing architecture constraints)
 - 时间限制 (Time constraints)
 - 资源限制 (Resource constraints)
 - 无约束 (No constraints)
-Generate key questions that guide the brainstorming exploration.
+### 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?
@@ -146,15 +192,52 @@ Generate key questions that guide the brainstorming exploration.
 6. **Innovation angle**: What would make this 10x better?
 7. **Integration**: How does this fit with existing systems/processes?
-**Purpose**: These vectors guide each perspective's analysis and ensure comprehensive exploration.
+**Subagent for Vector Generation**:
-### Step 1.4: Initialize brainstorm.md
+```javascript
 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
@@ -162,6 +245,7 @@ Create the main brainstorm document with session metadata and expansion content.
 **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
@@ -170,16 +254,21 @@ Create the main brainstorm document with session metadata and expansion content.
 ## Phase 2: Divergent Exploration
-**Objective**: Gather codebase context and execute serial (sequential) multi-perspective analysis to generate diverse viewpoints.
+**Objective**: Gather codebase context and execute parallel multi-perspective analysis via subagents to generate diverse viewpoints.
-**Execution Model**: Serial execution (creative → pragmatic → systematic) - each perspective completes before starting the next, allowing later perspectives to build on earlier findings.
+**Execution Model**: Parallel subagent execution - spawn 3 perspective agents simultaneously, batch wait for all results, then aggregate.
 **Key API Pattern**:
 ```
 spawn_agent × 3 → wait({ ids: [...] }) → aggregate → close_agent × 3
 ```
 ### Step 2.1: Codebase Context Gathering
-Use built-in tools to understand the codebase structure and identify relevant code.
+Use built-in tools to understand the codebase structure before spawning perspective agents.
 **Context Gathering Activities**:
-1. **Get project structure** - Execute `ccw tool exec get_modules_by_depth '{}'` to understand module organization
+1. **Get project structure** - Execute `ccw tool exec get_modules_by_depth '{}'`
 2. **Search for related code** - Use Grep/Glob to find files matching topic keywords
 3. **Read project tech context** - Load `.workflow/project-tech.json` if available
 4. **Analyze patterns** - Identify common code patterns and architecture decisions
@@ -191,47 +280,178 @@ Use built-in tools to understand the codebase structure and identify relevant co
 - `integration_points[]`: Key integration patterns between modules
 - `_metadata`: Timestamp and context information
-### Step 2.2: Serial Multi-Perspective Analysis
+### Step 2.2: Parallel Multi-Perspective Analysis
-Execute perspectives sequentially: Creative (Gemini) → Pragmatic (Codex) → Systematic (Claude).
+**⚠️ IMPORTANT**: Role files are NOT read by main process. Pass path in message, agent reads itself.
-**Execution Guideline**: Each perspective builds on codebase context and runs to completion before the next begins.
+Spawn 3 perspective agents in parallel: Creative + Pragmatic + Systematic.
 **Perspective Definitions**:
-| Perspective | Purpose | Focus |
+| Perspective | Role File | Focus |
-|-------------|---------|-------|
+|-------------|-----------|-------|
-| Creative | Innovation and novelty | Cross-domain inspiration, challenging assumptions, moonshot ideas |
+| Creative | `~/.codex/agents/cli-explore-agent.md` | Innovation, cross-domain inspiration, challenging assumptions |
-| Pragmatic | Implementation reality | Technical feasibility, effort estimates, quick wins, blockers |
+| Pragmatic | `~/.codex/agents/cli-explore-agent.md` | Implementation feasibility, effort estimates, blockers |
-| Systematic | Architecture thinking | Problem decomposition, patterns, dependencies, scalability |
+| Systematic | `~/.codex/agents/cli-explore-agent.md` | Problem decomposition, patterns, scalability |
-**Analysis Approach**:
+**Parallel Subagent Execution**:
- Each perspective receives the exploration context
+
- Creative generates novel ideas first
+```javascript
- Pragmatic evaluates creative ideas for feasibility
+// Build shared context from codebase exploration
- Systematic provides architectural structure and tradeoffs
+const explorationContext = `
- Each builds understanding progressively
+CODEBASE CONTEXT:
 - Key files: ${explorationResults.relevant_files.slice(0,5).map(f => f.path).join(', ')}
 - Existing patterns: ${explorationResults.existing_patterns.slice(0,3).join(', ')}
 - Architecture constraints: ${explorationResults.architecture_constraints.slice(0,3).join(', ')}`
 // Define perspectives
 const perspectives = [
  {
    name: 'creative',
    focus: 'Innovation and novelty',
    tasks: [
      'Think beyond obvious solutions - what would be surprising/delightful?',
      'Explore cross-domain inspiration',
      'Challenge assumptions - what if the opposite were true?',
      'Generate moonshot ideas alongside practical ones'
    ]
  },
  {
    name: 'pragmatic',
    focus: 'Implementation reality',
    tasks: [
      'Evaluate technical feasibility of core concept',
      'Identify existing patterns/libraries that could help',
      'Estimate implementation complexity',
      'Highlight potential technical blockers'
    ]
  },
  {
    name: 'systematic',
    focus: 'Architecture thinking',
    tasks: [
      'Decompose the problem into sub-problems',
      'Identify architectural patterns that apply',
      'Map dependencies and interactions',
      'Consider scalability implications'
    ]
  }
 ]
 // Parallel spawn - all agents start immediately
 const agentIds = perspectives.map(perspective => {
  return spawn_agent({
    message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: .workflow/project-tech.json
 3. Read: .workflow/project-guidelines.json
 ---
 ## Brainstorm Context
 Topic: ${idea_or_topic}
 Perspective: ${perspective.name} - ${perspective.focus}
 Session: ${sessionFolder}
 ${explorationContext}
 ## ${perspective.name.toUpperCase()} Perspective Tasks
 ${perspective.tasks.map(t => `• ${t}`).join('\n')}
 ## Deliverables
 Write findings to: ${sessionFolder}/perspectives/${perspective.name}.json
 Schema: {
  perspective: "${perspective.name}",
  ideas: [{ title, description, novelty, feasibility, rationale }],
  key_findings: [],
  challenged_assumptions: [],
  open_questions: [],
  _metadata: { perspective, timestamp }
 }
 ## Success Criteria
 - [ ] Role definition read
 - [ ] 3-5 ideas generated with ratings
 - [ ] Key findings documented
 - [ ] JSON output follows schema
 `
  })
 })
 // Batch wait - TRUE PARALLELISM (key Codex advantage)
 const results = wait({
  ids: agentIds,
  timeout_ms: 600000  // 10 minutes for all
 })
 // Handle timeout
 if (results.timed_out) {
  // Some agents may still be running
  // Option: continue waiting or use completed results
 }
 // Collect results from all perspectives
 const completedFindings = {}
 agentIds.forEach((agentId, index) => {
  const perspective = perspectives[index]
  if (results.status[agentId].completed) {
    completedFindings[perspective.name] = results.status[agentId].completed
  }
 })
 // Batch cleanup
 agentIds.forEach(id => close_agent({ id }))
 ```
 ### Step 2.3: Aggregate Multi-Perspective Findings
-Consolidate results from all three perspectives into a unified findings document.
+Consolidate results from all three parallel perspective agents.
 **perspectives.json Structure**:
 - `session_id`: Reference to brainstorm session
 - `timestamp`: Completion time
 - `topic`: Original idea/topic
- `creative[]`: Creative perspective findings (ideas with novelty ratings)
+- `creative`: Creative perspective findings (ideas with novelty ratings)
- `pragmatic[]`: Pragmatic perspective findings (approaches with effort ratings)
+- `pragmatic`: Pragmatic perspective findings (approaches with effort ratings)
- `systematic[]`: Systematic perspective findings (architectural options)
+- `systematic`: Systematic perspective findings (architectural options)
- `synthesis`: Convergent themes, conflicting views, unique contributions
+- `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
 - `aggregated_ideas[]`: Merged ideas from all perspectives
 - `key_findings[]`: Main insights across all perspectives
 **Aggregation Activities**:
-1. Extract key findings from each perspective's CLI analysis
+1. Extract ideas and findings from each perspective's output
-2. Identify themes all perspectives agree on
+2. Identify themes all perspectives agree on (convergent)
 3. Note conflicting views and tradeoffs
 4. Extract unique contributions from each perspective
-5. Organize findings by brainstorm dimension
+5. Merge and deduplicate similar ideas
 ```javascript
 const synthesis = {
  session_id: sessionId,
  timestamp: new Date().toISOString(),
  topic: idea_or_topic,
  // Individual perspective findings
  creative: completedFindings.creative || {},
  pragmatic: completedFindings.pragmatic || {},
  systematic: completedFindings.systematic || {},
  // Cross-perspective synthesis
  synthesis: {
    convergent_themes: extractConvergentThemes(completedFindings),
    conflicting_views: extractConflicts(completedFindings),
    unique_contributions: extractUniqueInsights(completedFindings)
  },
  // Aggregated for refinement
  aggregated_ideas: mergeAllIdeas(completedFindings),
  key_findings: mergeKeyFindings(completedFindings)
 }
 ```
 ### Step 2.4: Update brainstorm.md
@@ -250,10 +470,12 @@ Append exploration results to the brainstorm timeline.
 - Note key assumptions and reasoning
 **Success Criteria**:
 - All 3 subagents spawned and completed (or timeout handled)
 - `exploration-codebase.json` created with comprehensive context
- `perspectives.json` created with all three perspective analyses
+- `perspectives/*.json` created for each perspective
 - `perspectives.json` created with aggregated findings and synthesis
 - `brainstorm.md` updated with Round 2 results
- All CLI executions completed successfully
+- All agents closed properly
 - Ready for interactive refinement phase
 ---
@@ -264,6 +486,8 @@ Append exploration results to the brainstorm timeline.
 **Max Rounds**: 6 refinement rounds (can exit earlier if user indicates completion)
 **Execution Model**: Use `send_input` for deep interaction within same agent context, or spawn new agent for significantly different exploration angles.
 ### Step 3.1: Present Findings & Gather User Direction
 Display current ideas and perspectives to the user.
@@ -278,63 +502,197 @@ Display current ideas and perspectives to the user.
 | Option | Purpose | Next Action |
 |--------|---------|------------|
-| **深入探索** | Explore selected ideas in detail | Execute deep-dive CLI analysis |
+| **深入探索** | Explore selected ideas in detail | `send_input` to active agent OR spawn deep-dive agent |
-| **继续发散** | Generate more ideas | Additional idea generation from new angles |
+| **继续发散** | Generate more ideas | Spawn new agent with different angles |
-| **挑战验证** | Test ideas critically | Devil's advocate challenge |
+| **挑战验证** | Test ideas critically | Spawn challenge agent (devil's advocate) |
-| **合并综合** | Combine multiple ideas | Synthesize selected ideas into unified concept |
+| **合并综合** | Combine multiple ideas | Spawn merge agent to synthesize |
 | **准备收敛** | Begin convergence | Exit refinement loop for synthesis |
-### Step 3.2: Deep Dive on Selected Ideas
+### Step 3.2: Deep Dive on Selected Ideas (via send_input or new agent)
-When user selects "deep dive", provide comprehensive analysis of ideas.
+When user selects "deep dive", provide comprehensive analysis.
-**Deep Dive Strategy**:
+**Option A: send_input to Existing Agent** (preferred if agent still active)
 - Elaborate core concept with specifics
 - Identify implementation requirements and dependencies
 - Analyze potential challenges and propose mitigations
 - Suggest proof-of-concept approach
 - Define success metrics and acceptance criteria
-**Analysis Scope**:
+```javascript
- Detailed concept breakdown
+// Continue with existing agent context
- Technical requirements and dependencies
+send_input({
- Risk/challenge analysis with proposed solutions
+  id: perspectiveAgent,  // Reuse agent from Phase 2 if not closed
- MVP definition for proof-of-concept
+  message: `
- Success criteria and measurement approach
+## CONTINUATION: Deep Dive Analysis
-### Step 3.3: Devil's Advocate Challenge
+Based on your initial exploration, the user wants deeper investigation on these ideas:
 ${selectedIdeas.map((idea, i) => `${i+1}. ${idea.title}`).join('\n')}
-When user selects "challenge", critically test ideas.
+## Deep Dive Tasks
 • Elaborate each concept in detail
 • Identify implementation requirements and dependencies
 • Analyze potential challenges and propose mitigations
 • Suggest proof-of-concept approach
 • Define success metrics
-**Challenge Strategy**:
+## Deliverables
- Identify strongest objections to each idea
+Write to: ${sessionFolder}/ideas/{idea-slug}.md for each selected idea
 - Challenge core assumptions and reasoning
 - Identify failure scenarios and edge cases
 - Consider competitive or alternative solutions
 - Assess whether the idea solves the right problem
-**Analysis Scope**:
+## Success Criteria
- 3+ strongest objections per idea
+- [ ] Each idea has detailed breakdown
- Challenge to assumptions and reasoning
+- [ ] Technical requirements documented
- Failure scenarios and recovery approaches
+- [ ] Risk analysis with mitigations
- Alternative solutions that could compete
+`
- Survivability rating after challenge (1-5)
+})
-### Step 3.4: Merge Multiple Ideas
+const deepDiveResult = wait({ ids: [perspectiveAgent], timeout_ms: 600000 })
 ```
 **Option B: Spawn New Deep-Dive Agent** (if prior agents closed)
 ```javascript
 const deepDiveAgent = spawn_agent({
  message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/perspectives.json (prior findings)
 3. Read: .workflow/project-tech.json
 ---
 ## Deep Dive Context
 Topic: ${idea_or_topic}
 Selected Ideas: ${selectedIdeas.map(i => i.title).join(', ')}
 ## Deep Dive Tasks
 ${selectedIdeas.map(idea => `
 ### ${idea.title}
 • Elaborate the core concept in detail
 • Identify implementation requirements
 • List potential challenges and mitigations
 • Suggest proof-of-concept approach
 • Define success metrics
 `).join('\n')}
 ## Deliverables
 Write: ${sessionFolder}/ideas/{idea-slug}.md for each idea
 Include for each:
 - Detailed concept description
 - Technical requirements list
 - Risk/challenge matrix
 - MVP definition
 - Success criteria
 `
 })
 const result = wait({ ids: [deepDiveAgent], timeout_ms: 600000 })
 close_agent({ id: deepDiveAgent })
 ```
 ### Step 3.3: Devil's Advocate Challenge (spawn new agent)
 When user selects "challenge", spawn a dedicated challenge agent.
 ```javascript
 const challengeAgent = spawn_agent({
  message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/perspectives.json (ideas to challenge)
 ---
 ## Challenge Context
 Topic: ${idea_or_topic}
 Ideas to Challenge:
 ${selectedIdeas.map((idea, i) => `${i+1}. ${idea.title}: ${idea.description}`).join('\n')}
 ## Devil's Advocate Tasks
 • For each idea, identify 3 strongest objections
 • Challenge core assumptions
 • Identify scenarios where this fails
 • Consider competitive/alternative solutions
 • Assess whether this solves the right problem
 • Rate survivability after challenge (1-5)
 ## Deliverables
 Return structured challenge results:
 {
  challenges: [{
    idea: "...",
    objections: [],
    challenged_assumptions: [],
    failure_scenarios: [],
    alternatives: [],
    survivability_rating: 1-5,
    strengthened_version: "..."
  }]
 }
 ## Success Criteria
 - [ ] 3+ objections per idea
 - [ ] Assumptions explicitly challenged
 - [ ] Survivability ratings assigned
 `
 })
 const result = wait({ ids: [challengeAgent], timeout_ms: 300000 })
 close_agent({ id: challengeAgent })
 ```
 ### Step 3.4: Merge Multiple Ideas (spawn merge agent)
 When user selects "merge", synthesize complementary ideas.
-**Merge Strategy**:
+```javascript
- Identify complementary elements and strengths
+const mergeAgent = spawn_agent({
- Resolve contradictions and conflicts
+  message: `
- Create unified concept preserving key strengths
+## TASK ASSIGNMENT
 - Ensure coherence and viability of merged result
-**Analysis Scope**:
+### MANDATORY FIRST STEPS (Agent Execute)
- Complementary elements from each source idea
+1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
- Contradiction resolution or documented tradeoffs
+2. Read: ${sessionFolder}/perspectives.json (source ideas)
- New combined strengths and capabilities
+
- Implementation considerations for merged approach
+---
 ## Merge Context
 Topic: ${idea_or_topic}
 Ideas to Merge:
 ${selectedIdeas.map((idea, i) => `
 ${i+1}. ${idea.title} (${idea.source_perspective})
   ${idea.description}
   Strengths: ${idea.strengths?.join(', ') || 'N/A'}
 `).join('\n')}
 ## Merge Tasks
 • Identify complementary elements
 • Resolve contradictions
 • Create unified concept
 • Preserve key strengths from each
 • Describe the merged solution
 • Assess viability of merged idea
 ## Deliverables
 Write to: ${sessionFolder}/ideas/merged-idea-{n}.md
 Include:
 - Merged concept description
 - Elements taken from each source idea
 - Contradictions resolved (or noted as tradeoffs)
 - New combined strengths
 - Implementation considerations
 ## Success Criteria
 - [ ] Coherent merged concept
 - [ ] Source attributions clear
 - [ ] Contradictions addressed
 `
 })
 const result = wait({ ids: [mergeAgent], timeout_ms: 300000 })
 close_agent({ id: mergeAgent })
 ```
 ### Step 3.5: Document Each Round
@@ -361,6 +719,7 @@ Update brainstorm.md with results from each refinement round.
 - User feedback processed for each round
 - `brainstorm.md` updated with all refinement rounds
 - Ideas in `ideas/` folder for selected deep-dives
 - All spawned agents closed properly
 - Exit condition reached (user selects converge or max rounds)
 ---
@@ -461,11 +820,37 @@ Dimensions guide brainstorming scope and focus:
 ### Brainstorm Modes
-| Mode | Duration | Intensity | Complexity |
+| Mode | Duration | Intensity | Subagents |
 |------|----------|-----------|-----------|
-| Creative | 15-20 min | High novelty | Exploratory |
+| Creative | 15-20 min | High novelty | 1 agent, short timeout |
-| Balanced | 30-60 min | Mixed | Moderate |
+| Balanced | 30-60 min | Mixed | 3 parallel agents |
-| Deep | 1-2+ hours | Comprehensive | Detailed |
+| Deep | 1-2+ hours | Comprehensive | 3 parallel agents + deep refinement |
 ### Collaboration Patterns
 | Pattern | Usage | Description |
 |---------|-------|-------------|
 | Parallel Divergence | New topic | All perspectives explore simultaneously via parallel subagents |
 | Sequential Deep-Dive | Promising idea | `send_input` to one agent for elaboration, others critique via new agents |
 | Debate Mode | Controversial approach | Spawn opposing agents to argue for/against |
 | Synthesis Mode | Ready to decide | Spawn synthesis agent combining insights from all perspectives |
 ### Context Overflow Protection
 **Per-Agent Limits**:
 - Main analysis output: < 3000 words
 - Sub-document (if any): < 2000 words each
 - Maximum sub-documents: 5 per perspective
 **Synthesis Protection**:
 - If total analysis > 100KB, synthesis reads only main analysis files (not sub-documents)
 - Large ideas automatically split into separate idea documents in ideas/ folder
 **Recovery Steps**:
 1. Check agent outputs for truncation or overflow
 2. Reduce scope: fewer perspectives or simpler topic
 3. Use structured brainstorm mode for more focused output
 4. Split complex topics into multiple sessions
 ---
@@ -473,18 +858,53 @@ Dimensions guide brainstorming scope and focus:
 | Situation | Action | Recovery |
 |-----------|--------|----------|
-| CLI timeout | Retry with shorter prompt | Skip perspective or reduce depth |
+| **Subagent timeout** | Check `results.timed_out`, continue `wait()` or use partial results | Reduce scope, use 2 perspectives instead of 3 |
-| No good ideas | Reframe problem or adjust constraints | Try new exploration angles |
+| **Agent closed prematurely** | Cannot recover closed agent | Spawn new agent with prior context from perspectives.json |
-| User disengaged | Summarize progress and offer break | Save state for later continuation |
+| **Parallel agent partial failure** | Some perspectives complete, some fail | Use completed results, note gaps in synthesis |
-| Perspectives conflict | Present as tradeoff options | Let user select preferred direction |
+| **send_input to closed agent** | Error: agent not found | Spawn new agent with prior findings as context |
-| Max rounds reached | Force synthesis phase | Highlight unresolved questions |
+| **No good ideas** | Reframe problem or adjust constraints | Try new exploration angles |
-| Session folder conflict | Append timestamp suffix | Create unique folder |
+| **User disengaged** | Summarize progress and offer break | Save state, keep agents alive for resume |
 | **Perspectives conflict** | Present as tradeoff options | Let user select preferred direction |
 | **Max rounds reached** | Force synthesis phase | Highlight unresolved questions |
 | **Session folder conflict** | Append timestamp suffix | Create unique folder |
 ### Codex-Specific Error Patterns
 ```javascript
 // Safe parallel execution with error handling
 try {
  const agentIds = perspectives.map(p => spawn_agent({ message: buildPrompt(p) }))
  const results = wait({ ids: agentIds, timeout_ms: 600000 })
  if (results.timed_out) {
    // Handle partial completion
    const completed = agentIds.filter(id => results.status[id].completed)
    const pending = agentIds.filter(id => !results.status[id].completed)
    // Option 1: Continue waiting for pending
    // const moreResults = wait({ ids: pending, timeout_ms: 300000 })
    // Option 2: Use partial results
    // processPartialResults(completed, results)
  }
  // Process all results
  processResults(agentIds, results)
 } finally {
  // ALWAYS cleanup, even on errors
  agentIds.forEach(id => {
    try { close_agent({ id }) } catch (e) { /* ignore */ }
  })
 }
 ```
 ---
 ## Iteration Patterns
-### First Brainstorm Session
+### First Brainstorm Session (Parallel Mode)
 ```
 User initiates: TOPIC="idea or topic"
@@ -494,8 +914,13 @@ User initiates: TOPIC="idea or topic"
   ├─ Create brainstorm.md
   ├─ Expand seed into vectors
   ├─ Gather codebase context
-   ├─ Execute serial CLI perspectives (Creative → Pragmatic → Systematic)
+   │
-   ├─ Aggregate findings
+   ├─ Execute parallel perspective exploration:
   │   ├─ spawn_agent × 3 (Creative + Pragmatic + Systematic)
   │   ├─ wait({ ids: [...] })  ← TRUE PARALLELISM
   │   └─ close_agent × 3
   │
   ├─ Aggregate findings with synthesis
   └─ Enter multi-round refinement loop
 ```
@@ -516,15 +941,32 @@ Each round:
   ├─ Present current findings and top ideas
   ├─ Gather user feedback (deep dive/diverge/challenge/merge/converge)
   ├─ Process response:
-   │   ├─ Deep Dive → CLI analysis elaborating on selected ideas
+   │   ├─ Deep Dive → send_input to active agent OR spawn deep-dive agent
-   │   ├─ Diverge → CLI analysis generating new ideas
+   │   ├─ Diverge → spawn new agent with different angles
-   │   ├─ Challenge → CLI analysis with devil's advocate
+   │   ├─ Challenge → spawn challenge agent (devil's advocate)
-   │   ├─ Merge → CLI analysis synthesizing multiple ideas
+   │   ├─ Merge → spawn merge agent to synthesize
   │   └─ Converge → Exit loop for synthesis
   ├─ wait({ ids: [...] }) for result
   ├─ Update brainstorm.md
   └─ Repeat until user selects converge or max rounds reached
 ```
 ### Agent Lifecycle Management
 ```
 Subagent lifecycle:
   ├─ spawn_agent({ message }) → Create with role path + task
   ├─ wait({ ids, timeout_ms }) → Get results (ONLY way to get output)
   ├─ send_input({ id, message }) → Continue interaction (if not closed)
   └─ close_agent({ id }) → Cleanup (MUST do, cannot recover)
 Key rules:
   ├─ NEVER close before you're done with an agent
   ├─ ALWAYS use wait() to get results, NOT close_agent()
   ├─ Batch wait for parallel agents: wait({ ids: [a, b, c] })
   └─ Consider keeping agents alive for send_input during refinement
 ```
 ### Completion Flow
 ```
@@ -532,6 +974,7 @@ Final synthesis:
   ├─ Consolidate all findings into top ideas
   ├─ Generate synthesis.json
   ├─ Update brainstorm.md with final conclusions
   ├─ close_agent for any remaining active agents
   ├─ Offer follow-up options
   └─ Archive session artifacts
 ```
@@ -554,6 +997,16 @@ Final synthesis:
 4. **Embrace Conflicts**: Perspective conflicts often reveal important tradeoffs
 5. **Iterate Thoughtfully**: Each refinement round should meaningfully advance ideas
 ### Codex Subagent Best Practices
 1. **Role Path, Not Content**: Pass `~/.codex/agents/*.md` path in message, let agent read itself
 2. **Parallel for Perspectives**: Use batch spawn + wait for 3 perspective agents
 3. **Delay close_agent for Refinement**: Keep perspective agents alive for `send_input` reuse
 4. **Batch wait**: Use `wait({ ids: [a, b, c] })` for parallel agents, not sequential waits
 5. **Handle Timeouts**: Check `results.timed_out` and decide: continue waiting or use partial results
 6. **Explicit Cleanup**: Always `close_agent` when done, even on errors (use try/finally pattern)
 7. **send_input vs spawn**: Prefer `send_input` for same-context deep-dive, `spawn` for new exploration angles
 ### Documentation Practices
 1. **Evidence-Based**: Every idea should reference codebase patterns or feasibility analysis
@@ -561,7 +1014,7 @@ Final synthesis:
 3. **Timeline Clarity**: Use clear timestamps for traceability
 4. **Evolution Tracking**: Document how ideas changed and evolved
 5. **Action Items**: Generate specific, implementable recommendations
-
+6. **Synthesis Quality**: Ensure convergent/conflicting themes are clearly documented
 ---
--- a/.codex/prompts/collaborative-plan-with-file.md
+++ b/.codex/prompts/collaborative-plan-with-file.md
@@ -1,34 +1,38 @@
 ---
-description: Serial collaborative planning with Plan Note - Single-agent sequential task generation, unified plan-note.md, conflict detection. Codex-optimized.
+description: Parallel collaborative planning with Plan Note - Multi-agent parallel task generation, unified plan-note.md, conflict detection. Codex subagent-optimized.
-argument-hint: "TASK=\"<description>\" [--max-domains=5]"
+argument-hint: "TASK=\"<description>\" [--max-agents=5]"
 ---
 # Codex Collaborative-Plan-With-File Workflow
 ## Quick Start
-Serial collaborative planning workflow using **Plan Note** architecture. Processes sub-domains sequentially, generates task plans, and detects conflicts across domains.
+Parallel collaborative planning workflow using **Plan Note** architecture. Spawns parallel subagents for each sub-domain, generates task plans concurrently, and detects conflicts across domains.
-**Core workflow**: Understand → Template → Sequential Planning → Conflict Detection → Completion
+**Core workflow**: Understand → Template → Parallel Subagent Planning → Conflict Detection → Completion
 **Key features**:
 - **plan-note.md**: Shared collaborative document with pre-allocated sections
- **Serial domain processing**: Each sub-domain planned sequentially via CLI
+- **Parallel subagent planning**: Each sub-domain planned by its own subagent concurrently
 - **Conflict detection**: Automatic file, dependency, and strategy conflict scanning
 - **No merge needed**: Pre-allocated sections eliminate merge conflicts
-**Note**: Codex does not support parallel agent execution. All domains are processed serially.
+**Codex-Specific Features**:
 - Parallel subagent execution via `spawn_agent` + batch `wait({ ids: [...] })`
 - Role loading via path (agent reads `~/.codex/agents/*.md` itself)
 - Pre-allocated sections per agent = no write conflicts
 - Explicit lifecycle management with `close_agent`
 ## Overview
-This workflow enables structured planning through sequential phases:
+This workflow enables structured planning through parallel-capable phases:
 1. **Understanding & Template** - Analyze requirements, identify sub-domains, create plan-note.md template
-2. **Sequential Planning** - Process each sub-domain serially via CLI analysis
+2. **Parallel Planning** - Spawn subagent per sub-domain, batch wait for all results
 3. **Conflict Detection** - Scan plan-note.md for conflicts across all domains
 4. **Completion** - Generate human-readable plan.md summary
-The key innovation is the **Plan Note** architecture - a shared collaborative document with pre-allocated sections per sub-domain, eliminating merge conflicts.
+The key innovation is the **Plan Note** architecture - a shared collaborative document with pre-allocated sections per sub-domain, eliminating merge conflicts. Combined with Codex's true parallel subagent execution, all domains are planned simultaneously.
 ## Output Structure
@@ -55,12 +59,12 @@ The key innovation is the **Plan Note** architecture - a shared collaborative do
 | `plan-note.md` | Collaborative template with pre-allocated task pool and evidence sections per domain |
 | `requirement-analysis.json` | Sub-domain assignments, TASK ID ranges, complexity assessment |
-### Phase 2: Sequential Planning
+### Phase 2: Parallel Planning
 | Artifact | Purpose |
 |----------|---------|
-| `agents/{domain}/plan.json` | Detailed implementation plan per domain |
+| `agents/{domain}/plan.json` | Detailed implementation plan per domain (from parallel subagent) |
-| Updated `plan-note.md` | Task pool and evidence sections filled for each domain |
+| Updated `plan-note.md` | Task pool and evidence sections filled by each subagent |
 ### Phase 3: Conflict Detection
@@ -166,59 +170,163 @@ Create the sub-domain configuration document.
 ---
-## Phase 2: Sequential Sub-Domain Planning
+## Phase 2: Parallel Sub-Domain Planning
-**Objective**: Process each sub-domain serially via CLI analysis, generating detailed plans and updating plan-note.md.
+**Objective**: Spawn parallel subagents for each sub-domain, generating detailed plans and updating plan-note.md concurrently.
-**Execution Model**: Serial processing - plan each domain completely before moving to the next. Later domains can reference earlier planning results.
+**Execution Model**: Parallel subagent execution - all domains planned simultaneously via `spawn_agent` + batch `wait`.
-### Step 2.1: Domain Planning Loop
+**Key API Pattern**:
 ```
 spawn_agent × N → wait({ ids: [...] }) → verify outputs → close_agent × N
 ```
-For each sub-domain in sequence:
+### Step 2.1: User Confirmation (unless autoMode)
 1. Execute Gemini CLI analysis for the current domain
 2. Parse CLI output into structured plan
 3. Save detailed plan as `agents/{domain}/plan.json`
 4. Update plan-note.md with task summaries and evidence
-**Planning Guideline**: Wait for each domain's CLI analysis to complete before proceeding to the next.
+Display identified sub-domains and confirm before spawning agents.
-### Step 2.2: CLI Planning for Each Domain
+```javascript
 // User confirmation
 if (!autoMode) {
  // Display sub-domains for user approval
  // Options: "开始规划" / "调整拆分" / "取消"
 }
 ```
-Execute synchronous CLI analysis to generate a detailed implementation plan.
+### Step 2.2: Parallel Subagent Planning
-**CLI Analysis Scope**:
+**⚠️ IMPORTANT**: Role files are NOT read by main process. Pass path in message, agent reads itself.
 - **PURPOSE**: Generate detailed implementation plan for the specific domain
 - **CONTEXT**: Domain description, related codebase files, prior domain results
 - **TASK**: Analyze domain, identify all necessary tasks, define dependencies, estimate effort
 - **EXPECTED**: JSON output with tasks, summaries, interdependencies, total effort
-**Analysis Output Should Include**:
+**Spawn All Domain Agents in Parallel**:
- Task breakdown with IDs from the assigned range
+
 ```javascript
 // Create agent directories first
 subDomains.forEach(sub => {
  // mkdir: ${sessionFolder}/agents/${sub.focus_area}/
 })
 // Parallel spawn - all agents start immediately
 const agentIds = subDomains.map(sub => {
  return spawn_agent({
    message: `
 ## TASK ASSIGNMENT
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first)
 2. Read: .workflow/project-tech.json
 3. Read: .workflow/project-guidelines.json
 4. Read: ${sessionFolder}/plan-note.md (understand template structure)
 5. Read: ${sessionFolder}/requirement-analysis.json (understand full context)
 ---
 ## Sub-Domain Context
 **Focus Area**: ${sub.focus_area}
 **Description**: ${sub.description}
 **TASK ID Range**: ${sub.task_id_range[0]}-${sub.task_id_range[1]}
 **Session**: ${sessionId}
 ## Dual Output Tasks
 ### Task 1: Generate Complete plan.json
 Output: ${sessionFolder}/agents/${sub.focus_area}/plan.json
 Include:
 - Task breakdown with IDs from assigned range (${sub.task_id_range[0]}-${sub.task_id_range[1]})
 - Dependencies within and across domains
 - Files to modify with specific locations
 - Effort and complexity estimates per task
 - Conflict risk assessment for each task
-### Step 2.3: Update plan-note.md After Each Domain
+### Task 2: Sync Summary to plan-note.md
-Parse CLI output and update the plan-note.md sections for the current domain.
+**Locate Your Sections** (pre-allocated, ONLY modify these):
 - Task Pool: "## 任务池 - ${toTitleCase(sub.focus_area)}"
 - Evidence: "## 上下文证据 - ${toTitleCase(sub.focus_area)}"
-**Task Summary Format** (for "任务池" section):
+**Task Summary Format**:
- Task header: `### TASK-{ID}: {Title} [{domain}]`
+### TASK-{ID}: {Title} [${sub.focus_area}]
- Fields: 状态 (status), 复杂度 (complexity), 依赖 (dependencies), 范围 (scope)
+- **状态**: pending
- Modification points: File paths with line ranges and change summaries
+- **复杂度**: Low/Medium/High
- Conflict risk assessment: Low/Medium/High
+- **依赖**: TASK-xxx (if any)
 - **范围**: Brief scope description
 - **修改点**: file:line - change summary
 - **冲突风险**: Low/Medium/High
-**Evidence Format** (for "上下文证据" section):
+**Evidence Format**:
- Related files with relevance descriptions
+- 相关文件: File list with relevance
- Existing patterns identified in codebase
+- 现有模式: Patterns identified
- Constraints discovered during analysis
+- 约束: Constraints discovered
 ## Execution Steps
 1. Explore codebase for domain-relevant files
 2. Generate complete plan.json
 3. Extract task summaries from plan.json
 4. Read ${sessionFolder}/plan-note.md
 5. Locate and fill your pre-allocated task pool section
 6. Locate and fill your pre-allocated evidence section
 7. Write back plan-note.md
 ## Important Rules
 - ONLY modify your pre-allocated sections (do NOT touch other domains)
 - Use assigned TASK ID range exclusively: ${sub.task_id_range[0]}-${sub.task_id_range[1]}
 - Include conflict_risk assessment for each task
 ## Success Criteria
 - [ ] Role definition read
 - [ ] plan.json generated with detailed tasks
 - [ ] plan-note.md updated with task pool and evidence
 - [ ] All tasks within assigned ID range
 `
  })
 })
 // Batch wait - TRUE PARALLELISM (key Codex advantage)
 const results = wait({
  ids: agentIds,
  timeout_ms: 900000  // 15 minutes for all planning agents
 })
 // Handle timeout
 if (results.timed_out) {
  const completed = agentIds.filter(id => results.status[id].completed)
  const pending = agentIds.filter(id => !results.status[id].completed)
  // Option: Continue waiting or use partial results
  // If most agents completed, proceed with partial results
 }
 // Verify outputs exist
 subDomains.forEach((sub, index) => {
  const agentId = agentIds[index]
  if (results.status[agentId].completed) {
    // Verify: agents/${sub.focus_area}/plan.json exists
    // Verify: plan-note.md sections populated
  }
 })
 // Batch cleanup
 agentIds.forEach(id => close_agent({ id }))
 ```
 ### Step 2.3: Verify plan-note.md Consistency
 After all agents complete, verify the shared document.
 **Verification Activities**:
 1. Read final plan-note.md
 2. Verify all task pool sections are populated
 3. Verify all evidence sections are populated
 4. Check for any accidental cross-section modifications
 5. Validate TASK ID uniqueness across all domains
 **Success Criteria**:
- All domains processed sequentially
+- All subagents spawned and completed (or timeout handled)
 - `agents/{domain}/plan.json` created for each domain
 - `plan-note.md` updated with all task pools and evidence sections
 - Task summaries follow consistent format
 - No TASK ID overlaps across domains
 - All agents closed properly
 ---
@@ -323,17 +431,51 @@ Present session statistics and next steps.
 | Situation | Action | Recovery |
 |-----------|--------|----------|
-| CLI timeout | Retry with shorter, focused prompt | Skip domain or reduce scope |
+| **Subagent timeout** | Check `results.timed_out`, continue `wait()` or use partial results | Reduce scope, plan remaining domains with new agent |
-| No tasks generated | Review domain description | Retry with refined description |
+| **Agent closed prematurely** | Cannot recover closed agent | Spawn new agent with domain context |
-| Section not found in plan-note | Recreate section defensively | Continue with new section |
+| **Parallel agent partial failure** | Some domains complete, some fail | Use completed results, re-spawn for failed domains |
-| Conflict detection fails | Continue with empty conflicts | Note in completion summary |
+| **plan-note.md write conflict** | Multiple agents write simultaneously | Pre-allocated sections prevent this; if detected, re-read and verify |
-| Session folder conflict | Append timestamp suffix | Create unique folder |
+| **Section not found in plan-note** | Agent creates section defensively | Continue with new section |
 | **No tasks generated** | Review domain description | Retry with refined description via new agent |
 | **Conflict detection fails** | Continue with empty conflicts | Note in completion summary |
 | **Session folder conflict** | Append timestamp suffix | Create unique folder |
 ### Codex-Specific Error Patterns
 ```javascript
 // Safe parallel planning with error handling
 try {
  const agentIds = subDomains.map(sub => spawn_agent({ message: buildPlanPrompt(sub) }))
  const results = wait({ ids: agentIds, timeout_ms: 900000 })
  if (results.timed_out) {
    const completed = agentIds.filter(id => results.status[id].completed)
    const pending = agentIds.filter(id => !results.status[id].completed)
    // Re-spawn for timed-out domains
    const retryIds = pending.map((id, i) => {
      const sub = subDomains[agentIds.indexOf(id)]
      return spawn_agent({ message: buildPlanPrompt(sub) })
    })
    const retryResults = wait({ ids: retryIds, timeout_ms: 600000 })
    retryIds.forEach(id => { try { close_agent({ id }) } catch(e) {} })
  }
 } finally {
  // ALWAYS cleanup
  agentIds.forEach(id => {
    try { close_agent({ id }) } catch (e) { /* ignore */ }
  })
 }
 ```
 ---
 ## Iteration Patterns
-### New Planning Session
+### New Planning Session (Parallel Mode)
 ```
 User initiates: TASK="task description"
@@ -341,9 +483,13 @@ User initiates: TASK="task description"
   ├─ Analyze task and identify sub-domains
   ├─ Create plan-note.md template
   ├─ Generate requirement-analysis.json
-   ├─ Process each domain serially:
+   │
-   │   ├─ CLI analysis → plan.json
+   ├─ Execute parallel planning:
-   │   └─ Update plan-note.md sections
+   │   ├─ spawn_agent × N (one per sub-domain)
   │   ├─ wait({ ids: [...] })  ← TRUE PARALLELISM
   │   └─ close_agent × N
   │
   ├─ Verify plan-note.md consistency
   ├─ Detect conflicts
   ├─ Generate plan.md summary
   └─ Report completion
@@ -355,8 +501,24 @@ User initiates: TASK="task description"
 User resumes: TASK="same task"
   ├─ Session exists → Continue mode
   ├─ Load plan-note.md and requirement-analysis.json
-   ├─ Resume from first incomplete domain
+   ├─ Identify incomplete domains (empty task pool sections)
-   └─ Continue sequential processing
+   ├─ Spawn agents for incomplete domains only
   └─ Continue with conflict detection
 ```
 ### Agent Lifecycle Management
 ```
 Subagent lifecycle:
   ├─ spawn_agent({ message }) → Create with role path + task
   ├─ wait({ ids, timeout_ms }) → Get results (ONLY way to get output)
   └─ close_agent({ id }) → Cleanup (MUST do, cannot recover)
 Key rules:
   ├─ Pre-allocated sections = no write conflicts
   ├─ ALWAYS use wait() to get results, NOT close_agent()
   ├─ Batch wait for all domain agents: wait({ ids: [a, b, c, ...] })
   └─ Verify plan-note.md after batch completion
 ```
 ---
@@ -376,6 +538,16 @@ User resumes: TASK="same task"
 3. **Check Dependencies**: Cross-domain dependencies should be documented explicitly
 4. **Inspect Details**: Review `agents/{domain}/plan.json` for specifics when needed
 ### Codex Subagent Best Practices
 1. **Role Path, Not Content**: Pass `~/.codex/agents/*.md` path in message, let agent read itself
 2. **Pre-allocated Sections**: Each agent only writes to its own sections - no write conflicts
 3. **Batch wait**: Use `wait({ ids: [a, b, c] })` for all domain agents, not sequential waits
 4. **Handle Timeouts**: Check `results.timed_out`, re-spawn for failed domains
 5. **Explicit Cleanup**: Always `close_agent` when done, even on errors (use try/finally)
 6. **Verify After Batch**: Read plan-note.md after all agents complete to verify consistency
 7. **TASK ID Isolation**: Pre-assigned non-overlapping ranges prevent ID conflicts
 ### After Planning
 1. **Resolve Conflicts**: Address high/critical conflicts before execution
--- a/.codex/prompts/issue-execute.md
+++ b/.codex/prompts/issue-execute.md
@@ -583,30 +583,13 @@ After ALL tasks in the solution pass implementation, testing, and verification,
 # Stage all modified files from all tasks
 git add path/to/file1.ts path/to/file2.ts ...
-# Commit with formatted solution summary
+# Commit with clean, standard format (NO solution metadata)
-git commit -m "$(cat <<'EOF'
+git commit -m "[commit_type](scope): [brief description of changes]"
 [commit_type](scope): [solution.description - brief]
-## Solution Summary
+# Example commits:
- **Solution-ID**: [solution_id]
+# feat(auth): add token refresh mechanism
- **Issue-ID**: [issue_id]
+# fix(payment): resolve timeout handling in checkout flow
- **Risk/Impact/Complexity**: [solution.analysis.risk]/[solution.analysis.impact]/[solution.analysis.complexity]
+# refactor(api): simplify error handling logic
 ## Tasks Completed
 - [T1] [task1.title]: [task1.action] [task1.scope]
 - [T2] [task2.title]: [task2.action] [task2.scope]
 - ...
 ## Files Modified
 - path/to/file1.ts
 - path/to/file2.ts
 - ...
 ## Verification
 - All unit tests passed
 - All acceptance criteria verified
 EOF
 )"
 ```
 **Commit Type Selection**:
@@ -644,16 +627,78 @@ EOF
 ## Step 4: Report Completion
-After ALL tasks in the solution are complete and committed, report to queue system:
+After ALL tasks in the solution are complete and committed, report to queue system with full solution metadata:
 ```javascript
 // ccw auto-detects worktree and uses main repo's .workflow/
 // Record ALL solution context here (NOT in git commit)
 shell_command({
  command: `ccw issue done ${item_id} --result '${JSON.stringify({
-    files_modified: ["path1", "path2"],
+    solution_id: solution.id,
    issue_id: issue_id,
    commit: {
      hash: commit_hash,
      type: commit_type,
      scope: commit_scope,
      message: commit_message
    },
    analysis: {
      risk: solution.analysis.risk,
      impact: solution.analysis.impact,
      complexity: solution.analysis.complexity
    },
    tasks_completed: solution.tasks.map(t => ({
      id: t.id,
      title: t.title,
      action: t.action,
      scope: t.scope
    })),
    files_modified: ["path1", "path2", ...],
    tests_passed: true,
-    commit: { hash: "abc123", type: "feat", tasks: ["T1", "T2"] },
+    verification: {
-    summary: "[What was accomplished]"
+      all_tests_passed: true,
      acceptance_criteria_met: true,
      regression_checked: true
    },
    summary: "[What was accomplished - brief description]"
  })}'`
 })
 ```
 **Complete Example**:
 ```javascript
 shell_command({
  command: `ccw issue done S-1 --result '${JSON.stringify({
    solution_id: "SOL-ISS-20251227-001-1",
    issue_id: "ISS-20251227-001",
    commit: {
      hash: "a1b2c3d4",
      type: "feat",
      scope: "auth",
      message: "feat(auth): add token refresh mechanism"
    },
    analysis: {
      risk: "low",
      impact: "medium",
      complexity: "medium"
    },
    tasks_completed: [
      { id: "T1", title: "Implement refresh token endpoint", action: "Add", scope: "src/auth/" },
      { id: "T2", title: "Add token rotation logic", action: "Create", scope: "src/auth/services/" }
    ],
    files_modified: [
      "src/auth/routes/token.ts",
      "src/auth/services/refresh.ts",
      "src/auth/middleware/validate.ts"
    ],
    tests_passed: true,
    verification: {
      all_tests_passed: true,
      acceptance_criteria_met: true,
      regression_checked: true
    },
    summary: "Implemented token refresh mechanism with automatic rotation"
  })}'`
 })
 ```
@@ -662,7 +707,13 @@ shell_command({
 ```javascript
 shell_command({
-  command: `ccw issue done ${item_id} --fail --reason '{"task_id": "TX", "error_type": "test_failure", "message": "..."}'`
+  command: `ccw issue done ${item_id} --fail --reason '${JSON.stringify({
    task_id: "TX",
    error_type: "test_failure",
    message: "Integration tests failed: timeout in token validation",
    files_attempted: ["path1", "path2"],
    commit: null
  })}'`
 })
 ```
--- a/ccw/docs-site/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx
+++ b/ccw/docs-site/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx
@@ -0,0 +1,218 @@
 import React, {type ReactNode} from 'react';
 import {translate} from '@docusaurus/Translate';
 import {useLocation} from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {applyTrailingSlash, removeTrailingSlash} from '@docusaurus/utils-common';
 import {mergeSearchStrings, useHistorySelector} from '@docusaurus/theme-common';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 import type {Props} from '@theme/NavbarItem/LocaleDropdownNavbarItem';
 import IconLanguage from '@theme/Icon/Language';
 import styles from './styles.module.css';
 function isBaseUrlPrefixOfPathname(baseUrl: string, pathname: string): boolean {
  const baseUrlNoTrailingSlash = removeTrailingSlash(baseUrl);
  return (
    pathname === baseUrlNoTrailingSlash ||
    pathname.startsWith(`${baseUrlNoTrailingSlash}/`) ||
    pathname.startsWith(baseUrl)
  );
 }
 function findBestMatchingBaseUrl({
  pathname,
  candidateBaseUrls,
 }: {
  pathname: string;
  candidateBaseUrls: string[];
 }): string | undefined {
  let bestBaseUrl: string | undefined;
  let bestBaseUrlLength = -1;
  for (const baseUrl of candidateBaseUrls) {
    if (!isBaseUrlPrefixOfPathname(baseUrl, pathname)) {
      continue;
    }
    const baseUrlNoTrailingSlash = removeTrailingSlash(baseUrl);
    if (baseUrlNoTrailingSlash.length > bestBaseUrlLength) {
      bestBaseUrl = baseUrl;
      bestBaseUrlLength = baseUrlNoTrailingSlash.length;
    }
  }
  return bestBaseUrl;
 }
 function stripBaseUrlPrefix({
  pathname,
  baseUrl,
 }: {
  pathname: string;
  baseUrl: string;
 }): string {
  const baseUrlNoTrailingSlash = removeTrailingSlash(baseUrl);
  if (pathname === baseUrl || pathname === baseUrlNoTrailingSlash) {
    return '';
  }
  if (pathname.startsWith(`${baseUrlNoTrailingSlash}/`)) {
    return pathname.slice(baseUrlNoTrailingSlash.length + 1);
  }
  if (pathname.startsWith(baseUrl)) {
    return pathname.slice(baseUrl.length);
  }
  return removeTrailingSlash(pathname).replace(/^\//, '');
 }
 function useLocaleDropdownUtils() {
  const {
    siteConfig,
    i18n: {localeConfigs},
  } = useDocusaurusContext();
  const {pathname} = useLocation();
  const search = useHistorySelector((history) => history.location.search);
  const hash = useHistorySelector((history) => history.location.hash);
  const candidateBaseUrls = Object.values(localeConfigs)
    .map((localeConfig) => localeConfig.baseUrl)
    .filter((baseUrl): baseUrl is string => typeof baseUrl === 'string');
  const currentBaseUrl =
    findBestMatchingBaseUrl({pathname, candidateBaseUrls}) ?? siteConfig.baseUrl;
  const canonicalPathname = applyTrailingSlash(pathname, {
    trailingSlash: siteConfig.trailingSlash,
    baseUrl: currentBaseUrl,
  });
  // Canonical pathname, without the baseUrl of the current locale.
  // We pick the longest matching locale baseUrl so that when we're already
  // under /docs/zh/, we strip /docs/zh/ (not just /docs/).
  const pathnameSuffix = stripBaseUrlPrefix({
    pathname: canonicalPathname,
    baseUrl: currentBaseUrl,
  });
  const getLocaleConfig = (locale: string) => {
    const localeConfig = localeConfigs[locale];
    if (!localeConfig) {
      throw new Error(
        `Docusaurus bug, no locale config found for locale=${locale}`,
      );
    }
    return localeConfig;
  };
  const createUrl = ({
    locale,
    fullyQualified,
  }: {
    locale: string;
    fullyQualified: boolean;
  }) => {
    const localeConfig = getLocaleConfig(locale);
    const newUrl = `${fullyQualified ? localeConfig.url : ''}`;
    return `${newUrl}${localeConfig.baseUrl}${pathnameSuffix}`;
  };
  const getBaseURLForLocale = (locale: string) => {
    const localeConfig = getLocaleConfig(locale);
    const isSameDomain = localeConfig.url === siteConfig.url;
    if (isSameDomain) {
      // Shorter paths if localized sites are hosted on the same domain.
      // We keep the `pathname://` escape hatch so we don't rely on SPA
      // navigation when baseUrl changes between locales.
      return `pathname://${createUrl({locale, fullyQualified: false})}`;
    }
    return createUrl({locale, fullyQualified: true});
  };
  return {
    getURL: (locale: string, options: {queryString: string | undefined}) => {
      // We have 2 query strings because
      // - there's the current one
      // - there's one user can provide through navbar config
      // see https://github.com/facebook/docusaurus/pull/8915
      const finalSearch = mergeSearchStrings(
        [search, options.queryString],
        'append',
      );
      return `${getBaseURLForLocale(locale)}${finalSearch}${hash}`;
    },
    getLabel: (locale: string) => {
      return getLocaleConfig(locale).label;
    },
    getLang: (locale: string) => {
      return getLocaleConfig(locale).htmlLang;
    },
  };
 }
 export default function LocaleDropdownNavbarItem({
  mobile,
  dropdownItemsBefore,
  dropdownItemsAfter,
  queryString,
  ...props
 }: Props): ReactNode {
  const utils = useLocaleDropdownUtils();
  const {
    i18n: {currentLocale, locales},
  } = useDocusaurusContext();
  const localeItems = locales.map((locale): LinkLikeNavbarItemProps => {
    return {
      label: utils.getLabel(locale),
      lang: utils.getLang(locale),
      to: utils.getURL(locale, {queryString}),
      target: '_self',
      autoAddBaseUrl: false,
      className:
        // eslint-disable-next-line no-nested-ternary
        locale === currentLocale
          ? // Similar idea as DefaultNavbarItem: select the right Infima active
            // class name. This cannot be substituted with isActive, because the
            // target URLs contain `pathname://` and therefore are not NavLinks!
            mobile
            ? 'menu__link--active'
            : 'dropdown__link--active'
          : '',
    };
  });
  const items = [...dropdownItemsBefore, ...localeItems, ...dropdownItemsAfter];
  // Mobile is handled a bit differently
  const dropdownLabel = mobile
    ? translate({
        message: 'Languages',
        id: 'theme.navbar.mobileLanguageDropdown.label',
        description: 'The label for the mobile language switcher dropdown',
      })
    : utils.getLabel(currentLocale);
  return (
    <DropdownNavbarItem
      {...props}
      mobile={mobile}
      label={
        <>
          <IconLanguage className={styles.iconLanguage} />
          {dropdownLabel}
        </>
      }
      items={items}
    />
  );
 }
--- a/ccw/docs-site/src/theme/NavbarItem/LocaleDropdownNavbarItem/styles.module.css
+++ b/ccw/docs-site/src/theme/NavbarItem/LocaleDropdownNavbarItem/styles.module.css
@@ -0,0 +1,5 @@
 .iconLanguage {
  vertical-align: text-bottom;
  margin-right: 5px;
 }