project-documentation-workflow

## Auto Mode When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults. # Project Documentation Workflow (Optimized) ## Usage ```bash $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) ```csv 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|architecture|theory|implementation|feature|api|usage|synthesis` | | `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|medium|low` (for task ordering) | | `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|failed|skipped` | | `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 ```javascript 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 = `doc-${dateStr}-${slug}` const sessionFolder = `.workflow/.csv-wave/${sessionId}` Bash(`mkdir -p ${sessionFolder}/docs ${sessionFolder}/wave-summaries`) // Initialize discoveries.ndjson Write(`${sessionFolder}/discoveries.ndjson`, `# Discovery Board - ${sessionId}\n# Format: NDJSON\n`) ``` --- ### Phase 0: Dynamic Task Decomposition **Objective**: Analyze the project and dynamically generate appropriate documentation tasks. #### Step 1: Project Analysis ```javascript 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) ```javascript 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] of inDegree) { if (degree === 0) currentWave.push(id) } while (currentWave.length > 0) { waves.push([...currentWave]) const nextWave = [] for (const id of currentWave) { for (const neighbor of graph.get(id)) { inDegree.set(neighbor, inDegree.get(neighbor) - 1) if (inDegree.get(neighbor) === 0) { nextWave.push(neighbor) } } } currentWave = nextWave } // Assign wave numbers for (let w = 0; w < waves.length; w++) { for (const id of waves[w]) { taskMap.get(id).wave = w + 1 } } // Check for cycles const assignedCount = tasks.filter(t => t.wave > 0).length if (assignedCount < tasks.length) { throw new Error(`Circular dependency detected! Only ${assignedCount}/${tasks.length} tasks assigned.`) } return { tasks: tasks, waveCount: waves.length, waveDistribution: waves.map((w, i) => ({ wave: i + 1, tasks: w.length })) } } ``` #### Step 3: User Validation ```javascript // 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.filter(t => t.wave === w) console.log(`\nWave ${w}:`) for (const t of waveTasks) { console.log(` ${t.id}: ${t.title} [${t.doc_type}]`) } } const answer = functions.request_user_input({ questions: [{ header: "确认任务", id: "confirm_tasks", question: "Proceed with this task breakdown?", options: [ { label: "Proceed(Recommended)", description: "Start wave execution with this task breakdown" }, { label: "Cancel", description: "Abort and modify tasks manually" } ] }] }) if (answer.answers.confirm_tasks.answers[0] !== "Proceed(Recommended)") { console.log("Aborted. Use --continue to resume with modified tasks.") return } } // Generate tasks.csv Write(`${sessionFolder}/tasks.csv`, toCsv(tasksWithWaves)) Write(`${sessionFolder}/project-info.json`, JSON.stringify(project_info, null, 2)) ``` --- ### Phase 1: Wave Execution (with Inter-Wave Synthesis) **Key Optimization**: Add Wave Summary generation between waves for better context propagation. ```javascript 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 => t.wave === wave && t.status === 'pending')