project-documentation-workflow

name	project-documentation-workflow
description	Wave-based comprehensive project documentation generator with dynamic task decomposition. Analyzes project structure and generates appropriate documentation tasks, computes optimal execution waves via topological sort, produces complete documentation suite including architecture, methods, theory, features, usage, and design philosophy.
argument-hint	[-y|--yes] [-c|--concurrency N] [--continue] "project path or description"
allowed-tools	spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input

Auto Mode

When --yes or -y: Auto-confirm task decomposition, skip interactive validation, use defaults.

Project Documentation Workflow (Optimized)

Usage

$project-documentation-workflow "Document the authentication module in src/auth/"
$project-documentation-workflow -c 4 "Generate full docs for the FEM solver project"
$project-documentation-workflow -y "Document entire codebase with architecture and API"
$project-documentation-workflow --continue "doc-auth-module-20260304"

Flags:

• -y, --yes: Skip all confirmations (auto mode)
• -c, --concurrency N: Max concurrent agents within each wave (default: 3)
• --continue: Resume existing session

Output Directory: .workflow/.csv-wave/{session-id}/ Core Output: tasks.csv + results.csv + discoveries.ndjson + wave-summaries/ + docs/ (完整文档集)

---

Overview

优化版：动态任务分解 + 拓扑排序波次计算 + 波次间综合步骤。

┌─────────────────────────────────────────────────────────────────────────┐
│         PROJECT DOCUMENTATION WORKFLOW (Dynamic & Optimized)            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 0: Dynamic Decomposition                                          │
│     ├─ Analyze project structure, complexity, domain                     │
│     ├─ Generate appropriate documentation tasks (动态数量)                │
│     ├─ Compute task dependencies (deps)                                  │
│     ├─ Compute execution waves (topological sort)                        │
│     └─ User validates task breakdown (skip if -y)                        │
│                                                                          │
│  Phase 1: Wave Execution (with Inter-Wave Synthesis)                     │
│     ├─ For each wave (1..N, dynamically computed):                       │
│     │   ├─ Load Wave Summary from previous wave                          │
│     │   ├─ Build wave CSV with prev_context injection                    │
│     │   ├─ spawn_agents_on_csv(wave CSV)                                 │
│     │   ├─ Collect results, merge into master tasks.csv                  │
│     │   ├─ Generate Wave Summary (波次综合)                               │
│     │   └─ Check: any failed? → skip dependents                          │
│     └─ discoveries.ndjson shared across all waves                        │
│                                                                          │
│  Phase 2: Results Aggregation                                            │
│     ├─ Export final results.csv                                          │
│     ├─ Generate context.md with all findings                             │
│     ├─ Generate docs/index.md navigation                                 │
│     └─ Display summary: completed/failed/skipped per wave                │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

CSV Schema

tasks.csv (Master State)

id,title,description,doc_type,target_scope,doc_sections,formula_support,priority,deps,context_from,wave,status,findings,doc_path,key_discoveries,error
"doc-001","项目概述","撰写项目的整体概述","overview","README.md,package.json","purpose,background,positioning,audience","false","high","","","1","pending","","","",""

Columns:

Column	Type	Required	Description
id	string	Yes	Task ID (doc-NNN, auto-generated)
title	string	Yes	Document title
description	string	Yes	Detailed task description
doc_type	enum	Yes	`overview
target_scope	string	Yes	File scope (glob pattern)
doc_sections	string	Yes	Required sections (comma-separated)
formula_support	boolean	No	LaTeX formula support
priority	enum	No	`high
deps	string	No	Dependency task IDs (semicolon-separated)
context_from	string	No	Context source task IDs
wave	integer	Computed	Wave number (computed by topological sort)
status	enum	Output	`pending→completed
findings	string	Output	Key findings summary
doc_path	string	Output	Generated document path
key_discoveries	string	Output	Key discoveries (JSON)
error	string	Output	Error message

---

Implementation

Session Initialization

const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3

const requirement = $ARGUMENTS
  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
  .trim()

const slug = requirement.toLowerCase()
  .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
  .substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = 
 sessionFolder = 

()


(, )

---

Phase 0: Dynamic Task Decomposition

Objective: Analyze the project and dynamically generate appropriate documentation tasks.

Step 1: Project Analysis

Bash({
  command: `ccw cli -p "PURPOSE: Analyze the project and determine appropriate documentation tasks.
