docs: Add reference-docs-spec and optimize skill-generator for proper document organization

- Create specs/reference-docs-spec.md with comprehensive guidelines for phase-based reference document organization - Update skill-generator's Mandatory Prerequisites to include new reference-docs-spec - Refactor skill-md.md template to generate phase-based reference tables with 'When to Use' guidance - Add generateReferenceTable() function to automatically create structured reference sections - Replace flat template reference lists with phase-based navigation - Update skill-generator's own SKILL.md to demonstrate correct reference documentation pattern - Ensure all generated skills will have clear document usage timing and context
2026-02-05 01:50:27 +08:00 · 2026-01-29 15:28:21 +08:00
parent 26283e7a5a
commit b791c09476
4 changed files with 512 additions and 352 deletions
--- a/.claude/skills/skill-generator/SKILL.md
+++ b/.claude/skills/skill-generator/SKILL.md
@@ -94,6 +94,7 @@ Phase 01 → Phase 02 → Phase 03 → ... → Phase N
 | Document | Purpose | Priority |
 |----------|---------|----------|
 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | 通用设计规范 - 定义所有 Skill 的结构、命名、质量标准 | **P0 - 最高** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | **参考文档生成规范** - 确保生成的skill中Reference Documents部分有正确的分阶段组织和使用时机指引 | **P0 - 最高** |

 ### 模板文件 (生成前必读)

@@ -193,6 +194,7 @@ Phase 3: Phase/Action Generation
 Phase 4: Specs & Templates
   └─ Generate domain specifications and templates
      ├─ Input: skill-config.json (domain context)
+      ├─ ⚠️ 参考规范: [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 确保生成的参考文档有正确的分阶段组织
      ├─ Tool: Write
      │   ├─ Generate: specs/{domain}-requirements.md
      │   ├─ Generate: specs/quality-standards.md
@@ -273,105 +275,89 @@ Write(`${skillDir}/README.md`, generateReadme(config, validation));

 ---

-## Phase Reference Guide

-Navigation and entry points for each execution phase:
+## Reference Documents by Phase

-### Phase 0: Specification Study (Mandatory)
+> **重要**: 本部分展示skill-generator如何组织自己的参考文档，这是生成的skill应该模仿的示例。详见 [specs/reference-docs-spec.md](specs/reference-docs-spec.md)

-**Document**: 🔗 [SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md)
+### 🔧 Phase 0: Specification Study (强制前置)

-**Purpose**: Understand skill design standards before generating
+所有生成操作前必须阅读的规范

-**What to Read**:
- Skill structure conventions
- Naming standards
- Quality criteria
- Output format specifications
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill设计通用规范 | 理解Skill结构和命名规范 ✅ **必读** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 | 确保Reference Documents有正确的组织方式 ✅ **必读** |
+
+### 📋 Phase 1: Requirements Discovery
+
+收集Skill需求和配置
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1执行指南 | 理解如何收集用户需求和生成配置 |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill需求规范 | 理解Skill应包含哪些信息 |
+
+### 🔧 Phase 2: Structure Generation
+
+生成目录结构和入口文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2执行指南 | 理解如何生成目录结构 |
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md模板 | 了解如何生成入口文件 |
+
+### ⚙️ Phase 3: Phase/Action Generation
+
+根据执行模式生成具体的phase或action文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3执行指南 | 理解Sequential vs Autonomous生成逻辑 |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase模板 | 生成Sequential模式的phase文件 |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator模板 | 生成Autonomous模式的编排器 |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Action模板 | 生成Autonomous模式的action |
+
+### ✅ Phase 4: Specs & Templates
+
+生成领域特定的规范和模板
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4执行指南 | 理解如何生成domain-specific文档 |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档规范 | ⭐ 生成Specs时要遵循的规范 |
+
+### 🏁 Phase 5: Validation & Documentation
+
+验证生成结果并生成最终文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-validation.md](phases/05-validation.md) | Phase 5执行指南 | 理解如何验证生成的skill完整性 |
+
+### 🔍 Debugging & Troubleshooting
+
+遇到问题时查阅
+
+| Issue | Solution Document |
+|-------|------------------|
+| 生成的Skill缺少Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 检查是否遵循分阶段组织 |
+| 参考文档组织混乱 | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 核心原则部分 |
+| 生成的文档不符合质量标准 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
+
+### 📚 Reference & Background
+
+用于深度学习和设计决策
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [specs/execution-modes.md](specs/execution-modes.md) | 执行模式详细规范 | Sequential vs Autonomous的对比和适用场景 |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI集成规范 | 生成的Skill如何与CLI集成 |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | 脚本集成规范 | Phase中如何使用脚本 |
+| [templates/script-template.md](templates/script-template.md) | 脚本模板 | Bash + Python统一模板 |

 ---

