claude-code-workflow 6.3.48 → 6.3.49

package/.claude/skills/skill-generator/phases/02-structure-generation.md

@@ -8,9 +8,7 @@
 - 生成 SKILL.md 入口文件
 - 根据执行模式创建对应的子目录
 
-## Input
 
-- 依赖: `skill-config.json` (Phase 1 产出)
 
 ## Execution Steps
 
@@ -23,19 +21,79 @@ const skillDir = `.claude/skills/${config.skill_name}`;
 
 ### Step 2: 创建目录结构
 
+#### 基础目录（所有模式）
+
 ```javascript
-// 基础目录
-Bash(`mkdir -p "${skillDir}/phases"`);
-Bash(`mkdir -p "${skillDir}/specs"`);
-Bash(`mkdir -p "${skillDir}/templates"`);
+// 基础架构
+Bash(`mkdir -p "${skillDir}/{phases,specs,templates,scripts}"`);
+```
+
+#### 执行模式特定目录
+
+```
+config.execution_mode
+    ↓
+    ├─ "sequential"
+    │   ↓ Creates:
+    │   └─ phases/ (基础目录已包含)
+    │      ├─ _orchestrator.md
+    │      └─ workflow.json
+    │
+    └─ "autonomous" | "hybrid"
+        ↓ Creates:
+        └─ phases/actions/
+           ├─ state-schema.md
+           └─ *.md (动作文件)
+```
 
-// Autonomous 模式额外目录
+```javascript
+// Autonomous/Hybrid 模式额外目录
 if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
   Bash(`mkdir -p "${skillDir}/phases/actions"`);
 }
+```
+
+#### Context Strategy 特定目录 (P0 增强)
+
+```javascript
+// ========== P0: 根据上下文策略创建目录 ==========
+const contextStrategy = config.context_strategy || 'file';
+
+if (contextStrategy === 'file') {
+  // 文件策略：创建上下文持久化目录
+  Bash(`mkdir -p "${skillDir}/.scratchpad-template/context"`);
+
+  // 创建上下文模板文件
+  Write(
+    `${skillDir}/.scratchpad-template/context/.gitkeep`,
+    "# Runtime context storage for file-based strategy"
+  );
+}
+// 内存策略无需创建目录 (in-memory only)
+```
+
+**目录树视图**:
 
-// scripts 目录（默认创建，用于存放确定性脚本）
-Bash(`mkdir -p "${skillDir}/scripts"`);
+```
+Sequential + File Strategy:
+  .claude/skills/{skill-name}/
+  ├── phases/
+  │   ├── _orchestrator.md
+  │   ├── workflow.json
+  │   ├── 01-*.md
+  │   └── 02-*.md
+  ├── .scratchpad-template/
+  │   └── context/           ← File strategy persistent storage
+  └── specs/
+
+Autonomous + Memory Strategy:
+  .claude/skills/{skill-name}/
+  ├── phases/
+  │   ├── orchestrator.md
+  │   ├── state-schema.md
+  │   └── actions/
+  │       └── *.md
+  └── specs/
 ```
 
 ### Step 3: 生成 SKILL.md