TASK:
  1. Scan project structure to identify:
     - Project type (library/application/service/CLI/tool)
     - Primary language(s) and frameworks
     - Project scale (small/medium/large based on file count and complexity)
     - Key modules and their purposes
     - Existing documentation (README, docs/, etc.)
  
  2. Determine documentation needs based on project characteristics:
     - For ALL projects: overview, tech-stack, directory-structure
     - For libraries: api-reference, usage-guide, best-practices
     - For applications: system-architecture, feature-list, usage-guide
     - For numerical/scientific projects: theoretical-foundations (with formula_support=true)
     - For services: api-reference, module-interactions, deployment
     - For complex projects (>50 files): add design-patterns, data-model
     - For simple projects (<10 files): reduce to essential docs only
  
  3. Generate task list with:
     - Unique task IDs (doc-001, doc-002, ...)
     - Appropriate doc_type for each task
     - Target scope (glob patterns) based on actual project structure
     - Required sections for each document type
     - Dependencies (deps) between related tasks
     - Context sources (context_from) for information flow
     - Priority (high for essential docs, medium for useful, low for optional)
  
  4. Task dependency rules:
     - overview tasks: no deps (Wave 1)
     - architecture tasks: depend on overview tasks
     - implementation tasks: depend on architecture tasks
     - feature/api tasks: depend on implementation
     - synthesis tasks: depend on most other tasks

MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON with:
  - project_info: {type, scale, languages, frameworks, modules[]}
  - recommended_waves: number of waves suggested
  - tasks: [{id, title, description, doc_type, target_scope, doc_sections, formula_support, priority, deps[], context_from[]}]
  
CONSTRAINTS: 
  - Small projects: 5-8 tasks max
  - Medium projects: 10-15 tasks
  - Large projects: 15-25 tasks
  - Each doc_type should appear at most once unless justified
  - deps must form a valid DAG (no cycles)

PROJECT TO ANALYZE: ${requirement}" --tool gemini --mode analysis --rule planning-breakdown-task-steps`,
  run_in_background: true
})

Step 2: Topological Sort (Wave Computation)

function computeWaves(tasks) {
  // Build adjacency list
  const graph = new Map()
  const inDegree = new Map()
  const taskMap = new Map()
  
  for (const task of tasks) {
    taskMap.set(task.id, task)
    graph.set(task.id, [])
    inDegree.set(task.id, 0)
  }
  
  // Fill edges based on deps
  for (const task of tasks) {
    const deps = task.deps.filter(d => taskMap.has(d))
    for (const dep of deps) {
      graph.get(dep).push(task.id)
      inDegree.set(task.id, inDegree.get(task.id) + 1)
    }
  }
  
  // Kahn's BFS algorithm
  const waves = []
  let currentWave = []
  
  // Start with tasks that have no dependencies
  for (const [id, degree]  inDegree) {
     (degree === ) currentWave.(id)
  }
  
   (currentWave. > ) {
    waves.([...currentWave])
     nextWave = []
    
     ( id  currentWave) {
       ( neighbor  graph.(id)) {
        inDegree.(neighbor, inDegree.(neighbor) - )
         (inDegree.(neighbor) === ) {
          nextWave.(neighbor)
        }
      }
    }
    
    currentWave = nextWave
  }
  
  
   ( w = ; w < waves.; w++) {
     ( id  waves[w]) {
      taskMap.(id). = w + 
    }
  }
  
  
   assignedCount = tasks.( t. > ).
   (assignedCount < tasks.) {
      ()
  }
  
   {
    : tasks,
    : waves.,
    : waves.( ({ : i + , : w. }))
  }
}

Step 3: User Validation

// Parse decomposition result
const analysisResult = JSON.parse(decompositionOutput)
const { tasks, project_info, waveCount } = analysisResult

// Compute waves
const { tasks: tasksWithWaves, waveCount: computedWaves, waveDistribution } = computeWaves(tasks)