-### Phase 1: Requirements Discovery
-
-**Document**: 🔗 [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Gather configuration from user via interactive prompts |
-| **Input** | User responses (Skill name, purpose, execution mode) |
-| **Output** | `skill-config.json` (configuration file) |
-| **Key Decision** | Execution mode: Sequential vs Autonomous vs Hybrid |
-
---
-
-### Phase 2: Structure Generation
-
-**Document**: 🔗 [phases/02-structure-generation.md](phases/02-structure-generation.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Create directory structure and entry file |
-| **Input** | `skill-config.json` (from Phase 1) |
-| **Output** | `.claude/skills/{skill-name}/` directory + `SKILL.md` |
-
---
-
-### Phase 3: Phase/Action Generation
-
-**Document**: 🔗 [phases/03-phase-generation.md](phases/03-phase-generation.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Generate execution phases or actions based on mode |
-| **Input** | `skill-config.json` + Templates |
-| **Output** | Sequential: `phases/01-*.md` ... OR Autonomous: `phases/orchestrator.md` + `actions/*.md` |
-
-**Decision Logic**:
-```
-IF execution_mode === "sequential":
-  └─ Generate sequential phases with linear flow
-ELSE IF execution_mode === "autonomous":
-  └─ Generate orchestrator + independent actions
-```
-
---
-
-### Phase 4: Specs & Templates
-
-**Document**: 🔗 [phases/04-specs-templates.md](phases/04-specs-templates.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Generate domain specifications and template files |
-| **Input** | `skill-config.json` (domain context) |
-| **Output** | `specs/{skill-name}-requirements.md`, `specs/quality-standards.md` |
-
---
-
-### Phase 5: Validation & Documentation
-
-**Document**: 🔗 [phases/05-validation.md](phases/05-validation.md)
-
-| Attribute | Value |
-|-----------|-------|
-| **Purpose** | Verify completeness and generate usage documentation |
-| **Input** | All files from previous phases |
-| **Output** | `README.md`, `validation-report.json` |
-
---
-
-## Template Reference
-
-| Template | Generated For | When Used |
-|----------|--------------|-----------|
-| [skill-md.md](templates/skill-md.md) | SKILL.md entry file | Phase 2 |
-| [sequential-phase.md](templates/sequential-phase.md) | Sequential phase files | Phase 3 |
-| [autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator (autonomous) | Phase 3 |
-| [autonomous-action.md](templates/autonomous-action.md) | Action files | Phase 3 |
-| [code-analysis-action.md](templates/code-analysis-action.md) | Code analysis actions | Phase 3 |
-| [llm-action.md](templates/llm-action.md) | LLM-powered actions | Phase 3 |
-| [script-template.md](templates/script-template.md) | Bash + Python scripts | Phase 3/4 |
-
 ## Output Structure

 ### Sequential Mode
@@ -415,4 +401,86 @@ ELSE IF execution_mode === "autonomous":
 │   └── action-base.md
 ├── scripts/
 └── README.md
-```
+```
+
+---
+
+## Reference Documents by Phase
+
+> **重要**: 本部分展示skill-generator如何组织自己的参考文档，这是生成的skill应该模仿的示例。详见 [specs/reference-docs-spec.md](specs/reference-docs-spec.md)
+
+### 🔧 Phase 0: Specification Study (强制前置)
+
+所有生成操作前必须阅读的规范
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill设计通用规范 | 理解Skill结构和命名规范 ✅ **必读** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 | 确保Reference Documents有正确的组织方式 ✅ **必读** |
+
+### 📋 Phase 1: Requirements Discovery
+
+收集Skill需求和配置
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1执行指南 | 理解如何收集用户需求和生成配置 |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill需求规范 | 理解Skill应包含哪些信息 |
+
+### 🔧 Phase 2: Structure Generation
+
+生成目录结构和入口文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2执行指南 | 理解如何生成目录结构 |
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md模板 | 了解如何生成入口文件 |
+
+### ⚙️ Phase 3: Phase/Action Generation
+
+根据执行模式生成具体的phase或action文件
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3执行指南 | 理解Sequential vs Autonomous生成逻辑 |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase模板 | 生成Sequential模式的phase文件 |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator模板 | 生成Autonomous模式的编排器 |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Action模板 | 生成Autonomous模式的action |
+
+### ✅ Phase 4: Specs & Templates
+
+生成领域特定的规范和模板
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4执行指南 | 理解如何生成domain-specific文档 |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档规范 | ⭐ 生成Specs时要遵循的规范 |
+
+### 🏁 Phase 5: Validation & Documentation
+
+验证生成结果并生成最终文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-validation.md](phases/05-validation.md) | Phase 5执行指南 | 理解如何验证生成的skill完整性 |
+
+### 🔍 Debugging & Troubleshooting
+
+遇到问题时查阅
+
+| Issue | Solution Document |
+|-------|------------------|
+| 生成的Skill缺少Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 检查是否遵循分阶段组织 |
+| 参考文档组织混乱 | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 核心原则部分 |
+| 生成的文档不符合质量标准 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
+
+### 📚 Reference & Background
+
+用于深度学习和设计决策
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [specs/execution-modes.md](specs/execution-modes.md) | 执行模式详细规范 | Sequential vs Autonomous的对比和适用场景 |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI集成规范 | 生成的Skill如何与CLI集成 |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | 脚本集成规范 | Phase中如何使用脚本 |
+| [templates/script-template.md](templates/script-template.md) | 脚本模板 | Bash + Python统一模板 |
--- a/.claude/skills/skill-generator/specs/reference-docs-spec.md
+++ b/.claude/skills/skill-generator/specs/reference-docs-spec.md
@@ -0,0 +1,271 @@
+# Reference Documents Generation Specification
+
+> **重要**: 本规范定义如何在生成的skill中组织和展现参考文档，避免重复问题。
+
+## 核心原则
+
+### 1. 分阶段组织 (Phase-Based Organization)
+
+参考文档必须按照skill的执行阶段组织，而不是平铺列表。
+
+**❌ 错误方式** (平铺列表):
+```markdown
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| doc1.md | ... |
+| doc2.md | ... |
+| doc3.md | ... |
+```
+
+**✅ 正确方式** (分阶段导航):
+```markdown
+## Reference Documents by Phase
+
+### 📋 Phase 1: Analysis
+执行Phase 1时查阅的文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| doc1.md | ... | 理解x概念 |
+
+### ⚙️ Phase 2: Implementation
+执行Phase 2时查阅的文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| doc2.md | ... | 实现y功能 |
+```
+
+### 2. 四个标准分组
+
+参考文档必须分为以下四个分组：
+
+| 分组 | 使用时机 | 内容 |
+|-----|---------|------|
+| **Phase N: [Name]** | 执行该Phase时 | 该阶段相关的所有文档 |
+| **🔍 Debugging** | 遇到问题时 | 问题→文档映射表 |
+| **📚 Reference** | 深度学习时 | 模板、原始实现、最佳实践 |
+| (可选) **📌 Quick Links** | 快速导航 | 最常查阅的5-7个文档 |
+
+### 3. 每个文档条目必须包含
+
+```
+| [path](path) | Purpose | When to Use |
+```
+
+**When to Use 列要求**:
+- ✅ 清晰说明使用场景
+- ✅ 描述解决什么问题
+- ❌ 不要简单说 "参考" 或 "了解"
+
+**良好例子**:
+- "理解issue数据结构"
+- "学习Planning Agent的角色"
+- "检查implementation是否达到质量标准"
+- "快速定位状态异常的原因"
+
+**糟糕例子**:
+- "参考文档"
+- "更多信息"
+- "背景知识"
+
+### 4. 执行流程中嵌入文档指引
+
+在"Execution Flow"部分，每个Phase说明中应包含"查阅"提示：
+
+```markdown
+### Phase 2: Planning Pipeline
+→ **查阅**: action-plan.md, subagent-roles.md
+→ 具体流程说明...
+```
+
+### 5. 问题排查快速查询表
+
+应包含常见问题到文档的映射：
+
+```markdown
+### 🔍 Debugging & Troubleshooting
+
+| Issue | Solution Document |
+|-------|------------------|
+| Phase执行失败 | 查阅相应Phase文档 |
+| 输出格式不符 | specs/quality-standards.md |
+| 数据验证失败 | specs/schema-validation.md |
+```
+
+---
+
+## 生成规则
+
+### 规则 1: 文档分类识别
+
+根据skill的phases自动生成分组：
+
+```javascript
+const phaseEmojis = {
+  'discovery': '📋',      // 收集、探索
+  'generation': '🔧',     // 生成、创建
+  'analysis': '🔍',       // 分析、审查
+  'implementation': '⚙️', // 实现、执行
+  'validation': '✅',     // 验证、测试
+  'completion': '🏁',     // 完成、收尾
+};
+
+// 为每个phase生成一个章节
+phases.forEach((phase, index) => {
+  const emoji = phaseEmojis[phase.type] || '📌';
+  const title = `### ${emoji} Phase ${index + 1}: ${phase.name}`;
+  // 列出该phase相关的所有文档
+});
+```
+
+### 规则 2: 文档到Phase的映射
+
+在config中，specs和templates应标注所属的phases：
+
+```json
+{
+  "specs": [
+    {
+      "path": "specs/issue-handling.md",
+      "purpose": "Issue数据规范",
+      "phases": ["phase-2", "phase-3"],  // 这个spec与哪些phase相关
+      "context": "理解issue结构和验证规则"
+    }
+  ]
+}
+```
+
+### 规则 3: 优先级和必读性
+
+用视觉符号区分文档的重要性：
+
+```markdown
+| Document | When | Notes |
+|----------|------|-------|
+| spec.md | **执行前必读** | ✅ 强制前置 |
+| action.md | 执行时查阅 | 操作指南 |
+| template.md | 参考学习 | 可选深入 |
+```
+
+### 规则 4: 避免重复
+
+- **Mandatory Prerequisites** 部分：列出强制必读的P0规范
+- **Reference Documents by Phase** 部分：列出所有文档 (包括强制必读的)
+- 两个部分的文档可以重叠，但目的不同：
+  - Prerequisites：强调"必须先读"
+  - Reference：提供"完整导航"
+
+---
+
+## 实现示例
+
+### Sequential Skill 示例
+
+```markdown
+## ⚠️ Mandatory Prerequisites (强制前置条件)
+
+| Document | Purpose | When |
+|----------|---------|------|
+| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | **执行前必读** |
+| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案结构 | **执行前必读** |
+
+---
+
+## Reference Documents by Phase
+
+### 📋 Phase 1: Issue Collection
+执行Phase 1时查阅的文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-list.md](phases/actions/action-list.md) | Issue加载逻辑 | 理解如何收集issues |
+| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | 验证issue格式 ✅ **必读** |
+
+### ⚙️ Phase 2: Planning
+执行Phase 2时查阅的文档
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-plan.md](phases/actions/action-plan.md) | Planning流程 | 理解issue→solution转换 |
+| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案结构 | 验证solution JSON格式 ✅ **必读** |
+
+### 🔍 Debugging & Troubleshooting
+
+| Issue | Solution Document |
+|-------|------------------|
+| Phase 1失败 | [phases/actions/action-list.md](phases/actions/action-list.md) |
+| Planning输出不符 | [phases/actions/action-plan.md](phases/actions/action-plan.md) + [specs/solution-schema.md](specs/solution-schema.md) |
+| 数据验证失败 | [specs/issue-handling.md](specs/issue-handling.md) |
+
+### 📚 Reference & Background
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [../issue-plan.md](../../.codex/prompts/issue-plan.md) | 原始实现 | Planning Agent system prompt |
+```
+
+---
+
+## 生成算法
+
+```javascript
+function generateReferenceDocuments(config) {
+  let result = '## Reference Documents by Phase\n\n';
+
+  // 为每个phase生成一个章节
+  const phases = config.phases || config.actions || [];
+
+  phases.forEach((phase, index) => {
+    const phaseNum = index + 1;
+    const emoji = getPhaseEmoji(phase.type);
+    const title = phase.display_name || phase.name;
+
+    result += `### ${emoji} Phase ${phaseNum}: ${title}\n`;
+    result += `执行Phase ${phaseNum}时查阅的文档\n\n`;
+
+    // 找出该phase相关的所有文档
+    const docs = config.specs.filter(spec =>
+      (spec.phases || []).includes(`phase-${phaseNum}`) ||
+      matchesByName(spec.path, phase.name)
+    );
+
+    if (docs.length > 0) {
+      result += '| Document | Purpose | When to Use |\n';
+      result += '|----------|---------|-------------|\n';
+      docs.forEach(doc => {
+        const required = doc.phases && doc.phases[0] === `phase-${phaseNum}` ? ' ✅ **必读**' : '';
+        result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context}${required} |\n`;
+      });
+      result += '\n';
+    }
+  });
+
+  // 问题排查部分
+  result += '### 🔍 Debugging & Troubleshooting\n\n';
+  result += generateDebuggingTable(config);
+
+  // 深度学习参考
+  result += '### 📚 Reference & Background\n\n';
+  result += generateReferenceTable(config);
+
+  return result;
+}
+```
+
+---
+
+## 检查清单
+
+生成skill的SKILL.md时，参考文档部分应满足：
+
+- [ ] 有明确的"## Reference Documents by Phase"标题
+- [ ] 每个Phase都有对应的章节 (用emoji标识)
+- [ ] 每个文档条目包含"When to Use"列
+- [ ] 包含"🔍 Debugging & Troubleshooting"部分
+- [ ] 包含"📚 Reference & Background"部分
+- [ ] 强制必读文档用✅和**粗体**标记
+- [ ] Execution Flow部分中有"→ **查阅**: ..."指引
+- [ ] 避免过长的文档列表 (一个Phase最多5-8个文档)
--- a/.claude/skills/skill-generator/templates/skill-md.md
+++ b/.claude/skills/skill-generator/templates/skill-md.md
@@ -80,7 +80,9 @@ Bash(\`mkdir -p "\${workDir}"\`);
 {{output_structure}}
 \`\`\`

-## Reference Documents
+## Reference Documents by Phase
+
+> **重要**: 参考文档应按执行阶段组织，清晰标注使用时机和场景。避免平铺文档列表。

 {{reference_table}}

@@ -132,12 +134,12 @@ function generatePrerequisites(config) {
  const templates = config.templates || [];

  let result = '### 规范文档 (必读)\n\n';
-  result += '| Document | Purpose | Priority |\n';
-  result += '|----------|---------|----------|\n';
+  result += '| Document | Purpose | When |\n';
+  result += '|----------|---------|------|\n';

  specs.forEach((spec, index) => {
-    const priority = index === 0 ? '**P0 - 最高**' : 'P1';
-    result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${priority} |\n`;
+    const when = index === 0 ? '**执行前必读**' : '执行前推荐';
+    result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${when} |\n`;
  });

  if (templates.length > 0) {
@@ -151,6 +153,80 @@ function generatePrerequisites(config) {

  return result;
 }
+
+// ⭐ 新增：生成分阶段参考文档指南
+function generateReferenceTable(config) {
+  const phases = config.phases || config.actions || [];
+  const specs = config.specs || [];
+  const templates = config.templates || [];
+
+  let result = '';
+
+  // 为每个执行阶段生成文档导航
+  phases.forEach((phase, index) => {
+    const phaseNum = index + 1;
+    const phaseEmoji = getPhaseEmoji(phase.type || 'default');
+    const phaseTitle = phase.display_name || phase.name;
+
+    result += `### ${phaseEmoji} Phase ${phaseNum}: ${phaseTitle}\n`;
+    result += `执行Phase ${phaseNum}时查阅的文档\n\n`;
+
+    // 列出该阶段相关的文档
+    const relatedDocs = filterDocsByPhase(specs, phase, index);
+    if (relatedDocs.length > 0) {
+      result += '| Document | Purpose | When to Use |\n';
+      result += '|----------|---------|-------------|\n';
+      relatedDocs.forEach(doc => {
+        result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context || '查阅内容'} |\n`;
+      });
+      result += '\n';
+    }
+  });
+
+  // 问题排查部分
+  result += '### 🔍 Debugging & Troubleshooting (问题排查)\n';
+  result += '遇到问题时查阅的文档\n\n';
+  result += '| Issue | Solution Document |\n';
+  result += '|-------|-------------------|\n';
+  result += `| Phase执行失败 | 查阅相应Phase的文档 |\n`;
+  result += `| 输出不符合预期 | [specs/quality-standards.md](specs/quality-standards.md) - 验证质量标准 |\n`;
+  result += '\n';
+
+  // 深度学习参考
+  result += '### 📚 Reference & Background (深度学习)\n';
+  result += '用于理解原始实现和设计决策\n\n';
+  result += '| Document | Purpose | Notes |\n';
+  result += '|----------|---------|-------|\n';
+  templates.forEach(tmpl => {
+    result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} | 生成时参考 |\n`;
+  });
+
+  return result;
+}
+
+// 辅助函数：获取Phase表情符号
+function getPhaseEmoji(phaseType) {
+  const emojiMap = {
+    'discovery': '📋',
+    'generation': '🔧',
+    'analysis': '🔍',
+    'implementation': '⚙️',
+    'validation': '✅',
+    'completion': '🏁',
+    'default': '📌'
+  };
+  return emojiMap[phaseType] || emojiMap['default'];
+}
+
+// 辅助函数：根据Phase过滤文档
+function filterDocsByPhase(specs, phase, phaseIndex) {
+  // 简单过滤逻辑：匹配phase名称关键词
+  const keywords = phase.name.toLowerCase().split('-');
+  return specs.filter(spec => {
+    const specName = spec.path.toLowerCase();
+    return keywords.some(kw => specName.includes(kw));
+  });
+}
 ```

 ## Sequential 模式示例
--- a/.codex/skills/codex-issue-plan-execute/README.md
+++ b/.codex/skills/codex-issue-plan-execute/README.md
@@ -1,255 +0,0 @@
-# Codex Issue Plan-Execute Skill
-
-简化的 Codex issue 规划-执行工作流 Skill。
-
-## 快速开始
-
-### 安装
-
-该 Skill 已经在 `~/.claude/skills/codex-issue-plan-execute/` 中生成。
-
-### 使用方式
-
-#### 方式 1：执行单个 issue
-
-```bash
-codex -p "@.codex/prompts/codex-issue-plan-execute --issue ISS-001"
-```
-
-#### 方式 2：批量执行多个 issues
-
-```bash
-codex -p "@.codex/prompts/codex-issue-plan-execute --issues ISS-001,ISS-002,ISS-003"
-```
-
-#### 方式 3：交互式选择
-
-```bash
-codex -p "@.codex/prompts/codex-issue-plan-execute"
-# 系统会显示 issues 列表，你可以交互式选择
-```
-
-#### 方式 4：恢复之前的执行
-
-```bash
-codex -p "@.codex/prompts/codex-issue-plan-execute --resume .workflow/.scratchpad/codex-issue-20250129-120000"
-```
-
-## 工作流程
-
-```
-Initialize
-  ↓
-List Issues (显示所有 pending/planned issues)
-  ↓
-Plan Solutions (为选中的 issues 生成解决方案)
-  ↓
-Execute Solutions (按顺序执行解决方案)
-  ↓
-Complete (生成报告并完成)
-```
-
-### 每个阶段做什么
-
-**Phase 1: Initialize**
- 创建工作目录
- 初始化状态 JSON
- 准备执行环境
-
-**Phase 2: List Issues**
- 从 ccw issue 加载 issues
- 显示当前状态矩阵
- 收集用户的规划/执行选择
-
-**Phase 3: Plan Solutions**
- 为每个 issue 生成规划 subagent
- 分析代码并设计解决方案
- 绑定 solution 到 issue
- 更新 issue 状态 → "planned"
-
-**Phase 4: Execute Solutions**
- 加载已规划的解决方案
- 执行所有 tasks（implement → test → verify）
- 一次性提交所有更改
- 更新 solution 状态 → "completed"
-
-**Phase 5: Complete**
- 生成执行报告
- 保存最终状态和统计信息
- 输出完成摘要
-
-## 目录结构
-
-```
-codex-issue-plan-execute/
-├── SKILL.md                              # 入口文件（你已读）
-├── phases/
-│   ├── orchestrator.md                   # Orchestrator 编排逻辑
-│   ├── state-schema.md                   # 状态结构定义
-│   └── actions/
-│       ├── action-init.md                # 初始化
-│       ├── action-list.md                # 列表显示
-│       ├── action-plan.md                # 规划
-│       ├── action-execute.md             # 执行
-│       └── action-complete.md            # 完成
-├── specs/
-│   ├── issue-handling.md                 # Issue 处理规范
-│   ├── solution-schema.md                # Solution 数据结构
-│   ├── quality-standards.md              # 质量标准
-│   └── subagent-roles.md                 # Subagent 角色定义
-└── templates/
-    └── (可选的 prompt 模板)
-```
-
-## 配置选项
-
-### 命令行参数
-
-| 参数 | 值 | 说明 |
-|------|-----|------|
-| `--issue` | ISS-ID | 执行单个 issue |
-| `--issues` | ID1,ID2,ID3 | 执行多个 issues |
-| `--resume` | path | 从快照恢复 |
-| `--skip-plan` | - | 跳过规划阶段，直接执行 |
-| `--skip-execute` | - | 仅规划，不执行 |
-
-## 关键特性
-
-### ✓ 已实现
-
- [x] Autonomous 状态驱动编排
- [x] 双 Agent 规划-执行分离
- [x] 最小化队列（仅保留待执行项）
- [x] 批量 issue 处理
- [x] 完整状态持久化
- [x] 快照恢复能力
- [x] 详细执行报告
-
-### ⌛ 可选增强
-
- [ ] 并行规划（当前串行）
- [ ] 冲突检测和优先级排序
- [ ] 自动重试失败项
- [ ] WebUI 显示进度
- [ ] Slack 通知
-
-## 输出文件
-
-执行完成后会在 `.workflow/.scratchpad/codex-issue-{timestamp}/` 生成：
-
-```
-state.json                 # 最终状态快照
-state-history.json         # 状态变更历史
-queue.json                 # 执行队列
-execution-results.json     # 执行结果汇总
-final-report.md            # 最终报告
-solutions/
-  ├── ISS-001-plan.json
-  ├── ISS-001-execution.json
-  ├── ISS-002-plan.json
-  └── ...
-snapshots/
-  ├── snapshot-before-plan.json
-  ├── snapshot-before-execute.json
-  └── ...
-```
-
-## 故障排除
-
-### Issue 无法加载
-
-```bash
-# 检查 issues 是否存在
-ccw issue list --status registered
-
-# 手动创建 issue
-ccw issue init ISS-001 --title "My Issue"
-```
-
-### 规划失败
-
- 检查 `~/.codex/agents/issue-plan-agent.md` 是否存在
- 查看错误日志中的具体原因
- 从快照恢复后重试
-
-### 执行失败
-
- 检查测试是否通过：`npm test`
- 查看 acceptance criteria 是否满足
- 从快照恢复：`codex ... --resume {snapshot_path}`
-
-### 状态不一致
-
- 删除旧的 state.json 重新开始
- 或从最后一个有效快照恢复
-
-## 性能指标
-
-| 指标 | 预期值 |
-|------|--------|
-| 初始化 | < 1s |
-| 列表加载 | < 2s |
-| 单 issue 规划 | 30-60s |
-| 单 issue 执行 | 1-5 min |
-| 总处理时间（3 issues） | 5-20 min |
-
-## 系统要求
-
- Codex CLI >= 2.0
- Node.js >= 14
- Git 仓库已初始化
- ccw issue 命令可用
-
-## 贡献指南
-
-### 修改 Action
-
-编辑 `phases/actions/action-*.md` 文件
-
-### 修改规范
-
-编辑 `specs/*.md` 文件
-
-### 测试 Skill
-
-```bash
-# 测试单个 issue
-ccw codex issue:plan-execute --issue ISS-001
-
-# 测试批量处理
-ccw codex issue:plan-execute --issues ISS-001,ISS-002
-
-# 检查输出
-cat .workflow/.scratchpad/codex-issue-*/final-report.md
-```
-
-## 版本历史
-
- **v1.0** (2025-01-29)
-  - 初始发布
-  - Autonomous 编排模式
-  - 双 Agent 规划-执行分离
-  - 简化队列管理
-
-## 许可证
-
-与 Claude Code 相同
-
-## 支持
-
-遇到问题？
-
-1. 查看 [SKILL.md](SKILL.md) 了解架构
-2. 查看 `specs/` 下的规范文档
-3. 检查执行日志和快照
-4. 查看最终报告 `final-report.md`
-
---
-
-**Ready to use!** 🚀
-
-开始你的第一个 issue 规划-执行工作流：
-
-```bash
-codex -p "@.codex/prompts/codex-issue-plan-execute"
-```