mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-09 02:24:11 +08:00
Add runtime JavaScript file for Chinese documentation build
This commit is contained in:
catlog22
328
.codex/skills/workflow-brainstorm-auto-parallel/SKILL.md
Normal file
328
.codex/skills/workflow-brainstorm-auto-parallel/SKILL.md
Normal file
@@ -0,0 +1,328 @@
|
||||
---
|
||||
name: workflow-brainstorm-auto-parallel
|
||||
description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives. Triggers on "workflow:brainstorm:auto-parallel".
|
||||
allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep
|
||||
---
|
||||
|
||||
# Workflow Brainstorm Auto-Parallel
|
||||
|
||||
Parallel brainstorming automation orchestrating interactive framework generation, concurrent multi-role analysis, and synthesis integration to produce comprehensive guidance specifications.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Auto-Parallel Orchestrator (SKILL.md) │
|
||||
│ → Pure coordinator: Execute phases, parse outputs, manage agents│
|
||||
└───────────────┬─────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────┼───────────┬───────────┐
|
||||
↓ ↓ ↓ ↓
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Phase 0 │ │ Phase 1 │ │ Phase 2 │ │ Phase 3 │
|
||||
│ Parse │ │Framework│ │Parallel │ │Synthesis│
|
||||
│ Params │ │Generate │ │ Roles │ │Integrate│
|
||||
└─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
↓ ↓ ↓ ↓
|
||||
count, guidance- N role synthesis-
|
||||
style-skill specification analyses specification
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **Pure Orchestrator**: Execute phases in sequence (Phase 1, 3 sequential; Phase 2 parallel)
|
||||
2. **Auto-Continue**: All phases run autonomously without user intervention between phases
|
||||
3. **Subagent Lifecycle**: Explicit lifecycle management with spawn_agent → wait → close_agent
|
||||
4. **Progressive Phase Loading**: Phase docs are read on-demand when phase executes
|
||||
5. **Parallel Execution**: Phase 2 launches N role agents concurrently
|
||||
6. **Role Path Loading**: Subagent roles loaded via path reference in MANDATORY FIRST STEPS
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers.
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Parameter Parsing:
|
||||
├─ Extract --count N (default: 3, max: 9)
|
||||
├─ Extract --style-skill package-name (optional, for ui-designer)
|
||||
└─ Validate style SKILL package exists
|
||||
|
||||
Phase 1: Interactive Framework Generation
|
||||
└─ Ref: phases/01-interactive-framework.md
|
||||
├─ Sub-phases: Phase 0-5 (Context → Topic → Roles → Questions → Conflicts → Spec)
|
||||
├─ Output: guidance-specification.md + workflow-session.json
|
||||
└─ Parse: selected_roles[], session_id
|
||||
|
||||
Phase 2: Parallel Role Analysis
|
||||
└─ Ref: phases/02-parallel-role-analysis.md
|
||||
├─ Spawn N conceptual-planning-agent (concurrent execution)
|
||||
├─ For each role: Execute framework-based analysis
|
||||
├─ Optional: ui-designer appends --style-skill if provided
|
||||
├─ Lifecycle: spawn_agent → batch wait → close_agent
|
||||
└─ Output: [role]/analysis*.md (one per role)
|
||||
|
||||
Phase 3: Synthesis Integration
|
||||
└─ Ref: phases/03-synthesis-integration.md
|
||||
├─ Spawn cross-role analysis agent
|
||||
├─ User interaction: Enhancement selection + clarifications
|
||||
├─ Spawn parallel update agents (one per role)
|
||||
├─ Lifecycle: spawn_agent → wait → close_agent for each agent
|
||||
└─ Output: synthesis-specification.md + updated analyses
|
||||
|
||||
Return:
|
||||
└─ Summary with session info and next steps
|
||||
```
|
||||
|
||||
**Phase Reference Documents** (read on-demand when phase executes):
|
||||
|
||||
| Phase | Document | Purpose |
|
||||
|-------|----------|---------|
|
||||
| 1 | [phases/01-interactive-framework.md](phases/01-interactive-framework.md) | Interactive clarification generating confirmed guidance specification through role-based analysis |
|
||||
| 2 | [phases/02-parallel-role-analysis.md](phases/02-parallel-role-analysis.md) | Unified role-specific analysis generation with interactive context gathering and concurrent execution |
|
||||
| 3 | [phases/03-synthesis-integration.md](phases/03-synthesis-integration.md) | Cross-role synthesis integration with intelligent Q&A and targeted updates |
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is parameter parsing
|
||||
2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
|
||||
3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
|
||||
4. **Auto-Continue**: Execute next pending phase automatically after previous completes
|
||||
5. **Track Progress**: Phase execution state managed through workflow-session.json
|
||||
6. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After completing each phase, immediately proceed to next
|
||||
7. **Parallel Execution**: Phase 2 spawns multiple agent tasks simultaneously for concurrent execution
|
||||
8. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
|
||||
9. **Explicit Lifecycle**: Always close_agent after wait completes to free resources
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
workflow:brainstorm:auto-parallel "<topic>" [--count N] [--style-skill package-name]
|
||||
```
|
||||
|
||||
**Recommended Structured Format**:
|
||||
```bash
|
||||
workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name]
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `topic` (required): Topic or challenge description (structured format recommended)
|
||||
- `--count N` (optional): Number of roles to select (default: 3, max: 9)
|
||||
- `--style-skill package-name` (optional): Style SKILL package to load for ui-designer (located at `.codex/skills/style-{package-name}/`)
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Phase 0 → Phase 1
|
||||
|
||||
**Input**:
|
||||
- `topic`: User-provided topic or challenge description
|
||||
- `count`: Number of roles to select (parsed from --count parameter)
|
||||
- `style_skill_package`: Style SKILL package name (parsed from --style-skill parameter)
|
||||
|
||||
**Output**: None (in-memory variables)
|
||||
|
||||
### Phase 1 → Phase 2
|
||||
|
||||
**Input**: `topic`, `count`, `style_skill_package`
|
||||
|
||||
**Output**:
|
||||
- `session_id`: Workflow session identifier (WFS-{topic-slug})
|
||||
- `selected_roles[]`: Array of selected role names
|
||||
- `guidance-specification.md`: Framework content
|
||||
- `workflow-session.json`: Session metadata
|
||||
|
||||
**Parsing**:
|
||||
```javascript
|
||||
// Read workflow-session.json after Phase 1
|
||||
const session_data = Read(".workflow/active/WFS-{topic}/workflow-session.json");
|
||||
const selected_roles = session_data.selected_roles;
|
||||
const session_id = session_data.session_id;
|
||||
const style_skill_package = session_data.style_skill_package || null;
|
||||
```
|
||||
|
||||
### Phase 2 → Phase 3
|
||||
|
||||
**Input**: `session_id`, `selected_roles[]`, `style_skill_package`
|
||||
|
||||
**Output**:
|
||||
- `[role]/analysis*.md`: One analysis per selected role
|
||||
- `.superdesign/design_iterations/`: UI design artifacts (if --style-skill provided)
|
||||
|
||||
**Validation**:
|
||||
```javascript
|
||||
// Verify all role analyses created
|
||||
for (const role of selected_roles) {
|
||||
const analysis_path = `${brainstorm_dir}/${role}/analysis.md`;
|
||||
if (!exists(analysis_path)) {
|
||||
ERROR: `Missing analysis for ${role}`;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3 → Completion
|
||||
|
||||
**Input**: `session_id`, all role analyses, guidance-specification.md
|
||||
|
||||
**Output**:
|
||||
- `synthesis-specification.md`: Integrated cross-role analysis
|
||||
- Updated `[role]/analysis*.md` with clarifications
|
||||
|
||||
**Validation**:
|
||||
```javascript
|
||||
const synthesis_path = `${brainstorm_dir}/synthesis-specification.md`;
|
||||
if (!exists(synthesis_path)) {
|
||||
ERROR: "Synthesis generation failed";
|
||||
}
|
||||
```
|
||||
|
||||
## Subagent API Reference
|
||||
|
||||
### spawn_agent
|
||||
|
||||
Create a new subagent with task assignment.
|
||||
|
||||
```javascript
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## TASK CONTEXT
|
||||
${taskContext}
|
||||
|
||||
## DELIVERABLES
|
||||
${deliverables}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### wait
|
||||
|
||||
Get results from subagent (only way to retrieve results).
|
||||
|
||||
```javascript
|
||||
const result = wait({
|
||||
ids: [agentId],
|
||||
timeout_ms: 600000 // 10 minutes
|
||||
})
|
||||
|
||||
if (result.timed_out) {
|
||||
// Handle timeout - can continue waiting or send_input to prompt completion
|
||||
}
|
||||
|
||||
// Check completion status
|
||||
if (result.status[agentId].completed) {
|
||||
const output = result.status[agentId].completed;
|
||||
}
|
||||
```
|
||||
|
||||
### send_input
|
||||
|
||||
Continue interaction with active subagent (for clarification or follow-up).
|
||||
|
||||
```javascript
|
||||
send_input({
|
||||
id: agentId,
|
||||
message: `
|
||||
## CLARIFICATION ANSWERS
|
||||
${answers}
|
||||
|
||||
## NEXT STEP
|
||||
Continue with analysis generation.
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### close_agent
|
||||
|
||||
Clean up subagent resources (irreversible).
|
||||
|
||||
```javascript
|
||||
close_agent({ id: agentId })
|
||||
```
|
||||
|
||||
## Session Management
|
||||
|
||||
**⚡ FIRST ACTION**: Check `.workflow/active/` for existing sessions before Phase 1
|
||||
|
||||
**Multiple Sessions Support**:
|
||||
- Different Codex instances can have different brainstorming sessions
|
||||
- If multiple sessions found, prompt user to select
|
||||
- If single session found, use it
|
||||
- If no session exists, create `WFS-[topic-slug]`
|
||||
|
||||
**Session Continuity**:
|
||||
- MUST use selected session for all phases
|
||||
- Each role's context stored in session directory
|
||||
- Session isolation: Each session maintains independent state
|
||||
|
||||
## Output Structure
|
||||
|
||||
**Phase 1 Output**:
|
||||
- `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
|
||||
- `.workflow/active/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
|
||||
|
||||
**Phase 2 Output**:
|
||||
- `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
|
||||
- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
|
||||
|
||||
**Phase 3 Output**:
|
||||
- `.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
|
||||
- Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
|
||||
|
||||
**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
|
||||
**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.codex/skills/style-{package-name}/`
|
||||
|
||||
## Available Roles
|
||||
|
||||
- data-architect (数据架构师)
|
||||
- product-manager (产品经理)
|
||||
- product-owner (产品负责人)
|
||||
- scrum-master (敏捷教练)
|
||||
- subject-matter-expert (领域专家)
|
||||
- system-architect (系统架构师)
|
||||
- test-strategist (测试策略师)
|
||||
- ui-designer (UI 设计师)
|
||||
- ux-expert (UX 专家)
|
||||
|
||||
**Role Selection**: Handled by Phase 1 (artifacts) - intelligent recommendation + user selection
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Role selection failure**: Phase 1 defaults to product-manager with explanation
|
||||
- **Agent execution failure**: Agent-specific retry with minimal dependencies
|
||||
- **Template loading issues**: Agent handles graceful degradation
|
||||
- **Synthesis conflicts**: Phase 3 highlights disagreements without resolution
|
||||
- **Context overflow protection**: Per-role limits enforced by conceptual-planning-agent
|
||||
- **Agent lifecycle errors**: Ensure close_agent in error paths to prevent resource leaks
|
||||
|
||||
## Reference Information
|
||||
|
||||
**File Structure**:
|
||||
```
|
||||
.workflow/active/WFS-[topic]/
|
||||
├── workflow-session.json # Session metadata ONLY
|
||||
└── .brainstorming/
|
||||
├── guidance-specification.md # Framework (Phase 1)
|
||||
├── {role}/
|
||||
│ ├── analysis.md # Main document (with optional @references)
|
||||
│ └── analysis-{slug}.md # Section documents (max 5)
|
||||
└── synthesis-specification.md # Integration (Phase 3)
|
||||
```
|
||||
|
||||
**Next Steps** (returned to user):
|
||||
```
|
||||
Brainstorming complete for session: {sessionId}
|
||||
Roles analyzed: {count}
|
||||
Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md
|
||||
|
||||
✅ Next Steps:
|
||||
1. workflow:plan --session {sessionId} # Generate implementation plan
|
||||
```
|
||||
@@ -0,0 +1,456 @@
|
||||
## Overview
|
||||
|
||||
Seven-phase workflow: **Context collection** → **Topic analysis** → **Role selection** → **Role questions** → **Conflict resolution** → **Final check** → **Generate specification**
|
||||
|
||||
All user interactions use AskUserQuestion tool (max 4 questions per call, multi-round).
|
||||
|
||||
**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
|
||||
**Output**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
|
||||
**Core Principle**: Questions dynamically generated from project context + topic keywords, NOT generic templates
|
||||
|
||||
**Parameters**:
|
||||
- `topic` (required): Topic or challenge description (structured format recommended)
|
||||
- `--count N` (optional): Number of roles to select (system recommends N+2 options, default: 3)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Phase Summary
|
||||
|
||||
| Phase | Goal | AskUserQuestion | Storage |
|
||||
|-------|------|-----------------|---------|
|
||||
| 0 | Context collection | - | context-package.json |
|
||||
| 1 | Topic analysis | 2-4 questions | intent_context |
|
||||
| 2 | Role selection | 1 multi-select | selected_roles |
|
||||
| 3 | Role questions | 3-4 per role | role_decisions[role] |
|
||||
| 4 | Conflict resolution | max 4 per round | cross_role_decisions |
|
||||
| 4.5 | Final check | progressive rounds | additional_decisions |
|
||||
| 5 | Generate spec | - | guidance-specification.md |
|
||||
|
||||
### AskUserQuestion Pattern
|
||||
|
||||
```javascript
|
||||
// Single-select (Phase 1, 3, 4)
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "{问题文本}",
|
||||
header: "{短标签}", // max 12 chars
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "{选项}", description: "{说明和影响}" },
|
||||
{ label: "{选项}", description: "{说明和影响}" },
|
||||
{ label: "{选项}", description: "{说明和影响}" }
|
||||
]
|
||||
}
|
||||
// ... max 4 questions per call
|
||||
]
|
||||
})
|
||||
|
||||
// Multi-select (Phase 2)
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "请选择 {count} 个角色",
|
||||
header: "角色选择",
|
||||
multiSelect: true,
|
||||
options: [/* max 4 options per call */]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
### Multi-Round Execution
|
||||
|
||||
```javascript
|
||||
const BATCH_SIZE = 4;
|
||||
for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
|
||||
const batch = allQuestions.slice(i, i + BATCH_SIZE);
|
||||
AskUserQuestion({ questions: batch });
|
||||
// Store responses before next round
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Management
|
||||
|
||||
- Check `.workflow/active/` for existing sessions
|
||||
- Multiple → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
|
||||
- Parse `--count N` parameter (default: 3)
|
||||
- Store decisions in `workflow-session.json`
|
||||
|
||||
---
|
||||
|
||||
## Execution Phases
|
||||
|
||||
### Phase 0: Context Collection
|
||||
|
||||
**Goal**: Gather project context BEFORE user interaction
|
||||
|
||||
**Steps**:
|
||||
1. Check if `context-package.json` exists → Skip if valid
|
||||
2. Invoke `context-search-agent` (BRAINSTORM MODE - lightweight)
|
||||
3. Output: `.workflow/active/WFS-{session-id}/.process/context-package.json`
|
||||
|
||||
**Graceful Degradation**: If agent fails, continue to Phase 1 without context
|
||||
|
||||
```javascript
|
||||
// Spawn context-search-agent
|
||||
const contextAgentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## Task Objective
|
||||
Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only).
|
||||
|
||||
## Assigned Context
|
||||
- **Session**: ${session_id}
|
||||
- **Task**: ${task_description}
|
||||
- **Output**: .workflow/${session_id}/.process/context-package.json
|
||||
|
||||
## Required Output Fields
|
||||
metadata, project_context, assets, dependencies, conflict_detection
|
||||
`
|
||||
});
|
||||
|
||||
// Wait for completion
|
||||
const contextResult = wait({
|
||||
ids: [contextAgentId],
|
||||
timeout_ms: 300000 // 5 minutes
|
||||
});
|
||||
|
||||
// Clean up agent
|
||||
close_agent({ id: contextAgentId });
|
||||
|
||||
// Check result
|
||||
if (contextResult.timed_out) {
|
||||
console.warn("Context gathering timed out, continuing without context");
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 1: Topic Analysis
|
||||
|
||||
**Goal**: Extract keywords/challenges enriched by Phase 0 context
|
||||
|
||||
**Steps**:
|
||||
1. Load Phase 0 context (tech_stack, modules, conflict_risk)
|
||||
2. Deep topic analysis (entities, challenges, constraints, metrics)
|
||||
3. Generate 2-4 context-aware probing questions
|
||||
4. AskUserQuestion → Store to `session.intent_context`
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "实时协作平台的主要技术挑战？",
|
||||
header: "核心挑战",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "实时数据同步", description: "100+用户同时在线，状态同步复杂度高" },
|
||||
{ label: "可扩展性架构", description: "用户规模增长时的系统扩展能力" },
|
||||
{ label: "冲突解决机制", description: "多用户同时编辑的冲突处理策略" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "MVP阶段最关注的指标？",
|
||||
header: "优先级",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "功能完整性", description: "实现所有核心功能" },
|
||||
{ label: "用户体验", description: "流畅的交互体验和响应速度" },
|
||||
{ label: "系统稳定性", description: "高可用性和数据一致性" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
|
||||
|
||||
### Phase 2: Role Selection
|
||||
|
||||
**Goal**: User selects roles from intelligent recommendations
|
||||
|
||||
**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
|
||||
|
||||
**Steps**:
|
||||
1. Analyze Phase 1 keywords → Recommend count+2 roles with rationale
|
||||
2. AskUserQuestion (multiSelect=true) → Store to `session.selected_roles`
|
||||
3. If count+2 > 4, split into multiple rounds
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "请选择 3 个角色参与头脑风暴分析",
|
||||
header: "角色选择",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{ label: "system-architect", description: "实时同步架构设计和技术选型" },
|
||||
{ label: "ui-designer", description: "协作界面用户体验和状态展示" },
|
||||
{ label: "product-manager", description: "功能优先级和MVP范围决策" },
|
||||
{ label: "data-architect", description: "数据同步模型和存储方案设计" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
**⚠️ CRITICAL**: User MUST interact. NEVER auto-select without confirmation.
|
||||
|
||||
### Phase 3: Role-Specific Questions
|
||||
|
||||
**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges
|
||||
|
||||
**Algorithm**:
|
||||
1. FOR each selected role:
|
||||
- Map Phase 1 challenges to role domain
|
||||
- Generate 3-4 questions (implementation depth, trade-offs, edge cases)
|
||||
- AskUserQuestion per role → Store to `session.role_decisions[role]`
|
||||
2. Process roles sequentially (one at a time for clarity)
|
||||
3. If role needs > 4 questions, split into multiple rounds
|
||||
|
||||
**Example** (system-architect):
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "100+ 用户实时状态同步方案？",
|
||||
header: "状态同步",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Event Sourcing", description: "完整事件历史，支持回溯，存储成本高" },
|
||||
{ label: "集中式状态管理", description: "实现简单，单点瓶颈风险" },
|
||||
{ label: "CRDT", description: "去中心化，自动合并，学习曲线陡" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "两个用户同时编辑冲突如何解决？",
|
||||
header: "冲突解决",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "自动合并", description: "用户无感知，可能产生意外结果" },
|
||||
{ label: "手动解决", description: "用户控制，增加交互复杂度" },
|
||||
{ label: "版本控制", description: "保留历史，需要分支管理" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
### Phase 4: Conflict Resolution
|
||||
|
||||
**Goal**: Resolve ACTUAL conflicts from Phase 3 answers
|
||||
|
||||
**Algorithm**:
|
||||
1. Analyze Phase 3 answers for conflicts:
|
||||
- Contradictory choices (e.g., "fast iteration" vs "complex Event Sourcing")
|
||||
- Missing integration (e.g., "Optimistic updates" but no conflict handling)
|
||||
- Implicit dependencies (e.g., "Live cursors" but no auth defined)
|
||||
2. Generate clarification questions referencing SPECIFIC Phase 3 choices
|
||||
3. AskUserQuestion (max 4 per call, multi-round) → Store to `session.cross_role_decisions`
|
||||
4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4")
|
||||
|
||||
**Example**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "CRDT 与 UI 回滚期望冲突，如何解决？\n背景：system-architect选择CRDT，ui-designer期望回滚UI",
|
||||
header: "架构冲突",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "采用 CRDT", description: "保持去中心化，调整UI期望" },
|
||||
{ label: "显示合并界面", description: "增加用户交互，展示冲突详情" },
|
||||
{ label: "切换到 OT", description: "支持回滚，增加服务器复杂度" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
### Phase 4.5: Final Clarification
|
||||
|
||||
**Purpose**: Ensure no important points missed before generating specification
|
||||
|
||||
**Steps**:
|
||||
1. Ask initial check:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "在生成最终规范之前，是否有前面未澄清的重点需要补充？",
|
||||
header: "补充确认",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "无需补充", description: "前面的讨论已经足够完整" },
|
||||
{ label: "需要补充", description: "还有重要内容需要澄清" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
2. If "需要补充":
|
||||
- Analyze user's additional points
|
||||
- Generate progressive questions (not role-bound, interconnected)
|
||||
- AskUserQuestion (max 4 per round) → Store to `session.additional_decisions`
|
||||
- Repeat until user confirms completion
|
||||
3. If "无需补充": Proceed to Phase 5
|
||||
|
||||
**Progressive Pattern**: Questions interconnected, each round informs next, continue until resolved.
|
||||
|
||||
### Phase 5: Generate Specification
|
||||
|
||||
**Steps**:
|
||||
1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions` + `additional_decisions`
|
||||
2. Transform Q&A to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
|
||||
3. Generate `guidance-specification.md`
|
||||
4. Update `workflow-session.json` (metadata only)
|
||||
5. Validate: No interrogative sentences, all decisions traceable
|
||||
|
||||
---
|
||||
|
||||
## Question Guidelines
|
||||
|
||||
### Core Principle
|
||||
|
||||
**Target**: 开发者（理解技术但需要从用户需求出发）
|
||||
|
||||
**Question Structure**: `[业务场景/需求前提] + [技术关注点]`
|
||||
**Option Structure**: `标签：[技术方案] + 说明：[业务影响] + [技术权衡]`
|
||||
|
||||
### Quality Rules
|
||||
|
||||
**MUST Include**:
|
||||
- ✅ All questions in Chinese (用中文提问)
|
||||
- ✅ 业务场景作为问题前提
|
||||
- ✅ 技术选项的业务影响说明
|
||||
- ✅ 量化指标和约束条件
|
||||
|
||||
**MUST Avoid**:
|
||||
- ❌ 纯技术选型无业务上下文
|
||||
- ❌ 过度抽象的用户体验问题
|
||||
- ❌ 脱离话题的通用架构问题
|
||||
|
||||
### Phase-Specific Requirements
|
||||
|
||||
| Phase | Focus | Key Requirements |
|
||||
|-------|-------|------------------|
|
||||
| 1 | 意图理解 | Reference topic keywords, 用户场景、业务约束、优先级 |
|
||||
| 2 | 角色推荐 | Intelligent analysis (NOT keyword mapping), explain relevance |
|
||||
| 3 | 角色问题 | Reference Phase 1 keywords, concrete options with trade-offs |
|
||||
| 4 | 冲突解决 | Reference SPECIFIC Phase 3 choices, explain impact on both roles |
|
||||
|
||||
---
|
||||
|
||||
## Output & Governance
|
||||
|
||||
### Output Template
|
||||
|
||||
**File**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
|
||||
|
||||
```markdown
|
||||
# [Project] - Confirmed Guidance Specification
|
||||
|
||||
**Metadata**: [timestamp, type, focus, roles]
|
||||
|
||||
## 1. Project Positioning & Goals
|
||||
**CONFIRMED Objectives**: [from topic + Phase 1]
|
||||
**CONFIRMED Success Criteria**: [from Phase 1 answers]
|
||||
|
||||
## 2-N. [Role] Decisions
|
||||
### SELECTED Choices
|
||||
**[Question topic]**: [User's answer]
|
||||
- **Rationale**: [From option description]
|
||||
- **Impact**: [Implications]
|
||||
|
||||
### Cross-Role Considerations
|
||||
**[Conflict resolved]**: [Resolution from Phase 4]
|
||||
- **Affected Roles**: [Roles involved]
|
||||
|
||||
## Cross-Role Integration
|
||||
**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
|
||||
|
||||
## Risks & Constraints
|
||||
**Identified Risks**: [From answers] → Mitigation: [Approach]
|
||||
|
||||
## Next Steps
|
||||
**⚠️ Automatic Continuation** (when called from auto-parallel):
|
||||
- auto-parallel spawns agents for role-specific analysis
|
||||
- Each selected role gets conceptual-planning-agent
|
||||
- Agents read this guidance-specification.md for context
|
||||
|
||||
## Appendix: Decision Tracking
|
||||
| Decision ID | Category | Question | Selected | Phase | Rationale |
|
||||
|-------------|----------|----------|----------|-------|-----------|
|
||||
| D-001 | Intent | [Q] | [A] | 1 | [Why] |
|
||||
| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] |
|
||||
| D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
|
||||
```
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-[topic]/
|
||||
├── workflow-session.json # Metadata ONLY
|
||||
├── .process/
|
||||
│ └── context-package.json # Phase 0 output
|
||||
└── .brainstorming/
|
||||
└── guidance-specification.md # Full guidance content
|
||||
```
|
||||
|
||||
### Session Metadata
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-{topic-slug}",
|
||||
"type": "brainstorming",
|
||||
"topic": "{original user input}",
|
||||
"selected_roles": ["system-architect", "ui-designer", "product-manager"],
|
||||
"phase_completed": "artifacts",
|
||||
"timestamp": "2025-10-24T10:30:00Z",
|
||||
"count_parameter": 3
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ Rule**: Session JSON stores ONLY metadata. All guidance content goes to guidance-specification.md.
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
- ✅ No interrogative sentences (use CONFIRMED/SELECTED)
|
||||
- ✅ Every decision traceable to user answer
|
||||
- ✅ Cross-role conflicts resolved or documented
|
||||
- ✅ Next steps concrete and specific
|
||||
- ✅ No content duplication between .json and .md
|
||||
|
||||
### Update Mechanism
|
||||
|
||||
```
|
||||
IF guidance-specification.md EXISTS:
|
||||
Prompt: "Regenerate completely / Update sections / Cancel"
|
||||
ELSE:
|
||||
Run full Phase 0-5 flow
|
||||
```
|
||||
|
||||
### Governance Rules
|
||||
|
||||
- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections)
|
||||
- Every decision MUST trace to user answer
|
||||
- Conflicts MUST be resolved (not marked "TBD")
|
||||
- Next steps MUST be actionable
|
||||
- Topic preserved as authoritative reference
|
||||
|
||||
**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance.
|
||||
|
||||
---
|
||||
|
||||
## Post-Phase Update
|
||||
|
||||
After Phase 1 completes:
|
||||
- **Output Created**: `guidance-specification.md`, `workflow-session.json`
|
||||
- **Data Parsed**: `selected_roles[]`, `session_id`
|
||||
- **Next Action**: Auto-continue to Phase 2 (parallel role analysis)
|
||||
- **State Update**: Update workflow-session.json with `phase_completed: "artifacts"`
|
||||
@@ -0,0 +1,770 @@
|
||||
## Overview
|
||||
|
||||
**Unified command for generating and updating role-specific analysis** with interactive context gathering, framework alignment, and incremental update support. Replaces 9 individual role commands with single parameterized workflow.
|
||||
|
||||
### Core Function
|
||||
- **Multi-Role Support**: Single command supports all 9 brainstorming roles
|
||||
- **Interactive Context**: Dynamic question generation based on role and framework
|
||||
- **Incremental Updates**: Merge new insights into existing analyses
|
||||
- **Framework Alignment**: Address guidance-specification.md discussion points
|
||||
- **Agent Delegation**: Use conceptual-planning-agent with role-specific templates
|
||||
- **Explicit Lifecycle**: Manage subagent creation, waiting, and cleanup
|
||||
|
||||
### Supported Roles
|
||||
|
||||
| Role ID | Title | Focus Area | Context Questions |
|
||||
|---------|-------|------------|-------------------|
|
||||
| `ux-expert` | UX专家 | User research, information architecture, user journey | 4 |
|
||||
| `ui-designer` | UI设计师 | Visual design, high-fidelity mockups, design systems | 4 |
|
||||
| `system-architect` | 系统架构师 | Technical architecture, scalability, integration patterns | 5 |
|
||||
| `product-manager` | 产品经理 | Product strategy, roadmap, prioritization | 4 |
|
||||
| `product-owner` | 产品负责人 | Backlog management, user stories, acceptance criteria | 4 |
|
||||
| `scrum-master` | 敏捷教练 | Process facilitation, impediment removal, team dynamics | 3 |
|
||||
| `subject-matter-expert` | 领域专家 | Domain knowledge, business rules, compliance | 4 |
|
||||
| `data-architect` | 数据架构师 | Data models, storage strategies, data flow | 5 |
|
||||
| `api-designer` | API设计师 | API contracts, versioning, integration patterns | 4 |
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Generate new analysis with interactive context
|
||||
role-analysis ux-expert
|
||||
|
||||
# Generate with existing framework + context questions
|
||||
role-analysis system-architect --session WFS-xxx --include-questions
|
||||
|
||||
# Update existing analysis (incremental merge)
|
||||
role-analysis ui-designer --session WFS-xxx --update
|
||||
|
||||
# Quick generation (skip interactive context)
|
||||
role-analysis product-manager --session WFS-xxx --skip-questions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
### Phase 1: Detection & Validation
|
||||
|
||||
**Step 1.1: Role Validation**
|
||||
```bash
|
||||
VALIDATE role_name IN [
|
||||
ux-expert, ui-designer, system-architect, product-manager,
|
||||
product-owner, scrum-master, subject-matter-expert,
|
||||
data-architect, api-designer
|
||||
]
|
||||
IF invalid:
|
||||
ERROR: "Unknown role: {role_name}. Use one of: ux-expert, ui-designer, ..."
|
||||
EXIT
|
||||
```
|
||||
|
||||
**Step 1.2: Session Detection**
|
||||
```bash
|
||||
IF --session PROVIDED:
|
||||
session_id = --session
|
||||
brainstorm_dir = .workflow/active/{session_id}/.brainstorming/
|
||||
ELSE:
|
||||
FIND .workflow/active/WFS-*/
|
||||
IF multiple:
|
||||
PROMPT user to select
|
||||
ELSE IF single:
|
||||
USE existing
|
||||
ELSE:
|
||||
ERROR: "No active session. Run Phase 1 (artifacts) first"
|
||||
EXIT
|
||||
|
||||
VALIDATE brainstorm_dir EXISTS
|
||||
```
|
||||
|
||||
**Step 1.3: Framework Detection**
|
||||
```bash
|
||||
framework_file = {brainstorm_dir}/guidance-specification.md
|
||||
IF framework_file EXISTS:
|
||||
framework_mode = true
|
||||
LOAD framework_content
|
||||
ELSE:
|
||||
WARN: "No framework found - will create standalone analysis"
|
||||
framework_mode = false
|
||||
```
|
||||
|
||||
**Step 1.4: Update Mode Detection**
|
||||
```bash
|
||||
existing_analysis = {brainstorm_dir}/{role_name}/analysis*.md
|
||||
IF --update FLAG OR existing_analysis EXISTS:
|
||||
update_mode = true
|
||||
IF --update NOT PROVIDED:
|
||||
ASK: "Analysis exists. Update or regenerate?"
|
||||
OPTIONS: ["Incremental update", "Full regenerate", "Cancel"]
|
||||
ELSE:
|
||||
update_mode = false
|
||||
```
|
||||
|
||||
### Phase 2: Interactive Context Gathering
|
||||
|
||||
**Trigger Conditions**:
|
||||
- Default: Always ask unless `--skip-questions` provided
|
||||
- `--include-questions`: Force context gathering even if analysis exists
|
||||
- `--skip-questions`: Skip all interactive questions
|
||||
|
||||
**Step 2.1: Load Role Configuration**
|
||||
```javascript
|
||||
const roleConfig = {
|
||||
'ux-expert': {
|
||||
title: 'UX专家',
|
||||
focus_area: 'User research, information architecture, user journey',
|
||||
question_categories: ['User Intent', 'Requirements', 'UX'],
|
||||
question_count: 4,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/ux-expert.md'
|
||||
},
|
||||
'ui-designer': {
|
||||
title: 'UI设计师',
|
||||
focus_area: 'Visual design, high-fidelity mockups, design systems',
|
||||
question_categories: ['Requirements', 'UX', 'Feasibility'],
|
||||
question_count: 4,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/ui-designer.md'
|
||||
},
|
||||
'system-architect': {
|
||||
title: '系统架构师',
|
||||
focus_area: 'Technical architecture, scalability, integration patterns',
|
||||
question_categories: ['Scale & Performance', 'Technical Constraints', 'Architecture Complexity', 'Non-Functional Requirements'],
|
||||
question_count: 5,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/system-architect.md'
|
||||
},
|
||||
'product-manager': {
|
||||
title: '产品经理',
|
||||
focus_area: 'Product strategy, roadmap, prioritization',
|
||||
question_categories: ['User Intent', 'Requirements', 'Process'],
|
||||
question_count: 4,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/product-manager.md'
|
||||
},
|
||||
'product-owner': {
|
||||
title: '产品负责人',
|
||||
focus_area: 'Backlog management, user stories, acceptance criteria',
|
||||
question_categories: ['Requirements', 'Decisions', 'Process'],
|
||||
question_count: 4,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/product-owner.md'
|
||||
},
|
||||
'scrum-master': {
|
||||
title: '敏捷教练',
|
||||
focus_area: 'Process facilitation, impediment removal, team dynamics',
|
||||
question_categories: ['Process', 'Risk', 'Decisions'],
|
||||
question_count: 3,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/scrum-master.md'
|
||||
},
|
||||
'subject-matter-expert': {
|
||||
title: '领域专家',
|
||||
focus_area: 'Domain knowledge, business rules, compliance',
|
||||
question_categories: ['Requirements', 'Feasibility', 'Terminology'],
|
||||
question_count: 4,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/subject-matter-expert.md'
|
||||
},
|
||||
'data-architect': {
|
||||
title: '数据架构师',
|
||||
focus_area: 'Data models, storage strategies, data flow',
|
||||
question_categories: ['Architecture', 'Scale & Performance', 'Technical Constraints', 'Feasibility'],
|
||||
question_count: 5,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/data-architect.md'
|
||||
},
|
||||
'api-designer': {
|
||||
title: 'API设计师',
|
||||
focus_area: 'API contracts, versioning, integration patterns',
|
||||
question_categories: ['Architecture', 'Requirements', 'Feasibility', 'Decisions'],
|
||||
question_count: 4,
|
||||
template: '~/.codex/workflows/cli-templates/planning-roles/api-designer.md'
|
||||
}
|
||||
};
|
||||
|
||||
config = roleConfig[role_name];
|
||||
```
|
||||
|
||||
**Step 2.2: Generate Role-Specific Questions**
|
||||
|
||||
**9-Category Taxonomy**:
|
||||
|
||||
| Category | Focus | Example Question Pattern |
|
||||
|----------|-------|--------------------------|
|
||||
| User Intent | 用户目标 | "该分析的核心目标是什么？" |
|
||||
| Requirements | 需求细化 | "需求的优先级如何排序？" |
|
||||
| Architecture | 架构决策 | "技术栈的选择考量？" |
|
||||
| UX | 用户体验 | "交互复杂度的取舍？" |
|
||||
| Feasibility | 可行性 | "资源约束下的实现范围？" |
|
||||
| Risk | 风险管理 | "风险容忍度是多少？" |
|
||||
| Process | 流程规范 | "开发迭代的节奏？" |
|
||||
| Decisions | 决策确认 | "冲突的解决方案？" |
|
||||
| Terminology | 术语统一 | "统一使用哪个术语？" |
|
||||
| Scale & Performance | 性能扩展 | "预期的负载和性能要求？" |
|
||||
| Technical Constraints | 技术约束 | "现有技术栈的限制？" |
|
||||
| Architecture Complexity | 架构复杂度 | "架构的复杂度权衡？" |
|
||||
| Non-Functional Requirements | 非功能需求 | "可用性和可维护性要求？" |
|
||||
|
||||
**Question Generation Algorithm**:
|
||||
```javascript
|
||||
async function generateQuestions(role_name, framework_content) {
|
||||
const config = roleConfig[role_name];
|
||||
const questions = [];
|
||||
|
||||
// Parse framework for keywords
|
||||
const keywords = extractKeywords(framework_content);
|
||||
|
||||
// Generate category-specific questions
|
||||
for (const category of config.question_categories) {
|
||||
const question = generateCategoryQuestion(category, keywords, role_name);
|
||||
questions.push(question);
|
||||
}
|
||||
|
||||
return questions.slice(0, config.question_count);
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2.3: Multi-Round Question Execution**
|
||||
|
||||
```javascript
|
||||
const BATCH_SIZE = 4;
|
||||
const user_context = {};
|
||||
|
||||
for (let i = 0; i < questions.length; i += BATCH_SIZE) {
|
||||
const batch = questions.slice(i, i + BATCH_SIZE);
|
||||
const currentRound = Math.floor(i / BATCH_SIZE) + 1;
|
||||
const totalRounds = Math.ceil(questions.length / BATCH_SIZE);
|
||||
|
||||
console.log(`\n[Round ${currentRound}/${totalRounds}] ${config.title} 上下文询问\n`);
|
||||
|
||||
AskUserQuestion({
|
||||
questions: batch.map(q => ({
|
||||
question: q.question,
|
||||
header: q.category.substring(0, 12),
|
||||
multiSelect: false,
|
||||
options: q.options.map(opt => ({
|
||||
label: opt.label,
|
||||
description: opt.description
|
||||
}))
|
||||
}))
|
||||
});
|
||||
|
||||
// Store responses before next round
|
||||
for (const answer of responses) {
|
||||
user_context[answer.question] = {
|
||||
answer: answer.selected,
|
||||
category: answer.category,
|
||||
timestamp: new Date().toISOString()
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// Save context to file
|
||||
Write(
|
||||
`${brainstorm_dir}/${role_name}/${role_name}-context.md`,
|
||||
formatUserContext(user_context)
|
||||
);
|
||||
```
|
||||
|
||||
**Question Quality Rules**:
|
||||
|
||||
**MUST Include**:
|
||||
- ✅ All questions in Chinese (用中文提问)
|
||||
- ✅ 业务场景作为问题前提
|
||||
- ✅ 技术选项的业务影响说明
|
||||
- ✅ 量化指标和约束条件
|
||||
|
||||
**MUST Avoid**:
|
||||
- ❌ 纯技术选型无业务上下文
|
||||
- ❌ 过度抽象的通用问题
|
||||
- ❌ 脱离框架的重复询问
|
||||
|
||||
### Phase 3: Agent Execution
|
||||
|
||||
**Step 3.1: Load Session Metadata**
|
||||
```bash
|
||||
session_metadata = Read(.workflow/active/{session_id}/workflow-session.json)
|
||||
original_topic = session_metadata.topic
|
||||
selected_roles = session_metadata.selected_roles
|
||||
```
|
||||
|
||||
**Step 3.2: Prepare Agent Context**
|
||||
```javascript
|
||||
const agentContext = {
|
||||
role_name: role_name,
|
||||
role_config: roleConfig[role_name],
|
||||
output_location: `${brainstorm_dir}/${role_name}/`,
|
||||
framework_mode: framework_mode,
|
||||
framework_path: framework_mode ? `${brainstorm_dir}/guidance-specification.md` : null,
|
||||
update_mode: update_mode,
|
||||
user_context: user_context,
|
||||
original_topic: original_topic,
|
||||
session_id: session_id
|
||||
};
|
||||
```
|
||||
|
||||
**Step 3.3: Execute Conceptual Planning Agent**
|
||||
|
||||
**Framework-Based Analysis** (when guidance-specification.md exists):
|
||||
```javascript
|
||||
// Spawn conceptual-planning-agent
|
||||
const roleAgentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
[FLOW_CONTROL]
|
||||
|
||||
Execute ${role_name} analysis for existing topic framework
|
||||
|
||||
## Context Loading
|
||||
ASSIGNED_ROLE: ${role_name}
|
||||
OUTPUT_LOCATION: ${agentContext.output_location}
|
||||
ANALYSIS_MODE: ${framework_mode ? "framework_based" : "standalone"}
|
||||
UPDATE_MODE: ${update_mode}
|
||||
|
||||
## Flow Control Steps
|
||||
1. **load_topic_framework**
|
||||
- Action: Load structured topic discussion framework
|
||||
- Command: Read(${agentContext.framework_path})
|
||||
- Output: topic_framework_content
|
||||
|
||||
2. **load_role_template**
|
||||
- Action: Load ${role_name} planning template
|
||||
- Command: Read(${roleConfig[role_name].template})
|
||||
- Output: role_template_guidelines
|
||||
|
||||
3. **load_session_metadata**
|
||||
- Action: Load session metadata and user intent
|
||||
- Command: Read(.workflow/active/${session_id}/workflow-session.json)
|
||||
- Output: session_context
|
||||
|
||||
4. **load_user_context** (if exists)
|
||||
- Action: Load interactive context responses
|
||||
- Command: Read(${brainstorm_dir}/${role_name}/${role_name}-context.md)
|
||||
- Output: user_context_answers
|
||||
|
||||
5. **${update_mode ? 'load_existing_analysis' : 'skip'}**
|
||||
${update_mode ? `
|
||||
- Action: Load existing analysis for incremental update
|
||||
- Command: Read(${brainstorm_dir}/${role_name}/analysis.md)
|
||||
- Output: existing_analysis_content
|
||||
` : ''}
|
||||
|
||||
## Analysis Requirements
|
||||
**Primary Reference**: Original user prompt from workflow-session.json is authoritative
|
||||
**Framework Source**: Address all discussion points in guidance-specification.md from ${role_name} perspective
|
||||
**User Context Integration**: Incorporate interactive Q&A responses into analysis
|
||||
**Role Focus**: ${roleConfig[role_name].focus_area}
|
||||
**Template Integration**: Apply role template guidelines within framework structure
|
||||
|
||||
## Expected Deliverables
|
||||
1. **analysis.md** (main document, optionally with analysis-{slug}.md sub-documents)
|
||||
2. **Framework Reference**: @../guidance-specification.md (if framework_mode)
|
||||
3. **User Context Reference**: @./${role_name}-context.md (if user context exists)
|
||||
4. **User Intent Alignment**: Validate against session_context
|
||||
|
||||
## Update Requirements (if UPDATE_MODE)
|
||||
- **Preserve Structure**: Maintain existing analysis structure
|
||||
- **Add "Clarifications" Section**: Document new user context with timestamp
|
||||
- **Merge Insights**: Integrate new perspectives without removing existing content
|
||||
- **Resolve Conflicts**: If new context contradicts existing analysis, document both and recommend resolution
|
||||
|
||||
## Completion Criteria
|
||||
- Address each discussion point from guidance-specification.md with ${role_name} expertise
|
||||
- Provide actionable recommendations from ${role_name} perspective within analysis files
|
||||
- All output files MUST start with "analysis" prefix (no recommendations.md or other naming)
|
||||
- Reference framework document using @ notation for integration
|
||||
- Update workflow-session.json with completion status
|
||||
`
|
||||
});
|
||||
|
||||
// Wait for agent completion
|
||||
const roleResult = wait({
|
||||
ids: [roleAgentId],
|
||||
timeout_ms: 600000 // 10 minutes
|
||||
});
|
||||
|
||||
// Check result and cleanup
|
||||
if (roleResult.timed_out) {
|
||||
console.warn(`${role_name} analysis timed out`);
|
||||
}
|
||||
|
||||
// Always close agent
|
||||
close_agent({ id: roleAgentId });
|
||||
```
|
||||
|
||||
### Phase 3 (Parallel Mode): Execute Multiple Roles Concurrently
|
||||
|
||||
**When called from auto-parallel orchestrator**, execute all selected roles in parallel:
|
||||
|
||||
```javascript
|
||||
// Step 1: Spawn all role agents in parallel
|
||||
const roleAgents = [];
|
||||
|
||||
selected_roles.forEach((role_name, index) => {
|
||||
const config = roleConfig[role_name];
|
||||
|
||||
// For ui-designer, append style-skill if provided
|
||||
const styleContext = (role_name === 'ui-designer' && style_skill_package)
|
||||
? `\n## Style Reference\n**Style SKILL Package**: .codex/skills/style-${style_skill_package}/\n**Load First**: Read SKILL.md from style package for design tokens`
|
||||
: '';
|
||||
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## Task Objective
|
||||
Execute **${role_name}** (${config.title}) analysis for brainstorming session.
|
||||
|
||||
## Assigned Context
|
||||
- **Role**: ${role_name}
|
||||
- **Role Focus**: ${config.focus_area}
|
||||
- **Session ID**: ${session_id}
|
||||
- **Framework Path**: ${brainstorm_dir}/guidance-specification.md
|
||||
- **Output Location**: ${brainstorm_dir}/${role_name}/
|
||||
- **Role Index**: ${index + 1} of ${selected_roles.length}
|
||||
${styleContext}
|
||||
|
||||
## Analysis Requirements
|
||||
**Primary Reference**: Original user prompt from workflow-session.json is authoritative
|
||||
**Framework Source**: Address all discussion points in guidance-specification.md from ${role_name} perspective
|
||||
**Role Focus**: ${config.focus_area}
|
||||
|
||||
## Expected Deliverables
|
||||
1. **analysis.md** (main document)
|
||||
2. **analysis-{slug}.md** (optional sub-documents, max 5)
|
||||
3. **Framework Reference**: @../guidance-specification.md
|
||||
|
||||
## Completion Criteria
|
||||
- Address each framework discussion point with ${role_name} expertise
|
||||
- Provide actionable recommendations within analysis files
|
||||
- All output files MUST start with "analysis" prefix
|
||||
`
|
||||
});
|
||||
|
||||
roleAgents.push({ agentId, role_name });
|
||||
});
|
||||
|
||||
// Step 2: Batch wait for all agents
|
||||
const agentIds = roleAgents.map(a => a.agentId);
|
||||
const parallelResults = wait({
|
||||
ids: agentIds,
|
||||
timeout_ms: 900000 // 15 minutes for all agents
|
||||
});
|
||||
|
||||
// Step 3: Process results and check completion
|
||||
const completedRoles = [];
|
||||
const failedRoles = [];
|
||||
|
||||
roleAgents.forEach(({ agentId, role_name }) => {
|
||||
if (parallelResults.status[agentId]?.completed) {
|
||||
completedRoles.push(role_name);
|
||||
} else {
|
||||
failedRoles.push(role_name);
|
||||
}
|
||||
});
|
||||
|
||||
if (parallelResults.timed_out) {
|
||||
console.warn('Some role analyses timed out:', failedRoles);
|
||||
}
|
||||
|
||||
// Step 4: Batch cleanup - IMPORTANT: always close all agents
|
||||
roleAgents.forEach(({ agentId }) => {
|
||||
close_agent({ id: agentId });
|
||||
});
|
||||
|
||||
console.log(`Completed: ${completedRoles.length}/${selected_roles.length} roles`);
|
||||
console.log(`Completed roles: ${completedRoles.join(', ')}`);
|
||||
if (failedRoles.length > 0) {
|
||||
console.warn(`Failed roles: ${failedRoles.join(', ')}`);
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Validation & Finalization
|
||||
|
||||
**Step 4.1: Validate Output**
|
||||
```bash
|
||||
VERIFY EXISTS: ${brainstorm_dir}/${role_name}/analysis.md
|
||||
VERIFY CONTAINS: "@../guidance-specification.md" (if framework_mode)
|
||||
IF user_context EXISTS:
|
||||
VERIFY CONTAINS: "@./${role_name}-context.md" OR "## Clarifications" section
|
||||
```
|
||||
|
||||
**Step 4.2: Update Session Metadata**
|
||||
```json
|
||||
{
|
||||
"phases": {
|
||||
"BRAINSTORM": {
|
||||
"${role_name}": {
|
||||
"status": "${update_mode ? 'updated' : 'completed'}",
|
||||
"completed_at": "timestamp",
|
||||
"framework_addressed": true,
|
||||
"context_gathered": user_context ? true : false,
|
||||
"output_location": "${brainstorm_dir}/${role_name}/analysis.md",
|
||||
"update_history": [
|
||||
{
|
||||
"timestamp": "ISO8601",
|
||||
"mode": "${update_mode ? 'incremental' : 'initial'}",
|
||||
"context_questions": question_count
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 4.3: Completion Report**
|
||||
```markdown
|
||||
✅ ${roleConfig[role_name].title} Analysis Complete
|
||||
|
||||
**Output**: ${brainstorm_dir}/${role_name}/analysis.md
|
||||
**Mode**: ${update_mode ? 'Incremental Update' : 'New Generation'}
|
||||
**Framework**: ${framework_mode ? '✓ Aligned' : '✗ Standalone'}
|
||||
**Context Questions**: ${question_count} answered
|
||||
|
||||
${update_mode ? '
|
||||
**Changes**:
|
||||
- Added "Clarifications" section with new user context
|
||||
- Merged new insights into existing sections
|
||||
- Resolved conflicts with framework alignment
|
||||
' : ''}
|
||||
|
||||
**Next Steps**:
|
||||
${selected_roles.length > 1 ? `
|
||||
- Continue with other roles: ${selected_roles.filter(r => r !== role_name).join(', ')}
|
||||
- Run synthesis: Phase 3 (synthesis integration)
|
||||
` : `
|
||||
- Clarify insights: Phase 3 (synthesis integration)
|
||||
- Generate plan: workflow:plan --session ${session_id}
|
||||
`}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session}/.brainstorming/
|
||||
├── guidance-specification.md # Framework (if exists)
|
||||
└── {role-name}/
|
||||
├── {role-name}-context.md # Interactive Q&A responses
|
||||
├── analysis.md # Main analysis (REQUIRED)
|
||||
└── analysis-{slug}.md # Section documents (optional, max 5)
|
||||
```
|
||||
|
||||
### Analysis Document Structure (New Generation)
|
||||
|
||||
```markdown
|
||||
# ${roleConfig[role_name].title} Analysis: [Topic from Framework]
|
||||
|
||||
## Framework Reference
|
||||
**Topic Framework**: @../guidance-specification.md
|
||||
**Role Focus**: ${roleConfig[role_name].focus_area}
|
||||
**User Context**: @./${role_name}-context.md
|
||||
|
||||
## User Context Summary
|
||||
**Context Gathered**: ${question_count} questions answered
|
||||
**Categories**: ${question_categories.join(', ')}
|
||||
|
||||
${user_context ? formatContextSummary(user_context) : ''}
|
||||
|
||||
## Discussion Points Analysis
|
||||
[Address each point from guidance-specification.md with ${role_name} expertise]
|
||||
|
||||
### Core Requirements (from framework)
|
||||
[Role-specific perspective on requirements]
|
||||
|
||||
### Technical Considerations (from framework)
|
||||
[Role-specific technical analysis]
|
||||
|
||||
### User Experience Factors (from framework)
|
||||
[Role-specific UX considerations]
|
||||
|
||||
### Implementation Challenges (from framework)
|
||||
[Role-specific challenges and solutions]
|
||||
|
||||
### Success Metrics (from framework)
|
||||
[Role-specific metrics and KPIs]
|
||||
|
||||
## ${roleConfig[role_name].title} Specific Recommendations
|
||||
[Role-specific actionable strategies]
|
||||
|
||||
---
|
||||
*Generated by ${role_name} analysis addressing structured framework*
|
||||
*Context gathered: ${new Date().toISOString()}*
|
||||
```
|
||||
|
||||
### Analysis Document Structure (Incremental Update)
|
||||
|
||||
```markdown
|
||||
# ${roleConfig[role_name].title} Analysis: [Topic]
|
||||
|
||||
## Framework Reference
|
||||
[Existing content preserved]
|
||||
|
||||
## Clarifications
|
||||
### Session ${new Date().toISOString().split('T')[0]}
|
||||
${Object.entries(user_context).map(([q, a]) => `
|
||||
- **Q**: ${q} (Category: ${a.category})
|
||||
**A**: ${a.answer}
|
||||
`).join('\n')}
|
||||
|
||||
## User Context Summary
|
||||
[Updated with new context]
|
||||
|
||||
## Discussion Points Analysis
|
||||
[Existing content enhanced with new insights]
|
||||
|
||||
[Rest of sections updated based on clarifications]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Phases
|
||||
|
||||
### Called By
|
||||
- Auto-parallel orchestrator (Phase 2 - parallel role execution)
|
||||
- Manual invocation for single-role analysis
|
||||
|
||||
### Spawns
|
||||
- `conceptual-planning-agent` (via spawn_agent → wait → close_agent)
|
||||
|
||||
### Coordinates With
|
||||
- Phase 1 (artifacts) - creates framework for role analysis
|
||||
- Phase 3 (synthesis) - reads role analyses for integration
|
||||
|
||||
---
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Required Analysis Elements
|
||||
- [ ] Framework discussion points addressed (if framework_mode)
|
||||
- [ ] User context integrated (if context gathered)
|
||||
- [ ] Role template guidelines applied
|
||||
- [ ] Output files follow naming convention (analysis*.md only)
|
||||
- [ ] Framework reference using @ notation
|
||||
- [ ] Session metadata updated
|
||||
|
||||
### Context Quality
|
||||
- [ ] Questions in Chinese with business context
|
||||
- [ ] Options include technical trade-offs
|
||||
- [ ] Categories aligned with role focus
|
||||
- [ ] No generic questions unrelated to framework
|
||||
|
||||
### Update Quality (if update_mode)
|
||||
- [ ] "Clarifications" section added with timestamp
|
||||
- [ ] New insights merged without content loss
|
||||
- [ ] Conflicts documented and resolved
|
||||
- [ ] Framework alignment maintained
|
||||
|
||||
### Agent Lifecycle Quality
|
||||
- [ ] All spawn_agent have corresponding close_agent
|
||||
- [ ] All wait calls have reasonable timeout
|
||||
- [ ] Parallel agents use batch wait
|
||||
- [ ] Error paths include agent cleanup
|
||||
|
||||
---
|
||||
|
||||
## Command Parameters
|
||||
|
||||
### Required Parameters
|
||||
- `[role-name]`: Role identifier (ux-expert, ui-designer, system-architect, etc.)
|
||||
|
||||
### Optional Parameters
|
||||
- `--session [session-id]`: Specify brainstorming session (auto-detect if omitted)
|
||||
- `--update`: Force incremental update mode (auto-detect if analysis exists)
|
||||
- `--include-questions`: Force context gathering even if analysis exists
|
||||
- `--skip-questions`: Skip all interactive context gathering
|
||||
- `--style-skill [package]`: For ui-designer only, load style SKILL package
|
||||
|
||||
### Parameter Combinations
|
||||
|
||||
| Scenario | Command | Behavior |
|
||||
|----------|---------|----------|
|
||||
| New analysis | `role-analysis ux-expert` | Generate + ask context questions |
|
||||
| Quick generation | `role-analysis ux-expert --skip-questions` | Generate without context |
|
||||
| Update existing | `role-analysis ux-expert --update` | Ask clarifications + merge |
|
||||
| Force questions | `role-analysis ux-expert --include-questions` | Ask even if exists |
|
||||
| Specific session | `role-analysis ux-expert --session WFS-xxx` | Target specific session |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Invalid Role Name
|
||||
```
|
||||
ERROR: Unknown role: "ui-expert"
|
||||
Valid roles: ux-expert, ui-designer, system-architect, product-manager,
|
||||
product-owner, scrum-master, subject-matter-expert,
|
||||
data-architect, api-designer
|
||||
```
|
||||
|
||||
### No Active Session
|
||||
```
|
||||
ERROR: No active brainstorming session found
|
||||
Run: Phase 1 (artifacts) to create session
|
||||
```
|
||||
|
||||
### Missing Framework (with warning)
|
||||
```
|
||||
WARN: No guidance-specification.md found
|
||||
Generating standalone analysis without framework alignment
|
||||
Recommend: Run Phase 1 (artifacts) first for better results
|
||||
```
|
||||
|
||||
### Agent Execution Failure
|
||||
```
|
||||
ERROR: Conceptual planning agent failed
|
||||
Check: ${brainstorm_dir}/${role_name}/error.log
|
||||
Action: Retry with --skip-questions or check framework validity
|
||||
```
|
||||
|
||||
### Agent Lifecycle Errors
|
||||
```javascript
|
||||
// Always ensure cleanup in error paths
|
||||
try {
|
||||
const agentId = spawn_agent({ message: "..." });
|
||||
const result = wait({ ids: [agentId], timeout_ms: 600000 });
|
||||
// ... process result ...
|
||||
close_agent({ id: agentId });
|
||||
} catch (error) {
|
||||
// Ensure cleanup even on error
|
||||
if (agentId) close_agent({ id: agentId });
|
||||
throw error;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reference Information
|
||||
|
||||
### Role Template Locations
|
||||
- Templates: `~/.codex/workflows/cli-templates/planning-roles/`
|
||||
- Format: `{role-name}.md` (e.g., `ux-expert.md`, `system-architect.md`)
|
||||
|
||||
### Context Package
|
||||
- Location: `.workflow/active/WFS-{session}/.process/context-package.json`
|
||||
- Used by: `context-search-agent` (Phase 0 of artifacts)
|
||||
- Contains: Project context, tech stack, conflict risks
|
||||
|
||||
---
|
||||
|
||||
## Post-Phase Update
|
||||
|
||||
After Phase 2 completes:
|
||||
- **Output Created**: `[role]/analysis*.md` for each selected role
|
||||
- **Parallel Execution**: All N roles executed concurrently via spawn_agent + batch wait
|
||||
- **Agent Cleanup**: All agents closed after wait completes
|
||||
- **Next Action**: Auto-continue to Phase 3 (synthesis integration)
|
||||
- **State Update**: Update workflow-session.json with role completion status
|
||||
@@ -0,0 +1,476 @@
|
||||
## Overview
|
||||
|
||||
Six-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
|
||||
|
||||
**Phase 1-2**: Session detection → File discovery → Path preparation
|
||||
**Phase 3A**: Cross-role analysis agent → Generate recommendations
|
||||
**Phase 4**: User selects enhancements → User answers clarifications (via AskUserQuestion)
|
||||
**Phase 5**: Parallel update agents (one per role)
|
||||
**Phase 6**: Context package update → Metadata update → Completion report
|
||||
|
||||
All user interactions use AskUserQuestion tool (max 4 questions per call, multi-round).
|
||||
|
||||
**Document Flow**:
|
||||
- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata
|
||||
- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Phase Summary
|
||||
|
||||
| Phase | Goal | Executor | Output |
|
||||
|-------|------|----------|--------|
|
||||
| 1 | Session detection | Main flow | session_id, brainstorm_dir |
|
||||
| 2 | File discovery | Main flow | role_analysis_paths |
|
||||
| 3A | Cross-role analysis | spawn_agent | enhancement_recommendations |
|
||||
| 4 | User interaction | Main flow + AskUserQuestion | update_plan |
|
||||
| 5 | Document updates | spawn_agent[] (parallel) | Updated analysis*.md |
|
||||
| 6 | Finalization | Main flow | context-package.json, report |
|
||||
|
||||
### AskUserQuestion Pattern
|
||||
|
||||
```javascript
|
||||
// Enhancement selection (multi-select)
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "请选择要应用的改进建议",
|
||||
header: "改进选择",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{ label: "EP-001: API Contract", description: "添加详细的请求/响应 schema 定义" },
|
||||
{ label: "EP-002: User Intent", description: "明确用户需求优先级和验收标准" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
// Clarification questions (single-select, multi-round)
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "MVP 阶段的核心目标是什么？",
|
||||
header: "用户意图",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "快速验证", description: "最小功能集，快速上线获取反馈" },
|
||||
{ label: "技术壁垒", description: "完善架构，为长期发展打基础" },
|
||||
{ label: "功能完整", description: "覆盖所有规划功能，延迟上线" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Phases
|
||||
|
||||
### Phase 1: Discovery & Validation
|
||||
|
||||
1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*`
|
||||
2. **Validate Files**:
|
||||
- `guidance-specification.md` (optional, warn if missing)
|
||||
- `*/analysis*.md` (required, error if empty)
|
||||
3. **Load User Intent**: Extract from `workflow-session.json`
|
||||
|
||||
### Phase 2: Role Discovery & Path Preparation
|
||||
|
||||
**Main flow prepares file paths for Agent**:
|
||||
|
||||
1. **Discover Analysis Files**:
|
||||
- Glob: `.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md`
|
||||
- Supports: analysis.md + analysis-{slug}.md (max 5)
|
||||
|
||||
2. **Extract Role Information**:
|
||||
- `role_analysis_paths`: Relative paths
|
||||
- `participating_roles`: Role names from directories
|
||||
|
||||
3. **Pass to Agent**: session_id, brainstorm_dir, role_analysis_paths, participating_roles
|
||||
|
||||
### Phase 3A: Analysis & Enhancement Agent
|
||||
|
||||
**Agent executes cross-role analysis**:
|
||||
|
||||
```javascript
|
||||
// Spawn analysis agent
|
||||
const analysisAgentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## Agent Mission
|
||||
Analyze role documents, identify conflicts/gaps, generate enhancement recommendations
|
||||
|
||||
## Input
|
||||
- brainstorm_dir: ${brainstorm_dir}
|
||||
- role_analysis_paths: ${role_analysis_paths}
|
||||
- participating_roles: ${participating_roles}
|
||||
|
||||
## Flow Control Steps
|
||||
1. load_session_metadata → Read workflow-session.json
|
||||
2. load_role_analyses → Read all analysis files
|
||||
3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities
|
||||
4. generate_recommendations → Format as EP-001, EP-002, ...
|
||||
|
||||
## Output Format
|
||||
[
|
||||
{
|
||||
"id": "EP-001",
|
||||
"title": "API Contract Specification",
|
||||
"affected_roles": ["system-architect", "api-designer"],
|
||||
"category": "Architecture",
|
||||
"current_state": "High-level API descriptions",
|
||||
"enhancement": "Add detailed contract definitions",
|
||||
"rationale": "Enables precise implementation",
|
||||
"priority": "High"
|
||||
}
|
||||
]
|
||||
`
|
||||
});
|
||||
|
||||
// Wait for analysis completion
|
||||
const analysisResult = wait({
|
||||
ids: [analysisAgentId],
|
||||
timeout_ms: 600000 // 10 minutes
|
||||
});
|
||||
|
||||
// Parse enhancement recommendations
|
||||
const recommendations = JSON.parse(analysisResult.status[analysisAgentId]?.completed || '[]');
|
||||
|
||||
// Clean up agent
|
||||
close_agent({ id: analysisAgentId });
|
||||
```
|
||||
|
||||
### Phase 4: User Interaction
|
||||
|
||||
**All interactions via AskUserQuestion (Chinese questions)**
|
||||
|
||||
#### Step 1: Enhancement Selection
|
||||
|
||||
```javascript
|
||||
// If enhancements > 4, split into multiple rounds
|
||||
const enhancements = recommendations; // from Phase 3A
|
||||
const BATCH_SIZE = 4;
|
||||
const selectedEnhancements = [];
|
||||
|
||||
for (let i = 0; i < enhancements.length; i += BATCH_SIZE) {
|
||||
const batch = enhancements.slice(i, i + BATCH_SIZE);
|
||||
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `请选择要应用的改进建议 (第${Math.floor(i/BATCH_SIZE)+1}轮)`,
|
||||
header: "改进选择",
|
||||
multiSelect: true,
|
||||
options: batch.map(ep => ({
|
||||
label: `${ep.id}: ${ep.title}`,
|
||||
description: `影响: ${ep.affected_roles.join(', ')} | ${ep.enhancement}`
|
||||
}))
|
||||
}]
|
||||
})
|
||||
|
||||
// Store selections before next round
|
||||
selectedEnhancements.push(...user_selections);
|
||||
}
|
||||
|
||||
// User can also skip: provide "跳过" option
|
||||
```
|
||||
|
||||
#### Step 2: Clarification Questions
|
||||
|
||||
```javascript
|
||||
// Generate questions based on 9-category taxonomy scan
|
||||
// Categories: User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology
|
||||
|
||||
const clarifications = [...]; // from analysis
|
||||
const BATCH_SIZE = 4;
|
||||
const userAnswers = {};
|
||||
|
||||
for (let i = 0; i < clarifications.length; i += BATCH_SIZE) {
|
||||
const batch = clarifications.slice(i, i + BATCH_SIZE);
|
||||
const currentRound = Math.floor(i / BATCH_SIZE) + 1;
|
||||
const totalRounds = Math.ceil(clarifications.length / BATCH_SIZE);
|
||||
|
||||
AskUserQuestion({
|
||||
questions: batch.map(q => ({
|
||||
question: q.question,
|
||||
header: q.category.substring(0, 12),
|
||||
multiSelect: false,
|
||||
options: q.options.map(opt => ({
|
||||
label: opt.label,
|
||||
description: opt.description
|
||||
}))
|
||||
}))
|
||||
})
|
||||
|
||||
// Store answers before next round
|
||||
batch.forEach((q, idx) => {
|
||||
userAnswers[q.id] = {
|
||||
question: q.question,
|
||||
answer: responses[idx],
|
||||
category: q.category
|
||||
};
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Question Guidelines
|
||||
|
||||
**Target**: 开发者（理解技术但需要从用户需求出发）
|
||||
|
||||
**Question Structure**: `[跨角色分析发现] + [需要澄清的决策点]`
|
||||
**Option Structure**: `标签：[具体方案] + 说明：[业务影响] + [技术权衡]`
|
||||
|
||||
**9-Category Taxonomy**:
|
||||
|
||||
| Category | Focus | Example Question Pattern |
|
||||
|----------|-------|--------------------------|
|
||||
| User Intent | 用户目标 | "MVP阶段核心目标？" + 验证/壁垒/完整性 |
|
||||
| Requirements | 需求细化 | "功能优先级如何排序？" + 核心/增强/可选 |
|
||||
| Architecture | 架构决策 | "技术栈选择考量？" + 熟悉度/先进性/成熟度 |
|
||||
| UX | 用户体验 | "交互复杂度取舍？" + 简洁/丰富/渐进 |
|
||||
| Feasibility | 可行性 | "资源约束下的范围？" + 最小/标准/完整 |
|
||||
| Risk | 风险管理 | "风险容忍度？" + 保守/平衡/激进 |
|
||||
| Process | 流程规范 | "迭代节奏？" + 快速/稳定/灵活 |
|
||||
| Decisions | 决策确认 | "冲突解决方案？" + 方案A/方案B/折中 |
|
||||
| Terminology | 术语统一 | "统一使用哪个术语？" + 术语A/术语B |
|
||||
|
||||
**Quality Rules**:
|
||||
|
||||
**MUST Include**:
|
||||
- ✅ All questions in Chinese (用中文提问)
|
||||
- ✅ 基于跨角色分析的具体发现
|
||||
- ✅ 选项包含业务影响说明
|
||||
- ✅ 解决实际的模糊点或冲突
|
||||
|
||||
**MUST Avoid**:
|
||||
- ❌ 与角色分析无关的通用问题
|
||||
- ❌ 重复已在 artifacts 阶段确认的内容
|
||||
- ❌ 过于细节的实现级问题
|
||||
|
||||
#### Step 3: Build Update Plan
|
||||
|
||||
```javascript
|
||||
update_plan = {
|
||||
"role1": {
|
||||
"enhancements": ["EP-001", "EP-003"],
|
||||
"clarifications": [
|
||||
{"question": "...", "answer": "...", "category": "..."}
|
||||
]
|
||||
},
|
||||
"role2": {
|
||||
"enhancements": ["EP-002"],
|
||||
"clarifications": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 5: Parallel Document Update Agents
|
||||
|
||||
**Execute in parallel** (one agent per role):
|
||||
|
||||
```javascript
|
||||
// Step 1: Spawn all update agents in parallel
|
||||
const updateAgents = [];
|
||||
|
||||
participating_roles.forEach((role, index) => {
|
||||
const role_plan = update_plan[role];
|
||||
|
||||
const agentId = spawn_agent({
|
||||
message: `
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS (Agent Execute)
|
||||
1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
|
||||
2. Read: .workflow/project-tech.json
|
||||
3. Read: .workflow/project-guidelines.json
|
||||
|
||||
---
|
||||
|
||||
## Agent Mission
|
||||
Apply enhancements and clarifications to ${role} analysis
|
||||
|
||||
## Input
|
||||
- role: ${role}
|
||||
- analysis_path: ${brainstorm_dir}/${role}/analysis.md
|
||||
- enhancements: ${JSON.stringify(role_plan.enhancements)}
|
||||
- clarifications: ${JSON.stringify(role_plan.clarifications)}
|
||||
- original_user_intent: ${intent}
|
||||
|
||||
## Flow Control Steps
|
||||
1. load_current_analysis → Read analysis file
|
||||
2. add_clarifications_section → Insert Q&A section
|
||||
3. apply_enhancements → Integrate into relevant sections
|
||||
4. resolve_contradictions → Remove conflicts
|
||||
5. enforce_terminology → Align terminology
|
||||
6. validate_intent → Verify alignment with user intent
|
||||
7. write_updated_file → Save changes
|
||||
|
||||
## Output
|
||||
Updated ${role}/analysis.md
|
||||
`
|
||||
});
|
||||
|
||||
updateAgents.push({ agentId, role });
|
||||
});
|
||||
|
||||
// Step 2: Batch wait for all update agents
|
||||
const updateIds = updateAgents.map(a => a.agentId);
|
||||
const updateResults = wait({
|
||||
ids: updateIds,
|
||||
timeout_ms: 900000 // 15 minutes for all updates
|
||||
});
|
||||
|
||||
// Step 3: Check completion status
|
||||
const updatedRoles = [];
|
||||
const failedUpdates = [];
|
||||
|
||||
updateAgents.forEach(({ agentId, role }) => {
|
||||
if (updateResults.status[agentId]?.completed) {
|
||||
updatedRoles.push(role);
|
||||
} else {
|
||||
failedUpdates.push(role);
|
||||
}
|
||||
});
|
||||
|
||||
if (updateResults.timed_out) {
|
||||
console.warn('Some role updates timed out:', failedUpdates);
|
||||
}
|
||||
|
||||
// Step 4: Batch cleanup - IMPORTANT
|
||||
updateAgents.forEach(({ agentId }) => {
|
||||
close_agent({ id: agentId });
|
||||
});
|
||||
|
||||
console.log(`Updated: ${updatedRoles.length}/${participating_roles.length} roles`);
|
||||
```
|
||||
|
||||
**Agent Characteristics**:
|
||||
- **Isolation**: Each agent updates exactly ONE role (parallel safe)
|
||||
- **Dependencies**: Zero cross-agent dependencies
|
||||
- **Validation**: All updates must align with original_user_intent
|
||||
- **Lifecycle**: Explicit spawn → wait → close for each agent
|
||||
|
||||
### Phase 6: Finalization
|
||||
|
||||
#### Step 1: Update Context Package
|
||||
|
||||
```javascript
|
||||
// Sync updated analyses to context-package.json
|
||||
const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json")
|
||||
|
||||
// Update guidance-specification if exists
|
||||
// Update synthesis-specification if exists
|
||||
// Re-read all role analysis files
|
||||
// Update metadata timestamps
|
||||
|
||||
Write(context_pkg_path, JSON.stringify(context_pkg))
|
||||
```
|
||||
|
||||
#### Step 2: Update Session Metadata
|
||||
|
||||
```json
|
||||
{
|
||||
"phases": {
|
||||
"BRAINSTORM": {
|
||||
"status": "clarification_completed",
|
||||
"clarification_completed": true,
|
||||
"completed_at": "timestamp",
|
||||
"participating_roles": [...],
|
||||
"clarification_results": {
|
||||
"enhancements_applied": ["EP-001", "EP-002"],
|
||||
"questions_asked": 3,
|
||||
"categories_clarified": ["Architecture", "UX"],
|
||||
"roles_updated": ["role1", "role2"]
|
||||
},
|
||||
"quality_metrics": {
|
||||
"user_intent_alignment": "validated",
|
||||
"ambiguity_resolution": "complete",
|
||||
"terminology_consistency": "enforced"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 3: Completion Report
|
||||
|
||||
```markdown
|
||||
## ✅ Clarification Complete
|
||||
|
||||
**Enhancements Applied**: EP-001, EP-002, EP-003
|
||||
**Questions Answered**: 3/5
|
||||
**Roles Updated**: role1, role2, role3
|
||||
|
||||
### Next Steps
|
||||
✅ PROCEED: `workflow:plan --session WFS-{session-id}`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
**Location**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
|
||||
|
||||
**Updated Structure**:
|
||||
```markdown
|
||||
## Clarifications
|
||||
### Session {date}
|
||||
- **Q**: {question} (Category: {category})
|
||||
**A**: {answer}
|
||||
|
||||
## {Existing Sections}
|
||||
{Refined content based on clarifications}
|
||||
```
|
||||
|
||||
**Changes**:
|
||||
- User intent validated/corrected
|
||||
- Requirements more specific/measurable
|
||||
- Architecture with rationale
|
||||
- Ambiguities resolved, placeholders removed
|
||||
- Consistent terminology
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
**Content**:
|
||||
- ✅ All role analyses loaded/analyzed
|
||||
- ✅ Cross-role analysis (consensus, conflicts, gaps)
|
||||
- ✅ 9-category ambiguity scan
|
||||
- ✅ Questions prioritized
|
||||
|
||||
**Analysis**:
|
||||
- ✅ User intent validated
|
||||
- ✅ Cross-role synthesis complete
|
||||
- ✅ Ambiguities resolved
|
||||
- ✅ Terminology consistent
|
||||
|
||||
**Documents**:
|
||||
- ✅ Clarifications section formatted
|
||||
- ✅ Sections reflect answers
|
||||
- ✅ No placeholders (TODO/TBD)
|
||||
- ✅ Valid Markdown
|
||||
|
||||
**Agent Lifecycle**:
|
||||
- ✅ All spawn_agent have corresponding close_agent
|
||||
- ✅ Analysis agent closed before update agents spawn
|
||||
- ✅ All update agents closed after batch wait
|
||||
- ✅ Error paths include agent cleanup
|
||||
|
||||
---
|
||||
|
||||
## Post-Phase Update
|
||||
|
||||
After Phase 3 completes:
|
||||
- **Output Created**: `synthesis-specification.md`, updated role `analysis*.md` files
|
||||
- **Cross-Role Integration**: All role insights synthesized and conflicts resolved
|
||||
- **Agent Cleanup**: All agents (analysis + update) properly closed
|
||||
- **Next Action**: Workflow complete, recommend `workflow:plan --session {session_id}`
|
||||
- **State Update**: Update workflow-session.json with synthesis completion status
|
||||
Reference in New Issue
Block a user