// Display to user (skip if AUTO_YES)
if (!AUTO_YES) {
  console.log(`
╔════════════════════════════════════════════════════════════════╗
║                  PROJECT ANALYSIS RESULT                        ║
╠════════════════════════════════════════════════════════════════╣
║ Type: ${project_info.type.padEnd(20)} Scale: ${project_info.scale.padEnd(10)}        ║
║ Languages: ${project_info.languages.join(', ').substring(0, 40).padEnd(40)} ║
║ Modules: ${project_info.modules.length} identified                                              ║
╠════════════════════════════════════════════════════════════════╣
║ WAVE DISTRIBUTION (${computedWaves} waves, ${tasksWithWaves.length} tasks)               ║
${waveDistribution.map(w => `║   Wave ${w.wave}: ${w.tasks} tasks${' '.repeat(50 - w.tasks.toString().length)}`).join('\n')}
╚════════════════════════════════════════════════════════════════╝
  `)
  
  // Show tasks by wave
  for (let w = 1; w <= computedWaves; w++) {
    const waveTasks = tasksWithWaves.( t. === w)
    .()
     ( t  waveTasks) {
      .()
    }
  }
  
   answer = functions.({
    : [{
      : ,
      : ,
      : ,
      : [
        { : , :  },
        { : , :  }
      ]
    }]
  })
   (answer...[] !== ) {
    .()
    
  }
}


(, (tasksWithWaves))
(, .(project_info, , ))

---

Phase 1: Wave Execution (with Inter-Wave Synthesis)

Key Optimization: Add Wave Summary generation between waves for better context propagation.

const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => t.wave))

for (let wave = 1; wave <= maxWave; wave++) {
  console.log(`\n{'='*60}`)
  console.log(`Wave ${wave}/${maxWave}`)
  console.log('='.repeat(60))
  
  // 1. Load Wave Summary from previous wave
  const waveSummaryPath = `${sessionFolder}/wave-summaries/wave-${wave-1}-summary.md`
  let prevWaveSummary = ''
  if (wave > 1 && fileExists(waveSummaryPath)) {
    prevWaveSummary = Read(waveSummaryPath)
    console.log(`Loaded Wave ${wave-1} Summary (${prevWaveSummary.length} chars)`)
  }
  
  // 2. Filter tasks for this wave
  const waveTasks = tasks.filter( t. === wave && t. === )
  
  
   ( task  waveTasks) {
     depIds = (task. || ).().()
     depStatuses = depIds.( tasks.( t. === id)?.)
     (depStatuses.( s ===  || s === )) {
      task. = 
      task. = 
    }
  }
  
   pendingTasks = waveTasks.( t. === )
   (pendingTasks. === ) {
    .()
    
  }
  
  
   ( task  pendingTasks) {
    
     contextIds = (task. || ).().()
     prevFindings = contextIds.( {
       src = tasks.( t. === id)
       (!src?.)  
       
    }).().()
    
    
     waveContext = prevWaveSummary ? 
       : 
    
    
     discoveries = ()
     relevantDiscoveries = discoveries
      .()
      .( line.())
      .( .(line))
      .( (d, task))
      .(, ) 
      .( )
      .()
    
     discoveryContext = relevantDiscoveries ? 
       : 
    
    task. = prevFindings + waveContext + discoveryContext
  }
  
  
  (, (pendingTasks))
  
  
  ({
    : ,
    : ,
    : (sessionFolder, wave),
    : maxConcurrency,
    : ,
    : ,
    : {
      : ,
      : {
        : { :  },
        : { : , : [, ] },
        : { :  },
        : { :  },
        : { :  },
        : { :  }
      }
    }
  })
  
  
   results = (())
   ( r  results) {
     t = tasks.( t. === r.)
     (t) .(t, r)
  }
  (, (tasks))
  
  
   completedThisWave = results.( r. === )
   (completedThisWave. > ) {
     waveSummary = (wave, completedThisWave, tasks)
    (, waveSummary)
    .()
  }
  
  
  ()
  
  
   completed = results.( r. === ).
   failed = results.( r. === ).
  .()
}

---

Wave Summary Generation (Inter-Wave Synthesis)