@@ -192,16 +250,13 @@ function generateReferenceTable(config) {
 }
 ```
 
-## Output
 
-- **Directory**: `.claude/skills/{skill-name}/`
-- **Files**:
-  - `SKILL.md` (入口文件)
-  - `phases/` (执行阶段目录)
-  - `specs/` (规范文档目录)
-  - `templates/` (模板目录)
-  - `scripts/` (脚本目录，存放 Python/Bash 确定性脚本)
 
 ## Next Phase
 
 → [Phase 3: Phase Generation](03-phase-generation.md)
+
+**Data Flow to Phase 3**:
+- Complete directory structure in .claude/skills/{skill-name}/
+- SKILL.md entry file ready for phase/action generation
+- skill-config.json for template population

package/.claude/skills/skill-generator/phases/03-phase-generation.md

@@ -8,10 +8,7 @@
 - Autonomous 模式：生成编排器和动作文件
 - 支持 **文件上下文** 和 **内存上下文** 两种策略
 
-## Input
 
-- 依赖: `skill-config.json`, SKILL.md (Phase 1-2 产出)
-- 模板: `templates/sequential-phase.md`, `templates/autonomous-*.md`
 
 ## 上下文策略 (P0 增强)
 
@@ -55,66 +52,93 @@ const skillRoot = '.claude/skills/skill-generator';
 ```javascript
 if (config.execution_mode === 'sequential') {
   const phases = config.sequential_config.phases;
-  
+
   // ========== P0 增强: 生成声明式编排器 ==========
   const workflowOrchestrator = generateSequentialOrchestrator(config, phases);
   Write(`${skillDir}/phases/_orchestrator.md`, workflowOrchestrator);
-  
+
   // ========== P0 增强: 生成工作流定义 ==========
   const workflowDef = generateWorkflowDefinition(config, phases);
   Write(`${skillDir}/workflow.json`, JSON.stringify(workflowDef, null, 2));
-  
-  // 生成各阶段文件
+
+  // ========== P0 增强: 生成 Phase 0 (强制规范研读) ==========
+  const phase0Content = generatePhase0Spec(config);
+  Write(`${skillDir}/phases/00-spec-study.md`, phase0Content);
+
+  // ========== 生成用户定义的各阶段文件 ==========
   for (let i = 0; i < phases.length; i++) {
     const phase = phases[i];
     const prevPhase = i > 0 ? phases[i-1] : null;
     const nextPhase = i < phases.length - 1 ? phases[i+1] : null;
-    
+
     const content = generateSequentialPhase({
       phaseNumber: i + 1,
       phaseId: phase.id,
       phaseName: phase.name,
       phaseDescription: phase.description || `Execute ${phase.name}`,
-      input: prevPhase ? prevPhase.output : "user input",
+      input: prevPhase ? prevPhase.output : "phase 0 output", // Phase 0 为首个输入源
       output: phase.output,
       nextPhase: nextPhase ? nextPhase.id : null,
       config: config,
       contextStrategy: contextStrategy
     });
-    
+
     Write(`${skillDir}/phases/${phase.id}.md`, content);
   }
 }
 
 // ========== P0 增强: 声明式工作流定义 ==========
 function generateWorkflowDefinition(config, phases) {
+  // ========== P0: 添加强制 Phase 0 ==========
+  const phase0 = {
+    id: '00-spec-study',
+    name: 'Specification Study',
+    order: 0,
+    input: null,
+    output: 'spec-study-complete.flag',
+    description: '⚠️ MANDATORY: Read all specification documents before execution',
+    parallel: false,
+    condition: null,
+    agent: {
+      type: 'universal-executor',
+      run_in_background: false
+    }
+  };
+
   return {
     skill_name: config.skill_name,
     version: "1.0.0",
     execution_mode: "sequential",
     context_strategy: config.context_strategy || "file",
-    
-    // 声明式阶段列表 (类似 software-manual 的 agents_to_run)
-    phases_to_run: phases.map(p => p.id),
-    
-    // 阶段配置
-    phases: phases.map((p, i) => ({
-      id: p.id,
-      name: p.name,
-      order: i + 1,
-      input: i > 0 ? phases[i-1].output : null,
-      output: p.output,
-      // 可选的并行配置
-      parallel: p.parallel || false,
-      // 可选的条件执行
-      condition: p.condition || null,
-      // Agent 配置
-      agent: p.agent || {
-        type: "universal-executor",
-        run_in_background: false
-      }
-    })),
-    
+
+    // ========== P0: Phase 0 置于首位 ==========
+    phases_to_run: ['00-spec-study', ...phases.map(p => p.id)],
+
+    // ========== P0: Phase 0 + 用户定义阶段 ==========
+    phases: [
+      phase0,
+      ...phases.map((p, i) => ({
+        id: p.id,
+        name: p.name,
+        order: i + 1,
+        input: i === 0 ? phase0.output : phases[i-1].output, // 第一个阶段依赖 Phase 0
+        output: p.output,
+        parallel: p.parallel || false,
+        condition: p.condition || null,
+        // Agent 配置 (支持 LLM 集成)
+        agent: p.agent || (config.llm_integration?.enabled ? {
+          type: "llm",
+          tool: config.llm_integration.default_tool,
+          mode: config.llm_integration.mode || "analysis",
+          fallback_chain: config.llm_integration.fallback_chain || [],
+          run_in_background: false
+        } : {
+          type: "universal-executor",
+          run_in_background: false
+        })
+      }))
+    ],
+
     // 终止条件
     termination: {
       on_success: "all_phases_completed",
@@ -236,10 +260,30 @@ async function executePhase(phaseId, phaseConfig, workDir) {
 
 ## 阶段执行计划
 
+**执行流程**:
+
+\`\`\`
+START
+    ↓
+Phase 0: Specification Study
+    ↓ Output: spec-study-complete.flag
+    ↓
+Phase 1: ${phases[0]?.name || 'First Phase'}
+    ↓ Output: ${phases[0]?.output || 'phase-1.json'}
+${phases.slice(1).map((p, i) => `    ↓
+Phase ${i+2}: ${p.name}
+    ↓ Output: ${p.output}`).join('\n')}
+    ↓
+COMPLETE
+\`\`\`
+
+**阶段列表**:
+
 | Order | Phase | Input | Output | Agent |
 |-------|-------|-------|--------|-------|
-${phases.map((p, i) => 
-  `| ${i+1} | ${p.id} | ${i > 0 ? phases[i-1].output : '-'} | ${p.output} | ${p.agent?.type || 'universal-executor'} |`
+| 0 | 00-spec-study | - | spec-study-complete.flag | universal-executor |
+${phases.map((p, i) =>
+  `| ${i+1} | ${p.id} | ${i === 0 ? 'spec-study-complete.flag' : phases[i-1].output} | ${p.output} | ${p.agent?.type || 'universal-executor'} |`
 ).join('\n')}
 
 ## 错误恢复
@@ -754,6 +798,146 @@ ${actions.sort((a, b) => (b.priority || 0) - (a.priority || 0)).map(a =>
 ### Step 4: 辅助函数
 
 ```javascript
+// ========== P0: Phase 0 生成函数 ==========
+function generatePhase0Spec(config) {
+  const skillRoot = '.claude/skills/skill-generator';
+  const specsToRead = [
+    '../_shared/SKILL-DESIGN-SPEC.md',
+    `${skillRoot}/templates/*.md`
+  ];
+
+  return `# Phase 0: Specification Study
+
+⚠️ **MANDATORY PREREQUISITE** - 此阶段不可跳过
+
+## Objective
+
+在生成任何文件前，完整阅读所有规范文档，理解 Skill 设计标准。
+
+## Why This Matters
+
+**不研读规范 (❌)**:
+\`\`\`
+跳过规范
+    ├─ ✗ 不符合标准
+    ├─ ✗ 结构混乱
+    └─ ✗ 质量问题
+\`\`\`
+
+**研读规范 (✅)**:
+\`\`\`
+完整研读
+    ├─ ✓ 标准化输出
+    ├─ ✓ 高质量代码
+    └─ ✓ 易于维护
+\`\`\`
+
+## Required Reading
+
+### P0 - 核心设计规范
+
+\`\`\`javascript
+// 通用设计标准 (MUST READ)
+const designSpec = Read('.claude/skills/_shared/SKILL-DESIGN-SPEC.md');
+
+// 关键内容检查点:
+const checkpoints = {
+  structure: '目录结构约定',
+  naming: '命名规范',
+  quality: '质量标准',
+  output: '输出格式要求'
+};
+\`\`\`
+
+### P1 - 模板文件 (生成前必读)
+
+\`\`\`javascript
+// 根据执行模式加载对应模板
+const templates = {
+  all: [
+    'templates/skill-md.md'  // SKILL.md 入口文件模板
+  ],
+  sequential: [
+    'templates/sequential-phase.md'
+  ],
+  autonomous: [
+    'templates/autonomous-orchestrator.md',
+    'templates/autonomous-action.md'
+  ]
+};
+
+const mode = '${config.execution_mode}';
+const requiredTemplates = [...templates.all, ...templates[mode]];
+
+requiredTemplates.forEach(template => {
+  const content = Read(\`.claude/skills/skill-generator/\${template}\`);
+  // 理解模板结构、变量位置、生成规则
+});
+\`\`\`
+
+## Execution
+
+\`\`\`javascript
+// ========== 加载规范 ==========
+const specs = [];
+
+// 1. 设计规范 (P0)
+specs.push({
+  file: '../_shared/SKILL-DESIGN-SPEC.md',
+  content: Read('.claude/skills/_shared/SKILL-DESIGN-SPEC.md'),
+  priority: 'P0'
+});
+
+// 2. 模板文件 (P1)
+const templateFiles = Glob('.claude/skills/skill-generator/templates/*.md');
+templateFiles.forEach(file => {
+  specs.push({
+    file: file,
+    content: Read(file),
+    priority: 'P1'
+  });
+});
+
+// ========== 内化规范 ==========
+console.log('📖 Reading specifications...');
+specs.forEach(spec => {
+  console.log(\`  [\${spec.priority}] \${spec.file}\`);
+  // 理解内容（无需生成文件，仅内存处理）
+});
+
+// ========== 生成完成标记 ==========
+const result = {
+  status: 'completed',
+  specs_loaded: specs.length,
+  timestamp: new Date().toISOString()
+};
+
+Write(\`\${workDir}/spec-study-complete.flag\`, JSON.stringify(result, null, 2));
+\`\`\`
+
+## Output
+
+- **标记文件**: \`spec-study-complete.flag\` (证明已完成阅读)
+- **副作用**: 内化规范知识，后续阶段遵循标准
+
+## Success Criteria
+
+✅ **通过标准**:
+- [ ] 已阅读 SKILL-DESIGN-SPEC.md
+- [ ] 已阅读执行模式对应的模板文件
+- [ ] 理解目录结构约定
+- [ ] 理解命名规范
+- [ ] 理解质量标准
+
+## Next Phase
+
+→ [Phase 1: Requirements Discovery](01-requirements-discovery.md)
+
+**关键**: 只有完成规范研读后，Phase 1 才能正确收集需求并生成符合标准的配置。
+`;
+}
+
+// ========== 其他辅助函数 ==========
 function toPascalCase(str) {
   return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
 }
@@ -782,21 +966,4 @@ function getPreconditionCheck(action) {
 }
 ```
 
-## Output
-
-### Sequential 模式
-
-- `phases/_orchestrator.md` (声明式编排器)
-- `workflow.json` (工作流定义)
-- `phases/01-{step}.md`, `02-{step}.md`, ...
-
-### Autonomous 模式
-
-- `phases/orchestrator.md` (增强版编排器)
-- `phases/state-schema.md`
-- `specs/action-catalog.md` (声明式动作目录)
-- `phases/actions/action-{name}.md` (多个)
-
-## Next Phase
 
-→ [Phase 4: Specs & Templates](04-specs-templates.md)

package/.claude/skills/skill-generator/phases/04-specs-templates.md

@@ -1,26 +1,107 @@
-# Phase 4: Specs & Templates Generation
+# Phase 4: Specifications & Templates Generation
 
-生成规范文件和模板文件。
+Generate domain requirements, quality standards, agent templates, and action catalogs.
 
 ## Objective
 
-- 生成领域规范 (`specs/{domain}-requirements.md`)
-- 生成质量标准 (`specs/quality-standards.md`)
-- 生成 Agent 模板 (`templates/agent-base.md`)
-- Autonomous 模式额外生成动作目录 (`specs/action-catalog.md`)
+Generate comprehensive specifications and templates:
+- Domain requirements document with validation function
+- Quality standards with automated check system
+- Agent base template with prompt structure
+- Action catalog for autonomous mode (conditional)
 
 ## Input
 
-- 依赖: `skill-config.json`, SKILL.md, phases/*.md
+**File Dependencies**:
+- `skill-config.json` (from Phase 1)
+- `.claude/skills/{skill-name}/` directory (from Phase 2)
+- Generated phase/action files (from Phase 3)
 
-## Execution Steps
+**Required Information**:
+- Skill name, display name, description
+- Execution mode (determines if action-catalog.md is generated)
+- Output format and location
+- Phase/action definitions
 
-### Step 1: 生成领域规范
+## Output
+
+**Generated Files**:
+
+| File | Purpose | Generation Condition |
+|------|---------|---------------------|
+| `specs/{skill-name}-requirements.md` | Domain requirements with validation | Always |
+| `specs/quality-standards.md` | Quality evaluation criteria | Always |
+| `templates/agent-base.md` | Agent prompt template | Always |
+| `specs/action-catalog.md` | Action dependency graph and selection priority | Autonomous/Hybrid mode only |
+
+**File Structure**:
+
+**Domain Requirements** (`specs/{skill-name}-requirements.md`):
+```markdown
+# {display_name} Requirements
+- When to Use (phase/action reference table)
+- Domain Requirements (功能要求, 输出要求, 质量要求)
+- Validation Function (JavaScript code)
+- Error Handling (recovery strategies)
+```
+
+**Quality Standards** (`specs/quality-standards.md`):
+```markdown
+# Quality Standards
+- Quality Dimensions (Completeness 25%, Consistency 25%, Accuracy 25%, Usability 25%)
+- Quality Gates (Pass ≥80%, Review 60-79%, Fail <60%)
+- Issue Classification (Errors, Warnings, Info)
+- Automated Checks (runQualityChecks function)
+```
+
+**Agent Base** (`templates/agent-base.md`):
+```markdown
+# Agent Base Template
+- 通用 Prompt 结构 (ROLE, PROJECT CONTEXT, TASK, CONSTRAINTS, OUTPUT_FORMAT, QUALITY_CHECKLIST)
+- 变量说明 (workDir, output_path)
+- 返回格式 (AgentReturn interface)
+- 角色定义参考 (phase/action specific agents)
+```
+
+**Action Catalog** (`specs/action-catalog.md`, Autonomous/Hybrid only):
+```markdown
+# Action Catalog
+- Available Actions (table with Purpose, Preconditions, Effects)
+- Action Dependencies (Mermaid diagram)
+- State Transitions (state machine table)
+- Selection Priority (ordered action list)
+```
+
+## Decision Logic
+
+```
+Decision (execution_mode check):
+   ├─ mode === 'sequential' → Generate 3 files only
+   │  └─ Files: requirements.md, quality-standards.md, agent-base.md
+   │
+   ├─ mode === 'autonomous' → Generate 4 files
+   │  ├─ Files: requirements.md, quality-standards.md, agent-base.md
+   │  └─ Additional: action-catalog.md (with action dependencies)
+   │
+   └─ mode === 'hybrid' → Generate 4 files
+      ├─ Files: requirements.md, quality-standards.md, agent-base.md
+      └─ Additional: action-catalog.md (with hybrid logic)
+```
+
+## Execution Protocol
 
 ```javascript
+// Phase 4: Generate Specifications & Templates
+// Reference: phases/04-specs-templates.md
+
+// Load config and setup
 const config = JSON.parse(Read(`${workDir}/skill-config.json`));
 const skillDir = `.claude/skills/${config.skill_name}`;
 
+// Ensure specs and templates directories exist (created in Phase 2)
+// skillDir structure: phases/, specs/, templates/
+
+// Step 1: Generate domain requirements
 const domainRequirements = `# ${config.display_name} Requirements
 
 ${config.description}
@@ -29,8 +110,8 @@ ${config.description}
 
 | Phase | Usage | Reference |
 |-------|-------|-----------|
-${config.execution_mode === 'sequential' ? 
-  config.sequential_config.phases.map((p, i) => 
+${config.execution_mode === 'sequential' ?
+  config.sequential_config.phases.map((p, i) =>
     `| Phase ${i+1} | ${p.name} | ${p.id}.md |`
   ).join('\n') :
   `| Orchestrator | 动作选择 | orchestrator.md |
@@ -67,7 +148,7 @@ function validate${toPascalCase(config.skill_name)}(output) {
     { name: "格式正确", pass: output.format === "${config.output.format}" },
     { name: "内容完整", pass: output.content?.length > 0 }
   ];
-  
+
   return {
     passed: checks.filter(c => c.pass).length,
     total: checks.length,
@@ -86,11 +167,8 @@ function validate${toPascalCase(config.skill_name)}(output) {
 `;
 
 Write(`${skillDir}/specs/${config.skill_name}-requirements.md`, domainRequirements);
-```
 
-### Step 2: 生成质量标准
-
-```javascript
+// Step 2: Generate quality standards
 const qualityStandards = `# Quality Standards
 
 ${config.display_name} 的质量评估标准。
@@ -176,7 +254,7 @@ function runQualityChecks(workDir) {
 
   return {
     score: results.overall,
-    gate: results.overall >= 80 ? 'pass' : 
+    gate: results.overall >= 80 ? 'pass' :
           results.overall >= 60 ? 'review' : 'fail',
     details: results
   };
@@ -185,11 +263,8 @@ function runQualityChecks(workDir) {
 `;
 
 Write(`${skillDir}/specs/quality-standards.md`, qualityStandards);
-```
-
-### Step 3: 生成 Agent 模板
 
-```javascript
+// Step 3: Generate agent base template
 const agentBase = `# Agent Base Template
 
 ${config.display_name} 的 Agent 基础模板。
@@ -246,20 +321,17 @@ interface AgentReturn {
 ## 角色定义参考
 
 ${config.execution_mode === 'sequential' ?
-  config.sequential_config.phases.map((p, i) => 
+  config.sequential_config.phases.map((p, i) =>
     `- **Phase ${i+1} Agent**: ${p.name} 专家`
   ).join('\n') :
-  config.autonomous_config.actions.map(a => 
+  config.autonomous_config.actions.map(a =>
     `- **${a.name} Agent**: ${a.description || a.name + ' 执行者'}`
   ).join('\n')}
 `;
 
 Write(`${skillDir}/templates/agent-base.md`, agentBase);
-```
-
-### Step 4: Autonomous 模式 - 动作目录
 
-```javascript
+// Step 4: Conditional - Generate action catalog for autonomous/hybrid mode
 if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
   const actionCatalog = `# Action Catalog
 
@@ -269,7 +341,7 @@ ${config.display_name} 的可用动作目录。
 
 | Action | Purpose | Preconditions | Effects |
 |--------|---------|---------------|---------|
-${config.autonomous_config.actions.map(a => 
+${config.autonomous_config.actions.map(a =>
   `| [${a.id}](../phases/actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
 ).join('\n')}
 
@@ -289,7 +361,7 @@ ${config.autonomous_config.actions.map((a, i, arr) => {
 | From State | Action | To State |
 |------------|--------|----------|
 | pending | action-init | running |
-${config.autonomous_config.actions.slice(1).map(a => 
+${config.autonomous_config.actions.slice(1).map(a =>
   `| running | ${a.id} | running |`
 ).join('\n')}
 | running | action-complete | completed |
@@ -299,30 +371,28 @@ ${config.autonomous_config.actions.slice(1).map(a =>
 
 当多个动作的前置条件都满足时，按以下优先级选择：
 
-${config.autonomous_config.actions.map((a, i) => 
+${config.autonomous_config.actions.map((a, i) =>
   `${i + 1}. \`${a.id}\` - ${a.name}`
 ).join('\n')}
 `;
 
   Write(`${skillDir}/specs/action-catalog.md`, actionCatalog);
 }
-```
-
-### Step 5: 辅助函数
 
-```javascript
+// Helper function
 function toPascalCase(str) {
   return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
 }
-```
 
-## Output
-
-- `specs/{skill-name}-requirements.md` - 领域规范
-- `specs/quality-standards.md` - 质量标准
-- `specs/action-catalog.md` - 动作目录 (Autonomous 模式)
-- `templates/agent-base.md` - Agent 模板
+// Phase output summary
+console.log('Phase 4 complete: Generated specs and templates');
+```
 
 ## Next Phase
 
 → [Phase 5: Validation](05-validation.md)
+
+**Data Flow to Phase 5**:
+- All generated files in `specs/` and `templates/`
+- skill-config.json for validation reference
+- Complete skill directory structure ready for final validation