claude-code-workflow 6.3.18 → 6.3.20

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

@@ -0,0 +1,328 @@
+# Phase 4: Specs & Templates Generation
+
+生成规范文件和模板文件。
+
+## Objective
+
+- 生成领域规范 (`specs/{domain}-requirements.md`)
+- 生成质量标准 (`specs/quality-standards.md`)
+- 生成 Agent 模板 (`templates/agent-base.md`)
+- Autonomous 模式额外生成动作目录 (`specs/action-catalog.md`)
+
+## Input
+
+- 依赖: `skill-config.json`, SKILL.md, phases/*.md
+
+## Execution Steps
+
+### Step 1: 生成领域规范
+
+```javascript
+const config = JSON.parse(Read(`${workDir}/skill-config.json`));
+const skillDir = `.claude/skills/${config.skill_name}`;
+
+const domainRequirements = `# ${config.display_name} Requirements
+
+${config.description}
+
+## When to Use
+
+| Phase | Usage | Reference |
+|-------|-------|-----------|
+${config.execution_mode === 'sequential' ? 
+  config.sequential_config.phases.map((p, i) => 
+    `| Phase ${i+1} | ${p.name} | ${p.id}.md |`
+  ).join('\n') :
+  `| Orchestrator | 动作选择 | orchestrator.md |
+| Actions | 动作执行 | actions/*.md |`}
+
+---
+
+## Domain Requirements
+
+### 功能要求
+
+- [ ] 要求1: TODO
+- [ ] 要求2: TODO
+- [ ] 要求3: TODO
+
+### 输出要求
+
+- [ ] 格式: ${config.output.format}
+- [ ] 位置: ${config.output.location}
+- [ ] 命名: ${config.output.filename_pattern}
+
+### 质量要求
+
+- [ ] 完整性: 所有必需内容存在
+- [ ] 一致性: 术语和格式统一
+- [ ] 准确性: 内容基于实际分析
+
+## Validation Function
+
+\`\`\`javascript
+function validate${toPascalCase(config.skill_name)}(output) {
+  const checks = [
+    // TODO: 添加验证规则
+    { name: "格式正确", pass: output.format === "${config.output.format}" },
+    { name: "内容完整", pass: output.content?.length > 0 }
+  ];
+  
+  return {
+    passed: checks.filter(c => c.pass).length,
+    total: checks.length,
+    details: checks
+  };
+}
+\`\`\`
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| 输入数据缺失 | 返回明确错误信息 |
+| 处理超时 | 缩小范围，重试 |
+| 输出验证失败 | 记录问题，人工审核 |
+`;
+
+Write(`${skillDir}/specs/${config.skill_name}-requirements.md`, domainRequirements);
+```
+
+### Step 2: 生成质量标准
+
+```javascript
+const qualityStandards = `# Quality Standards
+
+${config.display_name} 的质量评估标准。
+
+## Quality Dimensions
+
+### 1. Completeness (完整性) - 25%
+
+| 要求 | 权重 | 检查方式 |
+|------|------|----------|
+| 所有必需输出存在 | 10 | 文件检查 |
+| 内容覆盖完整 | 10 | 内容分析 |
+| 无占位符残留 | 5 | 文本搜索 |
+
+### 2. Consistency (一致性) - 25%
+
+| 方面 | 检查 |
+|------|------|
+| 术语 | 同一概念使用相同术语 |
+| 格式 | 标题层级、代码块格式一致 |
+| 风格 | 语气和表达方式统一 |
+
+### 3. Accuracy (准确性) - 25%
+
+| 要求 | 说明 |
+|------|------|
+| 数据正确 | 引用和数据无错误 |
+| 逻辑正确 | 流程和关系描述准确 |
+| 代码正确 | 代码示例可运行 |
+
+### 4. Usability (可用性) - 25%
+
+| 指标 | 目标 |
+|------|------|
+| 可读性 | 结构清晰，易于理解 |
+| 可导航 | 目录和链接正确 |
+| 可操作 | 步骤明确，可执行 |
+
+## Quality Gates
+
+| Gate | Threshold | Action |
+|------|-----------|--------|
+| Pass | ≥ 80% | 输出最终产物 |
+| Review | 60-79% | 处理警告后继续 |
+| Fail | < 60% | 必须修复 |
+
+## Issue Classification
+
+### Errors (Must Fix)
+
+- 必需输出缺失
+- 数据错误
+- 代码不可运行
+
+### Warnings (Should Fix)
+
+- 格式不一致
+- 内容深度不足
+- 缺少示例
+
+### Info (Nice to Have)
+
+- 优化建议
+- 增强机会
+
+## Automated Checks
+
+\`\`\`javascript
+function runQualityChecks(workDir) {
+  const results = {
+    completeness: checkCompleteness(workDir),
+    consistency: checkConsistency(workDir),
+    accuracy: checkAccuracy(workDir),
+    usability: checkUsability(workDir)
+  };
+
+  results.overall = (
+    results.completeness * 0.25 +
+    results.consistency * 0.25 +
+    results.accuracy * 0.25 +
+    results.usability * 0.25
+  );
+
+  return {
+    score: results.overall,
+    gate: results.overall >= 80 ? 'pass' : 
+          results.overall >= 60 ? 'review' : 'fail',
+    details: results
+  };
+}
+\`\`\`
+`;
+
+Write(`${skillDir}/specs/quality-standards.md`, qualityStandards);
+```
+
+### Step 3: 生成 Agent 模板
+
+```javascript
+const agentBase = `# Agent Base Template
+
+${config.display_name} 的 Agent 基础模板。
+
+## 通用 Prompt 结构
+
+\`\`\`
+[ROLE] 你是{角色}，专注于{职责}。
+
+[PROJECT CONTEXT]
+Skill: ${config.skill_name}
+目标: ${config.description}
+
+[TASK]
+{任务描述}
+- 输出: {output_path}
+- 格式: ${config.output.format}
+
+[CONSTRAINTS]
+- 约束1
+- 约束2
+
+[OUTPUT_FORMAT]
+1. 执行任务
+2. 返回 JSON 简要信息
+
+[QUALITY_CHECKLIST]
+- [ ] 输出格式正确
+- [ ] 内容完整无遗漏
+- [ ] 无占位符残留
+\`\`\`
+
+## 变量说明
+
+| 变量 | 来源 | 示例 |
+|------|------|------|
+| {workDir} | 运行时 | .workflow/.scratchpad/${config.skill_name}-xxx |
+| {output_path} | 配置 | ${config.output.location}/${config.output.filename_pattern} |
+
+## 返回格式
+
+\`\`\`typescript
+interface AgentReturn {
+  status: "completed" | "partial" | "failed";
+  output_file: string;
+  summary: string;  // Max 50 chars
+  stats?: {
+    items_processed?: number;
+    errors?: number;
+  };
+}
+\`\`\`
+
+## 角色定义参考
+
+${config.execution_mode === 'sequential' ?
+  config.sequential_config.phases.map((p, i) => 
+    `- **Phase ${i+1} Agent**: ${p.name} 专家`
+  ).join('\n') :
+  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
+if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
+  const actionCatalog = `# Action Catalog
+
+${config.display_name} 的可用动作目录。
+
+## Available Actions
+
+| Action | Purpose | Preconditions | Effects |
+|--------|---------|---------------|---------|
+${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')}
+
+## Action Dependencies
+
+\`\`\`mermaid
+graph TD
+${config.autonomous_config.actions.map((a, i, arr) => {
+  if (i === 0) return `    ${a.id.replace(/-/g, '_')}[${a.name}]`;
+  const prev = arr[i-1];
+  return `    ${prev.id.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]`;
+}).join('\n')}
+\`\`\`
+
+## State Transitions
+
+| From State | Action | To State |
+|------------|--------|----------|
+| pending | action-init | running |
+${config.autonomous_config.actions.slice(1).map(a => 
+  `| running | ${a.id} | running |`
+).join('\n')}
+| running | action-complete | completed |
+| running | action-abort | failed |
+
+## Selection Priority
+
+当多个动作的前置条件都满足时，按以下优先级选择：
+
+${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
+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 模板
+
+## Next Phase
+
+→ [Phase 5: Validation](05-validation.md)

package/.claude/skills/skill-generator/phases/05-validation.md

@@ -0,0 +1,334 @@
+# Phase 5: Validation & Documentation
+
+验证生成的 Skill 完整性并生成使用说明。
+
+## Objective
+
+- 验证所有必需文件存在
+- 检查文件内容完整性
+- 生成 README.md 使用说明
+- 输出验证报告
+
+## Input
+
+- 依赖: 所有前序阶段产出
+- 生成的 Skill 目录
+
+## Execution Steps
+
+### Step 1: 文件完整性检查
+
+```javascript
+const config = JSON.parse(Read(`${workDir}/skill-config.json`));
+const skillDir = `.claude/skills/${config.skill_name}`;
+
+const requiredFiles = {
+  common: [
+    'SKILL.md',
+    `specs/${config.skill_name}-requirements.md`,
+    'specs/quality-standards.md',
+    'templates/agent-base.md'
+  ],
+  sequential: config.sequential_config?.phases?.map(p => `phases/${p.id}.md`) || [],
+  autonomous: [
+    'phases/orchestrator.md',
+    'phases/state-schema.md',
+    'specs/action-catalog.md',
+    ...(config.autonomous_config?.actions?.map(a => `phases/actions/${a.id}.md`) || [])
+  ]
+};
+
+const filesToCheck = [
+  ...requiredFiles.common,
+  ...(config.execution_mode === 'sequential' ? requiredFiles.sequential : requiredFiles.autonomous)
+];
+
+const fileCheckResults = filesToCheck.map(file => {
+  const fullPath = `${skillDir}/${file}`;
+  try {
+    const content = Read(fullPath);
+    return {
+      file: file,
+      exists: true,
+      size: content.length,
+      hasContent: content.length > 100,
+      hasTodo: content.includes('TODO')
+    };
+  } catch (e) {
+    return {
+      file: file,
+      exists: false,
+      size: 0,
+      hasContent: false,
+      hasTodo: false
+    };
+  }
+});
+```
+
+### Step 2: 内容质量检查
+
+```javascript
+const contentChecks = [];
+
+// 检查 SKILL.md
+const skillMd = Read(`${skillDir}/SKILL.md`);
+contentChecks.push({
+  file: 'SKILL.md',
+  checks: [
+    { name: 'Front Matter', pass: skillMd.startsWith('---') },
+    { name: 'Architecture', pass: skillMd.includes('## Architecture') },
+    { name: 'Execution Flow', pass: skillMd.includes('## Execution Flow') },
+    { name: 'References', pass: skillMd.includes('## Reference Documents') }
+  ]
+});
+
+// 检查 Phase 文件
+const phaseFiles = Glob(`${skillDir}/phases/*.md`);
+for (const phaseFile of phaseFiles) {
+  if (phaseFile.includes('/actions/')) continue; // 单独检查
+  
+  const content = Read(phaseFile);
+  contentChecks.push({
+    file: phaseFile.replace(skillDir + '/', ''),
+    checks: [
+      { name: 'Objective', pass: content.includes('## Objective') },
+      { name: 'Execution', pass: content.includes('## Execution') || content.includes('## Execution Steps') },
+      { name: 'Output', pass: content.includes('## Output') },
+      { name: 'Code Blocks', pass: content.includes('```') }
+    ]
+  });
+}
+
+// 检查 Specs 文件
+const specFiles = Glob(`${skillDir}/specs/*.md`);
+for (const specFile of specFiles) {
+  const content = Read(specFile);
+  contentChecks.push({
+    file: specFile.replace(skillDir + '/', ''),
+    checks: [
+      { name: 'Has Content', pass: content.length > 200 },
+      { name: 'Has Structure', pass: content.includes('##') },
+      { name: 'No Empty Sections', pass: !content.match(/##[^#]+\n\n##/) }
+    ]
+  });
+}
+```
+
+### Step 3: 生成验证报告
+
+```javascript
+const report = {
+  skill_name: config.skill_name,
+  execution_mode: config.execution_mode,
+  generated_at: new Date().toISOString(),
+  
+  file_checks: {
+    total: fileCheckResults.length,
+    existing: fileCheckResults.filter(f => f.exists).length,
+    with_content: fileCheckResults.filter(f => f.hasContent).length,
+    with_todos: fileCheckResults.filter(f => f.hasTodo).length,
+    details: fileCheckResults
+  },
+  
+  content_checks: {
+    files_checked: contentChecks.length,
+    all_passed: contentChecks.every(c => c.checks.every(ch => ch.pass)),
+    details: contentChecks
+  },
+  
+  summary: {
+    status: calculateOverallStatus(fileCheckResults, contentChecks),
+    issues: collectIssues(fileCheckResults, contentChecks),
+    recommendations: generateRecommendations(fileCheckResults, contentChecks)
+  }
+};
+
+Write(`${workDir}/validation-report.json`, JSON.stringify(report, null, 2));
+
+function calculateOverallStatus(fileResults, contentResults) {
+  const allFilesExist = fileResults.every(f => f.exists);
+  const allContentPassed = contentResults.every(c => c.checks.every(ch => ch.pass));
+  
+  if (allFilesExist && allContentPassed) return 'PASS';
+  if (allFilesExist) return 'REVIEW';
+  return 'FAIL';
+}
+
+function collectIssues(fileResults, contentResults) {
+  const issues = [];
+  
+  fileResults.filter(f => !f.exists).forEach(f => {
+    issues.push({ type: 'ERROR', message: `文件缺失: ${f.file}` });
+  });
+  
+  fileResults.filter(f => f.hasTodo).forEach(f => {
+    issues.push({ type: 'WARNING', message: `包含 TODO: ${f.file}` });
+  });
+  
+  contentResults.forEach(c => {
+    c.checks.filter(ch => !ch.pass).forEach(ch => {
+      issues.push({ type: 'WARNING', message: `${c.file}: 缺少 ${ch.name}` });
+    });
+  });
+  
+  return issues;
+}
+
+function generateRecommendations(fileResults, contentResults) {
+  const recommendations = [];
+  
+  if (fileResults.some(f => f.hasTodo)) {
+    recommendations.push('替换所有 TODO 占位符为实际内容');
+  }
+  
+  contentResults.forEach(c => {
+    if (c.checks.some(ch => !ch.pass)) {
+      recommendations.push(`完善 ${c.file} 的结构`);
+    }
+  });
+  
+  return recommendations;
+}
+```
+
+### Step 4: 生成 README.md
+
+```javascript
+const readme = `# ${config.display_name}
+
+${config.description}
+
+## Quick Start
+
+### 触发词
+
+${config.triggers.map(t => `- "${t}"`).join('\n')}
+
+### 执行模式
+
+**${config.execution_mode === 'sequential' ? 'Sequential (顺序)' : 'Autonomous (自主)'}**
+
+${config.execution_mode === 'sequential' ?
+  `阶段按固定顺序执行：\n${config.sequential_config.phases.map((p, i) => 
+    `${i + 1}. ${p.name}`
+  ).join('\n')}` :
+  `动作由编排器动态选择：\n${config.autonomous_config.actions.map(a => 
+    `- ${a.name}: ${a.description || ''}`
+  ).join('\n')}`}
+
+## Usage
+
+\`\`\`
+# 直接触发
+用户: ${config.triggers[0]}
+
+# 或使用 Skill 名称
+用户: /skill ${config.skill_name}
+\`\`\`
+
+## Output
+
+- **格式**: ${config.output.format}
+- **位置**: \`${config.output.location}\`
+- **文件名**: \`${config.output.filename_pattern}\`
+
+## Directory Structure
+
+\`\`\`
+.claude/skills/${config.skill_name}/
+├── SKILL.md                    # 入口文件
+├── phases/                     # 执行阶段
+${config.execution_mode === 'sequential' ?
+  config.sequential_config.phases.map(p => `│   ├── ${p.id}.md`).join('\n') :
+  `│   ├── orchestrator.md
+│   ├── state-schema.md
+│   └── actions/
+${config.autonomous_config.actions.map(a => `│       ├── ${a.id}.md`).join('\n')}`}
+├── specs/                      # 规范文件
+│   ├── ${config.skill_name}-requirements.md
+│   ├── quality-standards.md
+${config.execution_mode === 'autonomous' ? '│   └── action-catalog.md' : ''}
+└── templates/                  # 模板文件
+    └── agent-base.md
+\`\`\`
+
+## Customization
+
+### 修改执行逻辑
+
+编辑 \`phases/\` 目录下的阶段文件。
+
+### 调整质量标准
+
+编辑 \`specs/quality-standards.md\`。
+
+### 添加新${config.execution_mode === 'sequential' ? '阶段' : '动作'}
+
+${config.execution_mode === 'sequential' ?
+  `1. 在 \`phases/\` 创建新的阶段文件 (如 \`03.5-new-step.md\`)
+2. 更新 SKILL.md 的执行流程` :
+  `1. 在 \`phases/actions/\` 创建新的动作文件
+2. 更新 \`specs/action-catalog.md\`
+3. 在 \`phases/orchestrator.md\` 添加选择逻辑`}
+
+## Related Documents
+
+- [设计规范](../_shared/SKILL-DESIGN-SPEC.md)
+- [执行模式规范](specs/../../../skill-generator/specs/execution-modes.md)
+
+---
+
+*Generated by skill-generator v1.0*
+`;
+
+Write(`${skillDir}/README.md`, readme);
+```
+
+### Step 5: 输出最终结果
+
+```javascript
+const finalResult = {
+  skill_name: config.skill_name,
+  skill_path: skillDir,
+  execution_mode: config.execution_mode,
+  
+  generated_files: [
+    'SKILL.md',
+    'README.md',
+    ...filesToCheck
+  ],
+  
+  validation: report.summary,
+  
+  next_steps: [
+    '1. 审阅生成的文件结构',
+    '2. 替换 TODO 占位符',
+    '3. 根据实际需求调整阶段逻辑',
+    '4. 测试 Skill 执行流程',
+    '5. 更新触发词和描述'
+  ]
+};
+
+console.log('=== Skill 生成完成 ===');
+console.log(`路径: ${skillDir}`);
+console.log(`模式: ${config.execution_mode}`);
+console.log(`状态: ${report.summary.status}`);
+console.log('');
+console.log('下一步:');
+finalResult.next_steps.forEach(s => console.log(s));
+```
+
+## Output
+
+- `{workDir}/validation-report.json` - 验证报告
+- `{skillDir}/README.md` - 使用说明
+
+## Completion
+
+Skill 生成流程完成。用户可以：
+
+1. 查看生成的 Skill 目录
+2. 根据验证报告修复问题
+3. 自定义执行逻辑
+4. 测试 Skill 功能