function generateWaveSummary(waveNum, completedTasks, allTasks) {
  let summary = `# Wave ${waveNum} Summary\n\n`
  summary += `**Completed Tasks**: ${completedTasks.length}\n\n`
  
  // Group by doc_type
  const byType = {}
  for (const task of completedTasks) {
    const type = task.doc_type || 'unknown'
    if (!byType[type]) byType[type] = []
    byType[type].push(task)
  }
  
  for (const [type, tasks] of Object.entries(byType)) {
    summary += `## ${type.toUpperCase()}\n\n`
    for (const t of tasks) {
      summary += `### ${t.title}\n`
      if (t.findings) {
        summary += `${t.findings.substring(0, 300)}${t.findings.length > 300 ? '...' : ''}\n\n`
      }
      if (t.key_discoveries) {
        try {
          const discoveries = JSON.parse(t.key_discoveries)
          summary += `**Key Points**:\n`
          for ( d  discoveries.(, )) {
            summary += 
          }
          summary += 
        }  (e) {}
      }
    }
  }
  
  
   nextWaveTasks = allTasks.( t. === waveNum + )
   (nextWaveTasks. > ) {
    summary += 
    summary += 
  }
  
   summary
}

 () {
  
   taskScope = task. || 
   taskType = task. || 
  
  
   (taskType ===  && discovery..())  
   (taskType ===  && discovery..())  
   (taskType ===  && discovery..())  
  
  
   (discovery.?.) {
     taskScope.(discovery...()[])
  }
  
   
}

---

Optimized Instruction Template

function buildOptimizedInstruction(sessionFolder, wave) {
  return `## DOCUMENTATION TASK — Wave ${wave}

### ⚠️ MANDATORY FIRST STEPS (DO NOT SKIP)

1. **CHECK DISCOVERIES FIRST** (避免重复工作):
   \`\`\`bash
   # Search for existing discoveries about your topic
   grep -i "{doc_type}" ${sessionFolder}/discoveries.ndjson
   grep -i "{target_keywords}" ${sessionFolder}/discoveries.ndjson
   \`\`\`
   
2. **Read Wave Summary** (高密度上下文):
   - Read: ${sessionFolder}/wave-summaries/wave-${wave-1}-summary.md (if exists)
   
3. **Read prev_context** (provided below)

---

## Your Task

**Task ID**: {id}
**Title**: {title}
**Document Type**: {doc_type}
**Target Scope**: {target_scope}
**Required Sections**: {doc_sections}
**LaTeX Support**: {formula_support}
**Priority**: {priority}

### Task Description
{description}

### Previous Context (USE THIS!)
{prev_context}

---

## Execution Protocol

### Step 1: Discovery Check (MANDATORY)
Before reading any source files:
- Search discoveries.ndjson for existing findings
- Note any pre-discovered components, patterns, algorithms
- Avoid re-documenting what's already found

### Step 2: Scope Analysis
- Read files matching \`{target_scope}\`
- Identify key structures, functions, classes
- Extract relevant code patterns

### Step 3: Context Integration
- Build on findings from prev_context
- Reference Wave Summary insights
- Connect to discoveries from other agents

### Step 4: Document Generation
**Output Path**: Determine based on doc_type:
- \`overview\` → \`docs/01-overview/\`
- \`architecture\` → \`docs/02-architecture/\`
- \`implementation\` → \`docs/03-implementation/\`
- \`feature\` → \`docs/04-features/\`
- \`api\` → \`docs/04-features/\`
- \`usage\` → \`docs/04-features/\`
- \`synthesis\` → \`docs/05-synthesis/\`

**Document Structure**:
\`\`\`markdown
# {Title}

## Overview
[Brief introduction]

## {Required Section 1}
[Content with code examples]

## {Required Section 2}
[Content with diagrams if applicable]

...

## Code Examples
\`\`\`{language}
// file:line references
\`\`\`

## Cross-References
- Related: [Doc](path)
- Depends: [Prereq](path)

## Summary
[Key takeaways]
\`\`\`

### Step 5: Share Discoveries (MANDATORY)
Append to discovery board:
\`\`\`bash
echo '{"ts":"${getUtc8ISOString()}","worker":"{id}","type":"<TYPE>","data":{...}}' >> ${sessionFolder}/discoveries.ndjson
\`\`\`

**Discovery Types**:
- \`component_found\`: {name, type, file, purpose}
- \`pattern_found\`: {pattern_name, location, description}
- \`algorithm_found\`: {name, file, complexity, purpose}
- \`formula_found\`: {name, latex, file, context}
- \`feature_found\`: {name, entry_point, description}
- \`api_found\`: {endpoint, file, parameters, returns}
- \`config_found\`: {name, file, type, default_value}

### Step 6: Report
\`\`\`json
{
  "id": "{id}",
  "status": "completed",
  "findings": "Key discoveries (max 500 chars, structured for context propagation)",
  "doc_path": "docs/XX-category/filename.md",
  "key_discoveries": "[{\"name\":\"...\",\"type\":\"...\",\"description\":\"...\",\"file\":\"...\"}]",
  "error": ""
}
\`\`\`

---

## Quality Requirements

| Requirement | Criteria |
|-------------|----------|
| Section Coverage | ALL sections in doc_sections present |
| Code References | Include file:line for code |
| Discovery Sharing | At least 2 discoveries shared |
| Context Usage | Reference prev_context findings |
| Cross-References | Link to related docs |
`
}

