mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
feat: initialize monorepo with package.json for CCW workflow platform
This commit is contained in:
catlog22
@@ -3,66 +3,32 @@ description: Serial collaborative planning with Plan Note - Single-agent sequent
|
||||
argument-hint: "TASK=\"<description>\" [--max-domains=5] [--focus=<domain>]"
|
||||
---
|
||||
|
||||
# Codex Collaborative-Plan-With-File Prompt
|
||||
# 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.
|
||||
|
||||
**Core workflow**: Understand → Template → Sequential 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
|
||||
- **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.
|
||||
|
||||
## Overview
|
||||
|
||||
Serial collaborative planning workflow using **Plan Note** architecture:
|
||||
This workflow enables structured planning through sequential phases:
|
||||
|
||||
1. **Understanding**: Analyze requirements and identify 2-5 sub-domains
|
||||
2. **Sequential Planning**: Process each sub-domain sequentially, generating plan.json + updating plan-note.md
|
||||
3. **Conflict Detection**: Scan plan-note.md for conflicts
|
||||
4. **Completion**: Generate executable plan.md summary
|
||||
1. **Understanding & Template** - Analyze requirements, identify sub-domains, create plan-note.md template
|
||||
2. **Sequential Planning** - Process each sub-domain serially via CLI analysis
|
||||
3. **Conflict Detection** - Scan plan-note.md for conflicts across all domains
|
||||
4. **Completion** - Generate human-readable plan.md summary
|
||||
|
||||
**Note**: Codex does not support parallel agent execution. All domains processed serially.
|
||||
|
||||
## Target Task
|
||||
|
||||
**$TASK**
|
||||
|
||||
**Parameters**:
|
||||
- `--max-domains`: Maximum sub-domains to identify (default: 5)
|
||||
- `--focus`: Focus specific domain (optional)
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Session Detection:
|
||||
├─ Check if planning session exists for task
|
||||
├─ EXISTS + plan-note.md exists → Continue mode
|
||||
└─ NOT_FOUND → New session mode
|
||||
|
||||
Phase 1: Understanding & Template Creation
|
||||
├─ Analyze task description (Glob/Grep/Bash)
|
||||
├─ Identify 2-5 sub-domains
|
||||
├─ Create plan-note.md template
|
||||
└─ Generate requirement-analysis.json
|
||||
|
||||
Phase 2: Sequential Sub-Domain Planning (Serial)
|
||||
├─ For each sub-domain (LOOP):
|
||||
│ ├─ Gemini CLI: Generate detailed plan
|
||||
│ ├─ Extract task summary
|
||||
│ └─ Update plan-note.md section
|
||||
└─ Complete all domains sequentially
|
||||
|
||||
Phase 3: Conflict Detection
|
||||
├─ Parse plan-note.md
|
||||
├─ Extract all tasks from all sections
|
||||
├─ Detect file/dependency/strategy conflicts
|
||||
└─ Update conflict markers in plan-note.md
|
||||
|
||||
Phase 4: Completion
|
||||
├─ Generate conflicts.json
|
||||
├─ Generate plan.md summary
|
||||
└─ Ready for execution
|
||||
|
||||
Output:
|
||||
├─ .workflow/.planning/{slug}-{date}/plan-note.md (executable)
|
||||
├─ .workflow/.planning/{slug}-{date}/requirement-analysis.json (metadata)
|
||||
├─ .workflow/.planning/{slug}-{date}/conflicts.json (conflict report)
|
||||
├─ .workflow/.planning/{slug}-{date}/plan.md (human-readable)
|
||||
└─ .workflow/.planning/{slug}-{date}/agents/{domain}/plan.json (detailed)
|
||||
```
|
||||
The key innovation is the **Plan Note** architecture - a shared collaborative document with pre-allocated sections per sub-domain, eliminating merge conflicts.
|
||||
|
||||
## Output Structure
|
||||
|
||||
@@ -80,469 +46,364 @@ Output:
|
||||
└── plan.md # Phase 4: Human-readable summary
|
||||
```
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
### Phase 1: Understanding & Template
|
||||
|
||||
| Artifact | Purpose |
|
||||
|----------|---------|
|
||||
| `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
|
||||
|
||||
| Artifact | Purpose |
|
||||
|----------|---------|
|
||||
| `agents/{domain}/plan.json` | Detailed implementation plan per domain |
|
||||
| Updated `plan-note.md` | Task pool and evidence sections filled for each domain |
|
||||
|
||||
### Phase 3: Conflict Detection
|
||||
|
||||
| Artifact | Purpose |
|
||||
|----------|---------|
|
||||
| `conflicts.json` | Detected conflicts with types, severity, and resolutions |
|
||||
| Updated `plan-note.md` | Conflict markers section populated |
|
||||
|
||||
### Phase 4: Completion
|
||||
|
||||
| Artifact | Purpose |
|
||||
|----------|---------|
|
||||
| `plan.md` | Human-readable summary with requirements, tasks, and conflicts |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Session Setup
|
||||
### Session Initialization
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
The workflow automatically generates a unique session identifier and directory structure.
|
||||
|
||||
const taskSlug = "$TASK".toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 30)
|
||||
const dateStr = getUtc8ISOString().substring(0, 10)
|
||||
**Session ID Format**: `CPLAN-{slug}-{date}`
|
||||
- `slug`: Lowercase alphanumeric, max 30 chars
|
||||
- `date`: YYYY-MM-DD format (UTC+8)
|
||||
|
||||
const sessionId = `CPLAN-${taskSlug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.planning/${sessionId}`
|
||||
const planNotePath = `${sessionFolder}/plan-note.md`
|
||||
const requirementsPath = `${sessionFolder}/requirement-analysis.json`
|
||||
const conflictsPath = `${sessionFolder}/conflicts.json`
|
||||
const planPath = `${sessionFolder}/plan.md`
|
||||
**Session Directory**: `.workflow/.planning/{sessionId}/`
|
||||
|
||||
// Auto-detect mode
|
||||
const sessionExists = fs.existsSync(sessionFolder)
|
||||
const hasPlanNote = sessionExists && fs.existsSync(planNotePath)
|
||||
const mode = hasPlanNote ? 'continue' : 'new'
|
||||
**Auto-Detection**: If session folder exists with plan-note.md, automatically enters continue mode.
|
||||
|
||||
if (!sessionExists) {
|
||||
bash(`mkdir -p ${sessionFolder}/agents`)
|
||||
}
|
||||
```
|
||||
**Session Variables**:
|
||||
- `sessionId`: Unique session identifier
|
||||
- `sessionFolder`: Base directory for all artifacts
|
||||
- `maxDomains`: Maximum number of sub-domains (default: 5)
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Understanding & Template Creation
|
||||
## Phase 1: Understanding & Template Creation
|
||||
|
||||
#### Step 1.1: Analyze Task Description
|
||||
**Objective**: Analyze task requirements, identify parallelizable sub-domains, and create the plan-note.md template with pre-allocated sections.
|
||||
|
||||
Use built-in tools (no agent):
|
||||
### Step 1.1: Analyze Task Description
|
||||
|
||||
```javascript
|
||||
// 1. Extract task keywords
|
||||
const taskKeywords = extractKeywords("$TASK")
|
||||
Use built-in tools to understand the task scope and identify sub-domains.
|
||||
|
||||
// 2. Identify sub-domains via analysis
|
||||
// Example: "Implement real-time notification system"
|
||||
// → Domains: [Backend API, Frontend UI, Notification Service, Data Storage, Testing]
|
||||
**Analysis Activities**:
|
||||
1. **Extract task keywords** - Identify key terms and concepts from the task description
|
||||
2. **Identify sub-domains** - Split into 2-5 parallelizable focus areas based on task complexity
|
||||
3. **Assess complexity** - Evaluate overall task complexity (Low/Medium/High)
|
||||
4. **Search for references** - Find related documentation, README files, and architecture guides
|
||||
|
||||
const subDomains = identifySubDomains("$TASK", {
|
||||
maxDomains: 5, // --max-domains parameter
|
||||
keywords: taskKeywords
|
||||
})
|
||||
**Sub-Domain Identification Patterns**:
|
||||
|
||||
// 3. Estimate scope
|
||||
const complexity = assessComplexity("$TASK")
|
||||
```
|
||||
| Pattern | Keywords |
|
||||
|---------|----------|
|
||||
| Backend API | 服务, 后端, API, 接口 |
|
||||
| Frontend | 界面, 前端, UI, 视图 |
|
||||
| Database | 数据, 存储, 数据库, 持久化 |
|
||||
| Testing | 测试, 验证, QA |
|
||||
| Infrastructure | 部署, 基础, 运维, 配置 |
|
||||
|
||||
#### Step 1.2: Create plan-note.md Template
|
||||
**Ambiguity Handling**: When the task description is unclear or has multiple interpretations, gather user clarification before proceeding.
|
||||
|
||||
Generate structured template:
|
||||
### Step 1.2: Create plan-note.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
session_id: ${sessionId}
|
||||
original_requirement: |
|
||||
$TASK
|
||||
created_at: ${getUtc8ISOString()}
|
||||
complexity: ${complexity}
|
||||
sub_domains: ${subDomains.map(d => d.name).join(', ')}
|
||||
status: in_progress
|
||||
---
|
||||
Generate a structured template with pre-allocated sections for each sub-domain.
|
||||
|
||||
# 协作规划
|
||||
**plan-note.md Structure**:
|
||||
- **YAML Frontmatter**: session_id, original_requirement, created_at, complexity, sub_domains, status
|
||||
- **Section: 需求理解**: Core objectives, key points, constraints, split strategy
|
||||
- **Section: 任务池 - {Domain N}**: Pre-allocated task section per domain (TASK-{range})
|
||||
- **Section: 依赖关系**: Auto-generated after all domains complete
|
||||
- **Section: 冲突标记**: Populated in Phase 3
|
||||
- **Section: 上下文证据 - {Domain N}**: Evidence section per domain
|
||||
|
||||
**Session ID**: ${sessionId}
|
||||
**任务**: $TASK
|
||||
**复杂度**: ${complexity}
|
||||
**创建时间**: ${getUtc8ISOString()}
|
||||
**TASK ID Range Allocation**: Each domain receives a non-overlapping range of 100 IDs (e.g., Domain 1: TASK-001~100, Domain 2: TASK-101~200).
|
||||
|
||||
### Step 1.3: Generate requirement-analysis.json
|
||||
|
||||
Create the sub-domain configuration document.
|
||||
|
||||
**requirement-analysis.json Structure**:
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `session_id` | Session identifier |
|
||||
| `original_requirement` | Task description |
|
||||
| `complexity` | Low / Medium / High |
|
||||
| `sub_domains[]` | Array of focus areas with descriptions |
|
||||
| `sub_domains[].focus_area` | Domain name |
|
||||
| `sub_domains[].description` | Domain scope description |
|
||||
| `sub_domains[].task_id_range` | Non-overlapping TASK ID range |
|
||||
| `sub_domains[].estimated_effort` | Effort estimate |
|
||||
| `sub_domains[].dependencies` | Cross-domain dependencies |
|
||||
| `total_domains` | Number of domains identified |
|
||||
|
||||
**Success Criteria**:
|
||||
- 2-5 clear sub-domains identified
|
||||
- Each sub-domain can be planned independently
|
||||
- Plan Note template includes all pre-allocated sections
|
||||
- TASK ID ranges have no overlap (100 IDs per domain)
|
||||
- Requirements understanding is comprehensive
|
||||
|
||||
---
|
||||
|
||||
## 需求理解
|
||||
## Phase 2: Sequential Sub-Domain Planning
|
||||
|
||||
### 核心目标
|
||||
${extractObjectives("$TASK")}
|
||||
**Objective**: Process each sub-domain serially via CLI analysis, generating detailed plans and updating plan-note.md.
|
||||
|
||||
### 关键要点
|
||||
${extractKeyPoints("$TASK")}
|
||||
**Execution Model**: Serial processing - plan each domain completely before moving to the next. Later domains can reference earlier planning results.
|
||||
|
||||
### 约束条件
|
||||
${extractConstraints("$TASK")}
|
||||
### Step 2.1: Domain Planning Loop
|
||||
|
||||
### 拆分策略
|
||||
${subDomains.length} 个子领域:
|
||||
${subDomains.map((d, i) => `${i+1}. **${d.name}**: ${d.description}`).join('\n')}
|
||||
For each sub-domain in sequence:
|
||||
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.
|
||||
|
||||
### Step 2.2: CLI Planning for Each Domain
|
||||
|
||||
Execute synchronous CLI analysis to generate a detailed implementation plan.
|
||||
|
||||
**CLI Analysis Scope**:
|
||||
- **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**:
|
||||
- Task breakdown with IDs from the assigned range
|
||||
- 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
|
||||
|
||||
Parse CLI output and update the plan-note.md sections for the current domain.
|
||||
|
||||
**Task Summary Format** (for "任务池" section):
|
||||
- Task header: `### TASK-{ID}: {Title} [{domain}]`
|
||||
- Fields: 状态 (status), 复杂度 (complexity), 依赖 (dependencies), 范围 (scope)
|
||||
- Modification points: File paths with line ranges and change summaries
|
||||
- Conflict risk assessment: Low/Medium/High
|
||||
|
||||
**Evidence Format** (for "上下文证据" section):
|
||||
- Related files with relevance descriptions
|
||||
- Existing patterns identified in codebase
|
||||
- Constraints discovered during analysis
|
||||
|
||||
**Success Criteria**:
|
||||
- All domains processed sequentially
|
||||
- `agents/{domain}/plan.json` created for each domain
|
||||
- `plan-note.md` updated with all task pools and evidence sections
|
||||
- Task summaries follow consistent format
|
||||
|
||||
---
|
||||
|
||||
## 任务池 - ${subDomains[0].name}
|
||||
*(TASK-001 ~ TASK-100)*
|
||||
## Phase 3: Conflict Detection
|
||||
|
||||
*待由规划流程填充*
|
||||
**Objective**: Analyze plan-note.md for conflicts across all domain contributions.
|
||||
|
||||
### Step 3.1: Parse plan-note.md
|
||||
|
||||
Extract all tasks from all "任务池" sections.
|
||||
|
||||
**Extraction Activities**:
|
||||
1. Read plan-note.md content
|
||||
2. Parse YAML frontmatter for session metadata
|
||||
3. Identify all "任务池" sections by heading pattern
|
||||
4. Extract tasks matching pattern: `### TASK-{ID}: {Title} [{domain}]`
|
||||
5. Parse task details: status, complexity, dependencies, modification points, conflict risk
|
||||
6. Consolidate into unified task list
|
||||
|
||||
### Step 3.2: Detect Conflicts
|
||||
|
||||
Scan all tasks for three categories of conflicts.
|
||||
|
||||
**Conflict Types**:
|
||||
|
||||
| Type | Severity | Detection Logic | Resolution |
|
||||
|------|----------|-----------------|------------|
|
||||
| file_conflict | high | Same file:location modified by multiple domains | Coordinate modification order or merge changes |
|
||||
| dependency_cycle | critical | Circular dependencies in task graph (DFS detection) | Remove or reorganize dependencies |
|
||||
| strategy_conflict | medium | Multiple high-risk tasks in same file from different domains | Review approaches and align on single strategy |
|
||||
|
||||
**Detection Activities**:
|
||||
1. **File Conflicts**: Group modification points by file:location, identify locations modified by multiple domains
|
||||
2. **Dependency Cycles**: Build dependency graph from task dependencies, detect cycles using depth-first search
|
||||
3. **Strategy Conflicts**: Group tasks by files they modify, identify files with high-risk tasks from multiple domains
|
||||
|
||||
### Step 3.3: Generate Conflict Artifacts
|
||||
|
||||
Write conflict results and update plan-note.md.
|
||||
|
||||
**conflicts.json Structure**:
|
||||
- `detected_at`: Detection timestamp
|
||||
- `total_conflicts`: Number of conflicts found
|
||||
- `conflicts[]`: Array of conflict objects with type, severity, tasks involved, description, suggested resolution
|
||||
|
||||
**plan-note.md Update**: Locate "冲突标记" section and populate with conflict summary markdown. If no conflicts found, mark as "✅ 无冲突检测到".
|
||||
|
||||
**Success Criteria**:
|
||||
- All tasks extracted and analyzed
|
||||
- `conflicts.json` written with detection results
|
||||
- `plan-note.md` updated with conflict markers
|
||||
- All conflict types checked (file, dependency, strategy)
|
||||
|
||||
---
|
||||
|
||||
## 任务池 - ${subDomains[1].name}
|
||||
*(TASK-101 ~ TASK-200)*
|
||||
## Phase 4: Completion
|
||||
|
||||
*待由规划流程填充*
|
||||
**Objective**: Generate human-readable plan summary and finalize workflow.
|
||||
|
||||
---
|
||||
### Step 4.1: Generate plan.md
|
||||
|
||||
## 依赖关系
|
||||
Create a human-readable summary from plan-note.md content.
|
||||
|
||||
*所有子域规划完成后自动生成*
|
||||
**plan.md Structure**:
|
||||
|
||||
---
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| Header | Session ID, task description, creation time |
|
||||
| 需求 (Requirements) | Copied from plan-note.md "需求理解" section |
|
||||
| 子领域拆分 (Sub-Domains) | Each domain with description, task range, estimated effort |
|
||||
| 任务概览 (Task Overview) | All tasks with complexity, dependencies, and target files |
|
||||
| 冲突报告 (Conflict Report) | Summary of detected conflicts or "无冲突" |
|
||||
| 执行指令 (Execution) | Command to execute the plan |
|
||||
|
||||
## 冲突标记
|
||||
### Step 4.2: Display Completion Summary
|
||||
|
||||
*冲突检测阶段生成*
|
||||
Present session statistics and next steps.
|
||||
|
||||
---
|
||||
**Summary Content**:
|
||||
- Session ID and directory path
|
||||
- Total domains planned
|
||||
- Total tasks generated
|
||||
- Conflict status
|
||||
- Execution command for next step
|
||||
|
||||
## 上下文证据 - ${subDomains[0].name}
|
||||
|
||||
*相关文件、现有模式、约束等*
|
||||
|
||||
---
|
||||
|
||||
## 上下文证据 - ${subDomains[1].name}
|
||||
|
||||
*相关文件、现有模式、约束等*
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
#### Step 1.3: Generate requirement-analysis.json
|
||||
|
||||
```javascript
|
||||
const requirements = {
|
||||
session_id: sessionId,
|
||||
original_requirement: "$TASK",
|
||||
complexity: complexity,
|
||||
sub_domains: subDomains.map((domain, index) => ({
|
||||
focus_area: domain.name,
|
||||
description: domain.description,
|
||||
task_id_range: [index * 100 + 1, (index + 1) * 100],
|
||||
estimated_effort: domain.effort,
|
||||
dependencies: domain.dependencies || []
|
||||
})),
|
||||
total_domains: subDomains.length
|
||||
}
|
||||
|
||||
Write(requirementsPath, JSON.stringify(requirements, null, 2))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Sequential Sub-Domain Planning
|
||||
|
||||
#### Step 2.1: Plan Each Domain Sequentially
|
||||
|
||||
```javascript
|
||||
for (let i = 0; i < subDomains.length; i++) {
|
||||
const domain = subDomains[i]
|
||||
const domainFolder = `${sessionFolder}/agents/${domain.slug}`
|
||||
const domainPlanPath = `${domainFolder}/plan.json`
|
||||
|
||||
console.log(`Planning Domain ${i+1}/${subDomains.length}: ${domain.name}`)
|
||||
|
||||
// Execute Gemini CLI for this domain
|
||||
// ⏳ Wait for completion before proceeding to next domain
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 2.2: CLI Planning for Current Domain
|
||||
|
||||
**CLI Call** (synchronous):
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Generate detailed implementation plan for domain '${domain.name}' in task: $TASK
|
||||
Success: Comprehensive task breakdown with clear dependencies and effort estimates
|
||||
|
||||
DOMAIN CONTEXT:
|
||||
- Focus Area: ${domain.name}
|
||||
- Description: ${domain.description}
|
||||
- Task ID Range: ${domain.task_id_range[0]}-${domain.task_id_range[1]}
|
||||
- Related Domains: ${relatedDomains.join(', ')}
|
||||
|
||||
PRIOR DOMAINS (if any):
|
||||
${completedDomains.map(d => `- ${d.name}: ${completedTaskCount} tasks`).join('\n')}
|
||||
|
||||
TASK:
|
||||
• Analyze ${domain.name} in detail
|
||||
• Identify all necessary tasks (use TASK-ID range: ${domain.task_id_range[0]}-${domain.task_id_range[1]})
|
||||
• Define task dependencies and order
|
||||
• Estimate effort and complexity for each task
|
||||
• Identify file modifications needed
|
||||
• Assess conflict risks with other domains
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT: @**/*
|
||||
|
||||
EXPECTED:
|
||||
JSON output with:
|
||||
- tasks[]: {id, title, description, complexity, depends_on[], files_to_modify[], conflict_risk}
|
||||
- summary: Overview of domain plan
|
||||
- interdependencies: Links to other domains
|
||||
- total_effort: Estimated effort points
|
||||
|
||||
OUTPUT FORMAT: Structured JSON
|
||||
" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
#### Step 2.3: Parse and Update plan-note.md
|
||||
|
||||
After CLI completes for each domain:
|
||||
|
||||
```javascript
|
||||
// Parse CLI output
|
||||
const planJson = parseCLIOutput(cliResult)
|
||||
|
||||
// Save detailed plan
|
||||
Write(domainPlanPath, JSON.stringify(planJson, null, 2))
|
||||
|
||||
// Extract task summary
|
||||
const taskSummary = planJson.tasks.map((t, idx) => `
|
||||
### TASK-${t.id}: ${t.title} [${domain.slug}]
|
||||
|
||||
**状态**: 规划中
|
||||
**复杂度**: ${t.complexity}
|
||||
**依赖**: ${t.depends_on.length > 0 ? t.depends_on.map(d => `TASK-${d}`).join(', ') : 'None'}
|
||||
**范围**: ${t.description}
|
||||
|
||||
**修改点**:
|
||||
${t.files_to_modify.map(f => `- \`${f.path}:${f.line_range}\`: ${f.summary}`).join('\n')}
|
||||
|
||||
**冲突风险**: ${t.conflict_risk}
|
||||
`).join('\n')
|
||||
|
||||
// Update plan-note.md
|
||||
updatePlanNoteSection(
|
||||
planNotePath,
|
||||
`## 任务池 - ${domain.name}`,
|
||||
taskSummary
|
||||
)
|
||||
|
||||
// Extract evidence
|
||||
const evidence = `
|
||||
**相关文件**:
|
||||
${planJson.related_files.map(f => `- ${f.path}: ${f.relevance}`).join('\n')}
|
||||
|
||||
**现有模式**:
|
||||
${planJson.existing_patterns.map(p => `- ${p}`).join('\n')}
|
||||
|
||||
**约束**:
|
||||
${planJson.constraints.map(c => `- ${c}`).join('\n')}
|
||||
`
|
||||
|
||||
updatePlanNoteSection(
|
||||
planNotePath,
|
||||
`## 上下文证据 - ${domain.name}`,
|
||||
evidence
|
||||
)
|
||||
```
|
||||
|
||||
#### Step 2.4: Process All Domains
|
||||
|
||||
```javascript
|
||||
const completedDomains = []
|
||||
|
||||
for (const domain of subDomains) {
|
||||
// Step 2.2: CLI call (synchronous)
|
||||
const cliResult = executeCLI(domain)
|
||||
|
||||
// Step 2.3: Parse and update
|
||||
updatePlanNoteFromCLI(domain, cliResult)
|
||||
|
||||
completedDomains.push(domain)
|
||||
console.log(`✅ Completed: ${domain.name}`)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Conflict Detection
|
||||
|
||||
#### Step 3.1: Parse plan-note.md
|
||||
|
||||
```javascript
|
||||
const planContent = Read(planNotePath)
|
||||
const sections = parsePlanNoteSections(planContent)
|
||||
const allTasks = []
|
||||
|
||||
// Extract tasks from all domains
|
||||
for (const section of sections) {
|
||||
if (section.heading.includes('任务池')) {
|
||||
const tasks = extractTasks(section.content)
|
||||
allTasks.push(...tasks)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Step 3.2: Detect Conflicts
|
||||
|
||||
```javascript
|
||||
const conflicts = []
|
||||
|
||||
// 1. File conflicts
|
||||
const fileMap = new Map()
|
||||
for (const task of allTasks) {
|
||||
for (const file of task.files_to_modify) {
|
||||
const key = `${file.path}:${file.line_range}`
|
||||
if (!fileMap.has(key)) fileMap.set(key, [])
|
||||
fileMap.get(key).push(task)
|
||||
}
|
||||
}
|
||||
|
||||
for (const [location, tasks] of fileMap.entries()) {
|
||||
if (tasks.length > 1) {
|
||||
const agents = new Set(tasks.map(t => t.domain))
|
||||
if (agents.size > 1) {
|
||||
conflicts.push({
|
||||
type: 'file_conflict',
|
||||
severity: 'high',
|
||||
location: location,
|
||||
tasks_involved: tasks.map(t => t.id),
|
||||
agents_involved: Array.from(agents),
|
||||
description: `Multiple domains modifying: ${location}`,
|
||||
suggested_resolution: 'Coordinate modification order'
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 2. Dependency cycles
|
||||
const depGraph = buildDependencyGraph(allTasks)
|
||||
const cycles = detectCycles(depGraph)
|
||||
for (const cycle of cycles) {
|
||||
conflicts.push({
|
||||
type: 'dependency_cycle',
|
||||
severity: 'critical',
|
||||
tasks_involved: cycle,
|
||||
description: `Circular dependency: ${cycle.join(' → ')}`,
|
||||
suggested_resolution: 'Remove or reorganize dependencies'
|
||||
})
|
||||
}
|
||||
|
||||
// Write conflicts.json
|
||||
Write(conflictsPath, JSON.stringify({
|
||||
detected_at: getUtc8ISOString(),
|
||||
total_conflicts: conflicts.length,
|
||||
conflicts: conflicts
|
||||
}, null, 2))
|
||||
```
|
||||
|
||||
#### Step 3.3: Update plan-note.md
|
||||
|
||||
```javascript
|
||||
const conflictMarkdown = generateConflictMarkdown(conflicts)
|
||||
|
||||
updatePlanNoteSection(
|
||||
planNotePath,
|
||||
'## 冲突标记',
|
||||
conflictMarkdown
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Completion
|
||||
|
||||
#### Step 4.1: Generate plan.md
|
||||
|
||||
```markdown
|
||||
# 实现计划
|
||||
|
||||
**Session**: ${sessionId}
|
||||
**任务**: $TASK
|
||||
**创建**: ${getUtc8ISOString()}
|
||||
|
||||
---
|
||||
|
||||
## 需求
|
||||
|
||||
${copySection(planNotePath, '## 需求理解')}
|
||||
|
||||
---
|
||||
|
||||
## 子领域拆分
|
||||
|
||||
${subDomains.map((domain, i) => `
|
||||
### ${i+1}. ${domain.name}
|
||||
- **描述**: ${domain.description}
|
||||
- **任务范围**: TASK-${domain.task_id_range[0]} ~ TASK-${domain.task_id_range[1]}
|
||||
- **预估工作量**: ${domain.effort}
|
||||
`).join('\n')}
|
||||
|
||||
---
|
||||
|
||||
## 任务概览
|
||||
|
||||
${allTasks.map(t => `
|
||||
### ${t.id}: ${t.title}
|
||||
- **复杂度**: ${t.complexity}
|
||||
- **依赖**: ${t.depends_on.length > 0 ? t.depends_on.join(', ') : 'None'}
|
||||
- **文件**: ${t.files_to_modify.map(f => f.path).join(', ')}
|
||||
`).join('\n')}
|
||||
|
||||
---
|
||||
|
||||
## 冲突报告
|
||||
|
||||
${conflicts.length > 0
|
||||
? `检测到 ${conflicts.length} 个冲突:\n${copySection(planNotePath, '## 冲突标记')}`
|
||||
: '✅ 无冲突检测到'}
|
||||
|
||||
---
|
||||
|
||||
## 执行指令
|
||||
|
||||
\`\`\`bash
|
||||
/workflow:unified-execute-with-file ${planPath}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
#### Step 4.2: Write Summary
|
||||
|
||||
```javascript
|
||||
Write(planPath, planMarkdown)
|
||||
```
|
||||
**Success Criteria**:
|
||||
- `plan.md` generated with complete summary
|
||||
- All artifacts present in session directory
|
||||
- User informed of completion and next steps
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Sub-Domain Identification
|
||||
|
||||
Common domain patterns:
|
||||
- Backend API: "服务", "后端", "API", "接口"
|
||||
- Frontend: "界面", "前端", "UI", "视图"
|
||||
- Database: "数据", "存储", "数据库", "持久化"
|
||||
- Testing: "测试", "验证", "QA"
|
||||
- Infrastructure: "部署", "基础", "运维", "配置"
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `--max-domains` | 5 | Maximum sub-domains to identify |
|
||||
| `--focus` | None | Focus specific domain (optional) |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
## Error Handling & Recovery
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| CLI timeout | Retry with shorter prompt |
|
||||
| No tasks generated | Review domain description, retry |
|
||||
| Section not found | Recreate section in plan-note.md |
|
||||
| Conflict detection fails | Continue with empty conflicts |
|
||||
| Situation | Action | Recovery |
|
||||
|-----------|--------|----------|
|
||||
| CLI timeout | Retry with shorter, focused prompt | Skip domain or reduce scope |
|
||||
| No tasks generated | Review domain description | Retry with refined description |
|
||||
| Section not found in plan-note | Recreate section defensively | Continue with new section |
|
||||
| Conflict detection fails | Continue with empty conflicts | Note in completion summary |
|
||||
| Session folder conflict | Append timestamp suffix | Create unique folder |
|
||||
|
||||
---
|
||||
|
||||
## Iteration Patterns
|
||||
|
||||
### New Planning Session
|
||||
|
||||
```
|
||||
User initiates: TASK="task description"
|
||||
├─ No session exists → New session mode
|
||||
├─ Analyze task and identify sub-domains
|
||||
├─ Create plan-note.md template
|
||||
├─ Generate requirement-analysis.json
|
||||
├─ Process each domain serially:
|
||||
│ ├─ CLI analysis → plan.json
|
||||
│ └─ Update plan-note.md sections
|
||||
├─ Detect conflicts
|
||||
├─ Generate plan.md summary
|
||||
└─ Report completion
|
||||
```
|
||||
|
||||
### Continue Existing Session
|
||||
|
||||
```
|
||||
User resumes: TASK="same task"
|
||||
├─ Session exists → Continue mode
|
||||
├─ Load plan-note.md and requirement-analysis.json
|
||||
├─ Resume from first incomplete domain
|
||||
└─ Continue sequential processing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear Task Description**: Detailed requirements → better sub-domains
|
||||
2. **Review plan-note.md**: Check before moving to next phase
|
||||
3. **Resolve Conflicts**: Address before execution
|
||||
4. **Inspect Details**: Review agents/{domain}/plan.json for specifics
|
||||
### Before Starting Planning
|
||||
|
||||
1. **Clear Task Description**: Detailed requirements lead to better sub-domain splitting
|
||||
2. **Reference Documentation**: Ensure latest README and design docs are identified
|
||||
3. **Clarify Ambiguities**: Resolve unclear requirements before committing to sub-domains
|
||||
|
||||
### During Planning
|
||||
|
||||
1. **Review Plan Note**: Check plan-note.md between phases to verify progress
|
||||
2. **Verify Domains**: Ensure sub-domains are truly independent and parallelizable
|
||||
3. **Check Dependencies**: Cross-domain dependencies should be documented explicitly
|
||||
4. **Inspect Details**: Review `agents/{domain}/plan.json` for specifics when needed
|
||||
|
||||
### After Planning
|
||||
|
||||
1. **Resolve Conflicts**: Address high/critical conflicts before execution
|
||||
2. **Review Summary**: Check plan.md for completeness and accuracy
|
||||
3. **Validate Tasks**: Ensure all tasks have clear scope and modification targets
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Workflow
|
||||
|
||||
### Use collaborative-plan-with-file when:
|
||||
- Complex tasks requiring multi-domain decomposition
|
||||
- Need structured planning with conflict detection
|
||||
- Tasks spanning multiple modules or systems
|
||||
- Want documented planning process for team review
|
||||
- Preparing for multi-step execution workflows
|
||||
|
||||
### Use direct execution when:
|
||||
- Simple, single-domain tasks
|
||||
- Clear implementation path without ambiguity
|
||||
- Quick follow-up to existing planning session
|
||||
|
||||
### Consider alternatives when:
|
||||
- Exploring ideas without clear direction → use `workflow:brainstorm-with-file`
|
||||
- Analyzing existing code/system → use `workflow:analyze-with-file`
|
||||
- Lightweight planning for simple features → use `workflow:lite-plan`
|
||||
- Ready to execute existing plan → use `workflow:unified-execute-with-file`
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user