claude-code-workflow 6.3.10 → 6.3.12

package/.claude/commands/issue/plan.md

@@ -172,19 +172,17 @@ TodoWrite({
 });
 ```
 
-### Phase 2: Unified Explore + Plan (issue-plan-agent)
+### Phase 2: Unified Explore + Plan (issue-plan-agent) - PARALLEL
 
 ```javascript
 Bash(`mkdir -p .workflow/issues/solutions`);
 const pendingSelections = [];  // Collect multi-solution issues for user selection
 
-for (const [batchIndex, batch] of batches.entries()) {
-  updateTodo(`Plan batch ${batchIndex + 1}`, 'in_progress');
-
-  // Build issue list with metadata for agent context
+// Build prompts for all batches
+const agentTasks = batches.map((batch, batchIndex) => {
   const issueList = batch.map(i => `- ${i.id}: ${i.title}${i.tags.length ? ` [${i.tags.join(', ')}]` : ''}`).join('\n');
+  const batchIds = batch.map(i => i.id);
 
-  // Build minimal prompt - agent handles exploration, planning, and binding
   const issuePrompt = `
 ## Plan Issues
 
@@ -202,8 +200,9 @@ ${issueList}
 ### Steps
 1. Fetch: \`ccw issue status <id> --json\`
 2. Load project context (project-tech.json + project-guidelines.json)
-3. Explore (ACE) → Plan solution (respecting guidelines)
-4. Register & bind: \`ccw issue bind <id> --solution <file>\`
+3. **If source=discovery**: Use discovery_context (file, line, snippet, suggested_fix) as planning hints
+4. Explore (ACE) → Plan solution (respecting guidelines)
+5. Register & bind: \`ccw issue bind <id> --solution <file>\`
 
 ### Generate Files
 \`.workflow/issues/solutions/{issue-id}.jsonl\` - Solution with tasks (schema: cat .claude/workflows/cli-templates/schemas/solution-schema.json)
@@ -222,40 +221,57 @@ ${issueList}
 \`\`\`
 `;
 
-  // Launch issue-plan-agent - agent writes solutions directly
-  const batchIds = batch.map(i => i.id);
-  const result = Task(
-    subagent_type="issue-plan-agent",
-    run_in_background=false,
-    description=`Explore & plan ${batch.length} issues: ${batchIds.join(', ')}`,
-    prompt=issuePrompt
-  );
-
-  // Parse summary from agent
-  const summary = JSON.parse(result);
-
-  // Display auto-bound solutions
-  for (const item of summary.bound || []) {
-    console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
+  return { batchIndex, batchIds, issuePrompt, batch };
+});
+
+// Launch agents in parallel (max 10 concurrent)
+const MAX_PARALLEL = 10;
+for (let i = 0; i < agentTasks.length; i += MAX_PARALLEL) {
+  const chunk = agentTasks.slice(i, i + MAX_PARALLEL);
+  const taskIds = [];
+
+  // Launch chunk in parallel
+  for (const { batchIndex, batchIds, issuePrompt, batch } of chunk) {
+    updateTodo(`Plan batch ${batchIndex + 1}`, 'in_progress');
+    const taskId = Task(
+      subagent_type="issue-plan-agent",
+      run_in_background=true,
+      description=`Explore & plan ${batch.length} issues: ${batchIds.join(', ')}`,
+      prompt=issuePrompt
+    );
+    taskIds.push({ taskId, batchIndex });
   }
 
-  // Collect pending selections for Phase 3
-  pendingSelections.push(...(summary.pending_selection || []));
+  console.log(`Launched ${taskIds.length} agents (batch ${i/MAX_PARALLEL + 1}/${Math.ceil(agentTasks.length/MAX_PARALLEL)})...`);
 
-  // Show conflicts
-  if (summary.conflicts?.length > 0) {
-    console.log(`⚠ Conflicts: ${summary.conflicts.map(c => c.file).join(', ')}`);
-  }
+  // Collect results from this chunk
+  for (const { taskId, batchIndex } of taskIds) {
+    const result = TaskOutput(task_id=taskId, block=true);
+    const summary = JSON.parse(result);
 
-  updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
+    for (const item of summary.bound || []) {
+      console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
+    }
+    // Collect and notify pending selections
+    for (const pending of summary.pending_selection || []) {
+      console.log(`⏳ ${pending.issue_id}: ${pending.solutions.length} solutions → awaiting selection`);
+      pendingSelections.push(pending);
+    }
+    if (summary.conflicts?.length > 0) {
+      console.log(`⚠ Conflicts: ${summary.conflicts.map(c => c.file).join(', ')}`);
+    }
+    updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
+  }
 }
 ```
 
-### Phase 3: Multi-Solution Selection
+### Phase 3: Multi-Solution Selection (MANDATORY when pendingSelections > 0)
 
 ```javascript
-// Only handle issues where agent generated multiple solutions
+// MUST trigger user selection when multiple solutions exist
 if (pendingSelections.length > 0) {
+  console.log(`\n## User Selection Required: ${pendingSelections.length} issue(s) have multiple solutions\n`);
+
   const answer = AskUserQuestion({
     questions: pendingSelections.map(({ issue_id, solutions }) => ({
       question: `Select solution for ${issue_id}:`,

package/.claude/commands/issue/queue.md

@@ -199,6 +199,8 @@ Phase 5: Queue Output
 
 ### Phase 1: Solution Loading
 
+**NOTE**: Execute code directly. DO NOT pre-read solution files - Bash cat handles all reading.
+
 ```javascript
 // Load issues.jsonl
 const issuesPath = '.workflow/issues/issues.jsonl';
@@ -258,10 +260,15 @@ console.log(`Loaded ${allSolutions.length} solutions from ${plannedIssues.length
 ### Phase 2-4: Agent-Driven Queue Formation
 
 ```javascript
+// Generate queue-id ONCE here, pass to agent
+const now = new Date();
+const queueId = `QUE-${now.toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+
 // Build minimal prompt - agent orders SOLUTIONS, not tasks
 const agentPrompt = `
 ## Order Solutions
 
+**Queue ID**: ${queueId}
 **Solutions**: ${allSolutions.length} from ${plannedIssues.length} issues
 **Project Root**: ${process.cwd()}
 
@@ -291,11 +298,13 @@ ${JSON.stringify(allSolutions, null, 2)}
   3. More tasks = higher priority (larger impact)
 - **Parallel Safety**: Solutions in same parallel group must have NO file overlaps
 - **Queue Item ID Format**: \`S-N\` (S-1, S-2, S-3, ...)
-- **Queue ID Format**: \`QUE-YYYYMMDD-HHMMSS\` (UTC timestamp)
+- **Queue ID**: Use the provided Queue ID (passed above), do NOT generate new one
+
+### Generate Files (STRICT - only these 2)
+1. \`.workflow/issues/queues/{Queue ID}.json\` - Use Queue ID from above
+2. \`.workflow/issues/queues/index.json\` - Update existing index
 
-### Generate Files
-1. \`.workflow/issues/queues/\${queueId}.json\` - Full queue with solutions array
-2. \`.workflow/issues/queues/index.json\` - Update with new entry
+Write ONLY these 2 files, using the provided Queue ID.
 
 ### Return Summary
 \`\`\`json
@@ -320,10 +329,83 @@ const result = Task(
 const summary = JSON.parse(result);
 ```
 
-### Phase 5: Summary & Status Update
+### Phase 5: Validation & Status Update
 
 ```javascript
-// Agent already generated queue files, use summary
+// ============ VALIDATION: Prevent "next returns empty" issues ============
+
+const queuesDir = '.workflow/issues/queues';
+const indexPath = `${queuesDir}/index.json`;
+const queuePath = `${queuesDir}/${queueId}.json`;
+
+// 1. Validate index.json has active_queue_id
+const indexContent = Bash(`cat "${indexPath}" 2>/dev/null || echo '{}'`);
+const index = JSON.parse(indexContent);
+
+if (index.active_queue_id !== queueId) {
+  console.log(`⚠ Fixing: index.json active_queue_id not set to ${queueId}`);
+  index.active_queue_id = queueId;
+  // Ensure queue entry exists in index
+  if (!index.queues) index.queues = [];
+  const existing = index.queues.find(q => q.id === queueId);
+  if (!existing) {
+    index.queues.unshift({
+      id: queueId,
+      status: 'active',
+      issue_ids: summary.issues_queued,
+      total_solutions: summary.total_solutions,
+      completed_solutions: 0,
+      created_at: new Date().toISOString()
+    });
+  }
+  Bash(`echo '${JSON.stringify(index, null, 2)}' > "${indexPath}"`);
+  console.log(`✓ Fixed: index.json updated with active_queue_id: ${queueId}`);
+}
+
+// 2. Validate queue file exists and has correct structure
+const queueContent = Bash(`cat "${queuePath}" 2>/dev/null || echo '{}'`);
+const queue = JSON.parse(queueContent);
+
+if (!queue.solutions || queue.solutions.length === 0) {
+  console.error(`✗ ERROR: Queue file ${queuePath} has no solutions array`);
+  console.error('  Agent did not generate queue correctly. Aborting.');
+  return;
+}
+
+// 3. Validate all solutions have status: "pending" (not "queued" or other)
+let statusFixed = 0;
+for (const sol of queue.solutions) {
+  if (sol.status !== 'pending' && sol.status !== 'executing' && sol.status !== 'completed') {
+    console.log(`⚠ Fixing: ${sol.item_id} status "${sol.status}" → "pending"`);
+    sol.status = 'pending';
+    statusFixed++;
+  }
+}
+
+// 4. Validate at least one item has no dependencies (DAG entry point)
+const entryPoints = queue.solutions.filter(s =>
+  s.status === 'pending' && (!s.depends_on || s.depends_on.length === 0)
+);
+
+if (entryPoints.length === 0) {
+  console.error(`✗ ERROR: No entry points found (all items have dependencies)`);
+  console.error('  This will cause "ccw issue next" to return empty.');
+  console.error('  Check depends_on fields for circular dependencies.');
+  // Try to fix by clearing first item's dependencies
+  if (queue.solutions.length > 0) {
+    console.log(`⚠ Fixing: Clearing depends_on for first item ${queue.solutions[0].item_id}`);
+    queue.solutions[0].depends_on = [];
+  }
+}
+
+// Write back fixed queue if any changes made
+if (statusFixed > 0 || entryPoints.length === 0) {
+  Bash(`echo '${JSON.stringify(queue, null, 2)}' > "${queuePath}"`);
+  console.log(`✓ Queue file updated with ${statusFixed} status fixes`);
+}
+
+// ============ OUTPUT SUMMARY ============
+
 console.log(`
 ## Queue Formed: ${summary.queue_id}
 
@@ -332,14 +414,20 @@ console.log(`
 **Issues**: ${summary.issues_queued.join(', ')}
 **Groups**: ${summary.execution_groups.map(g => `${g.id}(${g.count})`).join(', ')}
 **Conflicts Resolved**: ${summary.conflicts_resolved}
+**Entry Points**: ${entryPoints.length} (items ready for immediate execution)
 
-Next: \`/issue:execute\`
+Next: \`/issue:execute\` or \`ccw issue next\`
 `);
 
 // Update issue statuses via CLI
 for (const issueId of summary.issues_queued) {
   Bash(`ccw issue update ${issueId} --status queued`);
 }
+
+// Final verification
+const verifyResult = Bash(`ccw issue queue dag 2>/dev/null | head -20`);
+console.log('\n### Verification (DAG Preview):');
+console.log(verifyResult);
 ```
 
 ## Error Handling
@@ -350,6 +438,10 @@ for (const issueId of summary.issues_queued) {
 | Circular dependency | List cycles, abort queue formation |
 | Unresolved conflicts | Agent resolves using ordering rules |
 | Invalid task reference | Skip and warn |
+| **index.json not updated** | Auto-fix: Set active_queue_id to new queue |
+| **Wrong status value** | Auto-fix: Convert non-pending status to "pending" |
+| **No entry points (all have deps)** | Auto-fix: Clear depends_on for first item |
+| **Queue file missing solutions** | Abort with error, agent must regenerate |
 
 ## Related Commands
 

package/.claude/skills/software-manual/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: software-manual
+description: Generate interactive TiddlyWiki-style HTML software manuals with screenshots, API docs, and multi-level code examples. Use when creating user guides, software documentation, or API references. Triggers on "software manual", "user guide", "generate manual", "create docs".
+allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write, mcp__chrome__*
+---
+
+# Software Manual Skill
+
+Generate comprehensive, interactive software manuals in TiddlyWiki-style single-file HTML format.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Context-Optimized Architecture                                  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Phase 1: Requirements      → manual-config.json                │
+│           ↓                                                      │
+│  Phase 2: Exploration       → exploration-*.json                │
+│           ↓                                                      │
+│  Phase 3: Parallel Agents   → sections/section-*.md             │
+│           ↓ (6 Agents)                                          │
+│  Phase 3.5: Consolidation   → consolidation-summary.md          │
+│           ↓                                                      │
+│  Phase 4: Screenshot        → screenshots/*.png                 │
+│           Capture              (via Chrome MCP)                 │
+│           ↓                                                      │
+│  Phase 5: HTML Assembly     → {name}-使用手册.html              │
+│           ↓                                                      │
+│  Phase 6: Refinement        → iterations/                       │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Key Design Principles
+
+1. **主 Agent 编排，子 Agent 执行**: 所有繁重计算委托给 `universal-executor` 子 Agent
+2. **Brief Returns**: Agents return path + summary, not full content (avoid context overflow)
+3. **System Agents**: 使用 `cli-explore-agent` (探索) 和 `universal-executor` (执行)
+4. **成熟库内嵌**: marked.js (MD 解析) + highlight.js (语法高亮)，无 CDN 依赖
+5. **Single-File HTML**: TiddlyWiki-style interactive document with embedded resources
+6. **动态标签**: 根据实际章节自动生成导航标签
+
+## Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Phase 1: Requirements Discovery (主 Agent)                     │
+│  → AskUserQuestion: 收集软件类型、目标用户、文档范围             │
+│  → Output: manual-config.json                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 2: Project Exploration (cli-explore-agent × N)           │
+│  → 并行探索: architecture, ui-routes, api-endpoints, config     │
+│  → Output: exploration-*.json                                   │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 2.5: API Extraction (extract_apis.py)                    │
+│  → 自动提取: FastAPI/TypeDoc/pdoc                                │
+│  → Output: api-docs/{backend,frontend,modules}/*.md             │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 3: Parallel Analysis (universal-executor × 6)            │
+│  → 6 个子 Agent 并行: overview, ui-guide, api-docs, config,     │
+│    troubleshooting, code-examples                               │
+│  → Output: sections/section-*.md                                │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 3.5: Consolidation (universal-executor)                  │
+│  → 质量检查: 一致性、交叉引用、截图标记                          │
+│  → Output: consolidation-summary.md, screenshots-list.json      │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 4: Screenshot Capture (universal-executor + Chrome MCP)  │
+│  → 批量截图: 调用 mcp__chrome__screenshot                        │
+│  → Output: screenshots/*.png + manifest.json                    │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 5: HTML Assembly (universal-executor)                    │
+│  → 组装 HTML: MD→tiddlers, 嵌入 CSS/JS/图片                     │
+│  → Output: {name}-使用手册.html                                  │
+├─────────────────────────────────────────────────────────────────┤
+│  Phase 6: Iterative Refinement (主 Agent)                       │
+│  → 预览 + 用户反馈 + 迭代修复                                    │
+│  → Output: iterations/v*.html                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Agent Configuration
+
+| Agent | Role | Output File | Focus Areas |
+|-------|------|-------------|-------------|
+| overview | Product Manager | section-overview.md | Product intro, features, quick start |
+| ui-guide | UX Expert | section-ui-guide.md | UI operations, step-by-step guides |
+| api-docs | API Architect | section-api-reference.md | REST API, Frontend API |
+| config | DevOps Engineer | section-configuration.md | Env vars, deployment, settings |
+| troubleshooting | Support Engineer | section-troubleshooting.md | FAQs, error codes, solutions |
+| code-examples | Developer Advocate | section-examples.md | Beginner/Intermediate/Advanced examples |
+
+## Agent Return Format
+
+```typescript
+interface ManualAgentReturn {
+  status: "completed" | "partial" | "failed";
+  output_file: string;
+  summary: string;                    // Max 50 chars
+  screenshots_needed: Array<{
+    id: string;                       // e.g., "ss-login-form"
+    url: string;                      // Relative or absolute URL
+    description: string;              // "Login form interface"
+    selector?: string;                // CSS selector for partial screenshot
+    wait_for?: string;                // Element to wait for
+  }>;
+  cross_references: string[];         // Other sections referenced
+  difficulty_level: "beginner" | "intermediate" | "advanced";
+}
+```
+
+## HTML Features (TiddlyWiki-style)
+
+1. **Search**: Full-text search with result highlighting
+2. **Collapse/Expand**: Per-section collapsible content
+3. **Tag Navigation**: Filter by category tags
+4. **Theme Toggle**: Light/Dark mode with localStorage persistence
+5. **Single File**: All CSS/JS/images embedded as Base64
+6. **Offline**: Works without internet connection
+7. **Print-friendly**: Optimized print stylesheet
+
+## Directory Setup
+
+```javascript
+// Generate timestamp directory name
+const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
+const dir = `.workflow/.scratchpad/manual-${timestamp}`;
+
+// Windows
+Bash(`mkdir "${dir}\\sections" && mkdir "${dir}\\screenshots" && mkdir "${dir}\\api-docs" && mkdir "${dir}\\iterations"`);
+```
+
+## Output Structure
+
+```
+.workflow/.scratchpad/manual-{timestamp}/
+├── manual-config.json              # Phase 1
+├── exploration/                    # Phase 2
+│   ├── exploration-architecture.json
+│   ├── exploration-ui-routes.json
+│   └── exploration-api-endpoints.json
+├── sections/                       # Phase 3
+│   ├── section-overview.md
+│   ├── section-ui-guide.md
+│   ├── section-api-reference.md
+│   ├── section-configuration.md
+│   ├── section-troubleshooting.md
+│   └── section-examples.md
+├── consolidation-summary.md        # Phase 3.5
+├── api-docs/                       # API documentation
+│   ├── frontend/                   # TypeDoc output
+│   └── backend/                    # Swagger/OpenAPI output
+├── screenshots/                    # Phase 4
+│   ├── ss-*.png
+│   └── screenshots-manifest.json
+├── iterations/                     # Phase 6
+│   ├── v1.html
+│   └── v2.html
+└── {软件名}-使用手册.html           # Final Output
+```
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | 用户配置收集 |
+| [phases/02-project-exploration.md](phases/02-project-exploration.md) | 项目类型检测 |
+| [phases/02.5-api-extraction.md](phases/02.5-api-extraction.md) | API 自动提取 |
+| [phases/03-parallel-analysis.md](phases/03-parallel-analysis.md) | 6 Agent 并行分析 |
+| [phases/03.5-consolidation.md](phases/03.5-consolidation.md) | 整合与质量检查 |
+| [phases/04-screenshot-capture.md](phases/04-screenshot-capture.md) | Chrome MCP 截图 |
+| [phases/05-html-assembly.md](phases/05-html-assembly.md) | HTML 组装 |
+| [phases/06-iterative-refinement.md](phases/06-iterative-refinement.md) | 迭代优化 |
+| [specs/quality-standards.md](specs/quality-standards.md) | 质量标准 |
+| [specs/writing-style.md](specs/writing-style.md) | 写作风格 |
+| [templates/tiddlywiki-shell.html](templates/tiddlywiki-shell.html) | HTML 模板 |
+| [templates/css/wiki-base.css](templates/css/wiki-base.css) | 基础样式 |
+| [templates/css/wiki-dark.css](templates/css/wiki-dark.css) | 暗色主题 |
+| [scripts/bundle-libraries.md](scripts/bundle-libraries.md) | 库文件打包 |
+| [scripts/api-extractor.md](scripts/api-extractor.md) | API 提取说明 |
+| [scripts/extract_apis.py](scripts/extract_apis.py) | API 提取脚本 |
+| [scripts/screenshot-helper.md](scripts/screenshot-helper.md) | 截图辅助 |

package/.claude/skills/software-manual/phases/01-requirements-discovery.md

@@ -0,0 +1,162 @@
+# Phase 1: Requirements Discovery
+
+Collect user requirements and generate configuration for the manual generation process.
+
+## Objective
+
+Gather essential information about the software project to customize the manual generation:
+- Software type and characteristics
+- Target user audience
+- Documentation scope and depth
+- Special requirements
+
+## Execution Steps
+
+### Step 1: Software Information Collection
+
+Use `AskUserQuestion` to collect:
+
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "What type of software is this project?",
+      header: "Software Type",
+      options: [
+        { label: "Web Application", description: "Frontend + Backend web app with UI" },
+        { label: "CLI Tool", description: "Command-line interface tool" },
+        { label: "SDK/Library", description: "Developer library or SDK" },
+        { label: "Desktop App", description: "Desktop application (Electron, etc.)" }
+      ],
+      multiSelect: false
+    },
+    {
+      question: "Who is the target audience for this manual?",
+      header: "Target Users",
+      options: [
+        { label: "End Users", description: "Non-technical users who use the product" },
+        { label: "Developers", description: "Developers integrating or extending the product" },
+        { label: "Administrators", description: "System admins deploying and maintaining" },
+        { label: "All Audiences", description: "Mixed audience with different sections" }
+      ],
+      multiSelect: false
+    },
+    {
+      question: "What documentation scope do you need?",
+      header: "Doc Scope",
+      options: [
+        { label: "Quick Start", description: "Essential getting started guide only" },
+        { label: "User Guide", description: "Complete user-facing documentation" },
+        { label: "API Reference", description: "Focus on API documentation" },
+        { label: "Comprehensive", description: "Full documentation including all sections" }
+      ],
+      multiSelect: false
+    },
+    {
+      question: "What difficulty levels should code examples cover?",
+      header: "Example Levels",
+      options: [
+        { label: "Beginner Only", description: "Simple, basic examples" },
+        { label: "Beginner + Intermediate", description: "Basic to moderate complexity" },
+        { label: "All Levels", description: "Beginner, Intermediate, and Advanced" }
+      ],
+      multiSelect: false
+    }
+  ]
+});
+```
+
+### Step 2: Auto-Detection (Supplement)
+
+Automatically detect project characteristics:
+
+```javascript
+// Detect from package.json
+const packageJson = Read('package.json');
+const softwareName = packageJson.name;
+const version = packageJson.version;
+const description = packageJson.description;
+
+// Detect tech stack
+const hasReact = packageJson.dependencies?.react;
+const hasVue = packageJson.dependencies?.vue;
+const hasExpress = packageJson.dependencies?.express;
+const hasNestJS = packageJson.dependencies?.['@nestjs/core'];
+
+// Detect CLI
+const hasBin = !!packageJson.bin;
+
+// Detect UI
+const hasPages = Glob('src/pages/**/*').length > 0 || Glob('pages/**/*').length > 0;
+const hasRoutes = Glob('**/routes.*').length > 0;
+```
+
+### Step 3: Generate Configuration
+
+Create `manual-config.json`:
+
+```json
+{
+  "software": {
+    "name": "{{detected or user input}}",
+    "version": "{{from package.json}}",
+    "description": "{{from package.json}}",
+    "type": "{{web|cli|sdk|desktop}}"
+  },
+  "target_audience": "{{end_users|developers|admins|all}}",
+  "doc_scope": "{{quick_start|user_guide|api_reference|comprehensive}}",
+  "example_levels": ["beginner", "intermediate", "advanced"],
+  "tech_stack": {
+    "frontend": "{{react|vue|angular|vanilla}}",
+    "backend": "{{express|nestjs|fastify|none}}",
+    "language": "{{typescript|javascript}}",
+    "ui_framework": "{{tailwind|mui|antd|none}}"
+  },
+  "features": {
+    "has_ui": true,
+    "has_api": true,
+    "has_cli": false,
+    "has_config": true
+  },
+  "agents_to_run": [
+    "overview",
+    "ui-guide",
+    "api-docs",
+    "config",
+    "troubleshooting",
+    "code-examples"
+  ],
+  "screenshot_config": {
+    "enabled": true,
+    "dev_command": "npm run dev",
+    "dev_url": "http://localhost:3000",
+    "wait_timeout": 5000
+  },
+  "output": {
+    "filename": "{{name}}-使用手册.html",
+    "theme": "light",
+    "language": "zh-CN"
+  },
+  "timestamp": "{{ISO8601}}"
+}
+```
+
+## Agent Selection Logic
+
+Based on `doc_scope`, select agents to run:
+
+| Scope | Agents |
+|-------|--------|
+| quick_start | overview |
+| user_guide | overview, ui-guide, config, troubleshooting |
+| api_reference | overview, api-docs, code-examples |
+| comprehensive | ALL 6 agents |
+
+## Output
+
+- **File**: `manual-config.json`
+- **Location**: `.workflow/.scratchpad/manual-{timestamp}/`
+
+## Next Phase
+
+Proceed to [Phase 2: Project Exploration](02-project-exploration.md) with the generated configuration.