---

Phase 2: Results Aggregation

// 1. Generate docs/index.md
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const completed = tasks.filter(t => t.status === 'completed')

// Group by doc_type for navigation
const byType = {}
for (const t of completed) {
  const type = t.doc_type || 'other'
  if (!byType[type]) byType[type] = []
  byType[type].push(t)
}

let index = `# Project Documentation Index\n\n`
index += `**Generated**: ${getUtc8ISOString().substring(0, 10)}\n`
index += `**Total Documents**: ${completed.length}\n\n`

const typeLabels = {
  overview: '📋 概览',
  architecture: '🏗️ 架构',
  implementation: '⚙️ 实现',
  theory: '📐 理论',
  feature: '✨ 功能',
  api: '🔌 API',
  usage: '📖 使用',
  synthesis: '💡 综合'
}

for (const [type, typeTasks] of Object.(byType)) {
   label = typeLabels[type] || type
  index += 
   ( t  typeTasks) {
    index += 
  }
  index += 
}


index += 
index += 
index += 

(, index)


()


 projectInfo = .(())
 contextMd = 
contextMd += 
contextMd += 

contextMd += 
contextMd += 
contextMd += 
contextMd += 

 statusCounts = {
  : tasks.( t. === ).,
  : tasks.( t. === ).,
  : tasks.( t. === ).
}
contextMd += 
contextMd += 
contextMd += 
contextMd += 
contextMd += 
contextMd += 


 maxWave = .(...tasks.( t.))
contextMd += 
 ( w = ; w <= maxWave; w++) {
   waveTasks = tasks.( t. === w)
  contextMd += 
   ( t  waveTasks) {
     icon = t. ===  ?  : t. ===  ?  : 
    contextMd += 
     (t.) {
      contextMd += 
    }
     (t.) {
      contextMd += 
    }
    contextMd += 
  }
}

(, contextMd)


.()

---

Optimized Output Structure

.workflow/.csv-wave/doc-{date}-{slug}/
├── project-info.json              # 项目分析结果
├── tasks.csv                      # Master CSV (动态生成的任务)
├── results.csv                    # 最终结果
├── discoveries.ndjson             # 发现板
├── context.md                     # 执行报告
│
├── wave-summaries/                # NEW: 波次摘要
│   ├── wave-1-summary.md
│   ├── wave-2-summary.md
│   └── ...
│
└── docs/
    ├── index.md                   # 文档导航
    ├── 01-overview/
    ├── 02-architecture/
    ├── 03-implementation/
    ├── 04-features/
    └── 05-synthesis/

---

Optimization Summary

优化点	原版	优化版
任务数量	固定17任务	动态生成 (5-25基于项目规模)
波次计算	硬编码5波	拓扑排序动态计算
上下文传播	仅 prev_context	prev_context + Wave Summary + Discoveries
发现利用	依赖自觉	强制第一步检查
文档密度	原始 findings	结构化 Wave Summary

---

Core Rules

1. Dynamic First: 任务列表动态生成，不预设
2. Wave Order is Sacred: 波次由拓扑排序决定
3. Discovery Check Mandatory: 必须先检查发现板
4. Wave Summary: 每波次结束生成摘要
5. Context Compound: 上下文累积传播
6. Quality Gates: 每文档必须覆盖所有 doc_sections
7. DO NOT STOP: 持续执行直到所有波次完成