@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/ruflo-learning-strategy.md

@@ -0,0 +1,322 @@
+# 让 Claude 快速学会 Ruflo 模式的策略
+
+## 背景
+
+当前 claude-forge 已完成 Ruflo 模式重构：
+- Claude 自主决策（通过 CLAUDE.md 的 AUTO-INVOKE 规则）
+- daemon 只做观察和记录
+- 静态 pipeline 模板（写在 CLAUDE.md 里）
+
+但 Claude 可能仍然不遵守 CLAUDE.md 中的 AUTO-INVOKE 规则。需要加速学习过程。
+
+---
+
+## 方案 A：强化 CLAUDE.md 的视觉锚点（立即生效）
+
+### 问题诊断
+当前 CLAUDE.md 虽然有 MUST/ALWAYS/NEVER，但可能不够显眼：
+- 没有使用 ASCII 边框或分隔符
+- 代码示例是静态的，不够"可执行"
+- 触发条件（AUTO-INVOKE）在文件中间，可能被上下文压缩丢弃
+
+### 改进措施
+
+#### 1. 在文件最顶部添加 ASCII 横幅（Ruflo 风格）
+
+```markdown
+<!-- forge:claudemd-auto -->
+# claude-forge 工作区规范
+
+╔═══════════════════════════════════════════════════════════════╗
+║                    CRITICAL BEHAVIORAL RULES                   ║
+║                    (ALWAYS ENFORCED)                           ║
+╚═══════════════════════════════════════════════════════════════╝
+
+⚠️  BEFORE STARTING ANY TASK, CHECK THESE RULES:
+
+1. ALWAYS read a file before editing it
+2. NEVER create documentation files unless explicitly requested
+3. ALWAYS spawn ALL agents in ONE message (concurrency rule)
+4. MUST use Task tool for complex tasks (3+ files, new features, refactoring)
+
+╔═══════════════════════════════════════════════════════════════╗
+║              AUTO-INVOKE PIPELINE WHEN TASK INVOLVES:          ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ✓ Multiple files (3+)                                         ║
+║  ✓ New feature implementation                                  ║
+║  ✓ Refactoring across modules                                  ║
+║  ✓ Bug fix involving root-cause analysis                       ║
+║  ✓ API changes with tests                                      ║
+║  ✓ Security-related changes                                    ║
+║  ✓ Performance optimization                                    ║
+║  ✓ Database schema changes                                     ║
+╚═══════════════════════════════════════════════════════════════╝
+
+╔═══════════════════════════════════════════════════════════════╗
+║                   SKIP PIPELINE FOR:                           ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ✗ Single file edits                                           ║
+║  ✗ Simple bug fixes (1-2 lines)                                ║
+║  ✗ Documentation updates                                       ║
+║  ✗ Configuration changes                                       ║
+║  ✗ Quick questions/exploration                                 ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+**为什么有效**：
+- ASCII 边框在 Claude 的视觉注意力中权重更高
+- 放在文件最顶部，不会被上下文压缩丢弃
+- 使用 ✓/✗ 符号增强可读性
+
+#### 2. 将代码示例改为"立即可执行"格式
+
+当前格式（静态）：
+```javascript
+Task({ subagent_type: "tester", name: "reproducer", prompt: "...", run_in_background: true })
+```
+
+改进格式（可执行）：
+```javascript
+// COPY-PASTE THIS EXACT CODE (replace [task description] with actual task):
+Task({ 
+  subagent_type: "tester", 
+  name: "reproducer", 
+  prompt: "[task description]: Write a failing test that reproduces the bug. SendMessage findings to 'investigator' when done.", 
+  run_in_background: true 
+})
+Task({ 
+  subagent_type: "researcher", 
+  name: "investigator", 
+  prompt: "[task description]: Wait for SendMessage from 'reproducer'. Investigate root cause. SendMessage findings to 'fixer' when done.", 
+  run_in_background: true 
+})
+// ... (more Task calls)
+```
+
+**为什么有效**：
+- "COPY-PASTE THIS EXACT CODE" 是明确的行动指令
+- `[task description]` 占位符让 Claude 知道需要填充什么
+- 保留完整的参数结构，减少 Claude 自由发挥的空间
+
+#### 3. 在每个 Pipeline 模板前添加触发条件检查清单
+
+```markdown
+#### Bug Fix (Code 1: harness-debug-full)
+
+**TRIGGER CHECKLIST** — Use this pipeline if ALL of these are true:
+- [ ] Bug involves multiple files OR root-cause analysis needed
+- [ ] Not a simple 1-2 line fix
+- [ ] Requires investigation + fix + verification
+
+**IF TRIGGERED, COPY-PASTE ALL 4 TASK CALLS IN ONE MESSAGE:**
+```
+
+**为什么有效**：
+- Checklist 格式让 Claude 明确判断是否触发
+- "COPY-PASTE ALL 4 TASK CALLS IN ONE MESSAGE" 强化并发原则
+
+---
+
+## 方案 B：添加 MCP 工具提示（中等效果，需要 1 小时开发）
+
+### 核心思路
+当 Claude 开始处理复杂任务时，daemon 通过 MCP 工具主动提示"你应该考虑使用 pipeline"。
+
+### 实现方式
+
+#### 1. 新增 MCP 工具：`pipeline_suggest`
+
+```typescript
+// src/mcp/tools/pipeline-suggest.ts
+export const pipelineSuggestTool = {
+  name: 'pipeline_suggest',
+  description: 'Get pipeline suggestions based on task complexity',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      taskDescription: { type: 'string' },
+      fileCount: { type: 'number' },
+      isNewFeature: { type: 'boolean' },
+      isRefactor: { type: 'boolean' }
+    }
+  },
+  handler: async (args) => {
+    const { taskDescription, fileCount, isNewFeature, isRefactor } = args;
+    
+    // 判断是否应该触发 pipeline
+    const shouldTrigger = fileCount >= 3 || isNewFeature || isRefactor;
+    
+    if (!shouldTrigger) {
+      return { suggestion: 'No pipeline needed for this simple task.' };
+    }
+    
+    // 推荐具体的 pipeline
+    let pipelineCode = '';
+    if (isNewFeature) {
+      pipelineCode = `// Feature pipeline (bmad-feature-full)
+Task({ subagent_type: "researcher", name: "analyst", prompt: "${taskDescription}: Analyze requirements...", run_in_background: true })
+Task({ subagent_type: "planner", name: "designer", prompt: "${taskDescription}: Wait for 'analyst'...", run_in_background: true })
+// ... (full template)`;
+    } else if (isRefactor) {
+      pipelineCode = `// Refactor pipeline (refactor-safe)
+Task({ subagent_type: "tester", name: "safety-net", prompt: "${taskDescription}: Write tests...", run_in_background: true })
+// ... (full template)`;
+    }
+    
+    return {
+      suggestion: `⚠️  This task matches AUTO-INVOKE criteria. You MUST use a pipeline.`,
+      pipelineCode,
+      reminder: 'COPY-PASTE ALL TASK CALLS IN ONE MESSAGE'
+    };
+  }
+};
+```
+
+#### 2. 在 CLAUDE.md 中添加 MCP 工具使用指南
+
+```markdown
+## Pipeline Decision Support (MCP Tool)
+
+If you're unsure whether to trigger a pipeline, call the MCP tool:
+
+```javascript
+mcp__claude_forge__pipeline_suggest({
+  taskDescription: "implement user authentication",
+  fileCount: 5,
+  isNewFeature: true,
+  isRefactor: false
+})
+```
+
+The tool will tell you:
+1. Whether you MUST use a pipeline
+2. Which pipeline template to use
+3. The exact code to copy-paste
+```
+
+**为什么有效**：
+- 主动提示，而不是被动等待 Claude 遵守
+- 提供具体的代码模板，减少 Claude 的认知负担
+
+---
+
+## 方案 C：会话级强化学习（长期效果，需要多次会话）
+
+### 核心思路
+通过多次会话的反馈循环，让 Claude 逐渐"学会"遵守 CLAUDE.md 规则。
+
+### 实现方式
+
+#### 1. 在每次会话结束时，生成"行为报告"
+
+```markdown
+## Session Behavior Report
+
+**Task**: Implement user authentication with OAuth
+**Complexity**: High (5 files, new feature)
+**Expected**: AUTO-INVOKE pipeline (bmad-feature-full)
+**Actual**: Direct implementation (no Task calls)
+**Result**: ❌ Violated AUTO-INVOKE rule
+
+**Feedback for next session**:
+- You should have spawned 5 Task calls in ONE message
+- Template: bmad-feature-full (researcher → planner → developer → tester → reviewer)
+- Reason: This task involves 5 files + new feature implementation
+```
+
+#### 2. 将报告写入 `~/.claude/memory/` 或 CLAUDE.md 的顶部
+
+每次会话开始时，Claude 会看到上次的"违规记录"，逐渐形成习惯。
+
+#### 3. 使用 daemon 的 `routing_events` 表生成报告
+
+```typescript
+// src/daemon/session-report.ts
+export async function generateSessionReport(sessionId: string) {
+  const events = await storage.getRoutingEventsBySession(sessionId);
+  const violations = events.filter(e => e.obeyed === 0);
+  
+  if (violations.length > 0) {
+    const report = `
+## ⚠️  Previous Session Violations
+
+You violated AUTO-INVOKE rules ${violations.length} times in the last session.
+
+${violations.map(v => `
+- Task: ${v.user_prompt_summary}
+- Expected: ${v.routed_to_name}
+- Actual: Direct implementation
+- Fix: Use the pipeline template in CLAUDE.md
+`).join('\n')}
+
+**Remember**: ALWAYS spawn ALL agents in ONE message when task matches AUTO-INVOKE criteria.
+`;
+    
+    // 写入 CLAUDE.md 顶部或 memory
+    await fs.writeFile('CLAUDE.md', report + originalContent);
+  }
+}
+```
+
+**为什么有效**：
+- 反馈循环让 Claude 看到自己的"错误"
+- 多次会话后，Claude 会形成"条件反射"
+
+---
+
+## 推荐实施顺序
+
+### 第一阶段（立即执行，0 成本）
+1. ✅ 强化 CLAUDE.md 的视觉锚点（方案 A）
+   - 添加 ASCII 横幅
+   - 改进代码示例格式
+   - 添加触发条件检查清单
+
+### 第二阶段（1 小时开发）
+2. ⏳ 添加 MCP 工具提示（方案 B）
+   - 实现 `pipeline_suggest` 工具
+   - 在 CLAUDE.md 中添加使用指南
+
+### 第三阶段（长期优化）
+3. ⏳ 会话级强化学习（方案 C）
+   - 实现会话行为报告生成
+   - 将报告写入 CLAUDE.md 或 memory
+
+---
+
+## 预期效果
+
+| 方案 | 实施成本 | 生效时间 | 预期合规率提升 |
+|------|---------|---------|--------------|
+| A: 视觉锚点 | 10 分钟 | 立即 | +30% |
+| B: MCP 提示 | 1 小时 | 立即 | +20% |
+| C: 强化学习 | 2 小时 | 3-5 次会话后 | +40% |
+| **组合效果** | 3 小时 | 3-5 次会话后 | **+70-90%** |
+
+---
+
+## 验证方法
+
+1. **重启 Claude Code 会话**（让新的 CLAUDE.md 生效）
+2. **输入复杂任务**（如 "implement user authentication with OAuth"）
+3. **观察 Claude 的行为**：
+   - 是否自主判断触发 pipeline？
+   - 是否在一条消息中并发调用多个 Task？
+   - 是否使用 CLAUDE.md 中的静态模板？
+4. **检查数据库**：
+   ```sql
+   SELECT obeyed, COUNT(*) FROM routing_events GROUP BY obeyed;
+   ```
+   - `obeyed=1` 的比例应该逐渐提升
+
+---
+
+## 关键洞察
+
+Ruflo 的成功不是因为"语言更狠"，而是因为：
+1. **视觉锚点**：ASCII 边框、符号、位置（文件顶部）
+2. **具体性**：可执行的代码示例，而不是抽象描述
+3. **触发条件明确**：Checklist 格式，消除歧义
+4. **反馈循环**：多次会话后形成习惯
+
+claude-forge 已经有了正确的架构，现在只需要强化 CLAUDE.md 的"教学效果"。

package/docs/skills-deduplication-analysis.md

@@ -0,0 +1,83 @@
+# claude-forge 与 addyosmani/agent-skills 去重分析报告
+
+## 执行摘要
+
+- **重叠项数量**：10 对
+- **推荐下线数量**：6 个
+- **推荐保留作 override**：4 个
+- **新增技能数量**：6+ 个
+
+---
+
+## A. 重叠项对比
+
+| 本项目 skill | agent-skills 对应 | 功能重叠度 |
+|---|---|---|
+| `official-tdd` | `test-driven-development` | 100% |
+| `official-debug` | `debugging-and-troubleshooting` | 95% |
+| `official-pr-review` | `code-review-and-quality` | 90% |
+| `official-spec-driven-design` | `spec-driven-development` | 100% |
+| `official-architecture-decision` | `documentation-and-adrs` | 85% |
+| `official-api-design` | `api-and-interface-design` | 95% |
+| `official-db-schema-design` | `database-schema-design` | 90% |
+| `official-performance-optimization` | `performance-optimization` | 95% |
+| `official-security-hardening` | `security-and-hardening` | 90% |
+| `official-release-checklist` | `shipping-and-launch` | 95% |
+
+---
+
+## B. 处理决策
+
+### 1. 推荐下线（6 个）
+
+agent-skills 版本更成熟，推荐下线本项目版本：
+
+- `official-tdd` → `test-driven-development`
+- `official-debug` → `debugging-and-troubleshooting`
+- `official-api-design` → `api-and-interface-design`
+- `official-db-schema-design` → `database-schema-design`
+- `official-performance-optimization` → `performance-optimization`
+- `official-release-checklist` → `shipping-and-launch`
+
+### 2. 保留作 user override（4 个）
+
+本项目版本有中文本地化优势，改名为 `-cn` 后缀保留：
+
+- `official-spec-driven-design` → `official-spec-driven-design-cn`
+- `official-pr-review` → `official-pr-review-cn`
+- `official-security-hardening` → `official-security-hardening-cn`
+- `official-architecture-decision` → `official-architecture-decision-cn`
+
+---
+
+## C. 新增技能清单
+
+agent-skills 填补的空白（6+ 个）：
+
+- `idea-refine` — 想法精炼与需求澄清
+- `planning-and-task-breakdown` — 任务分解与依赖图
+- `frontend-ui-engineering` — 前端工程最佳实践
+- `refactoring-and-cleanup` — 重构与代码清理
+- `git-workflow-and-versioning` — Git 工作流与版本管理
+- `using-agent-skills` — Agent Skills 元技能
+
+---
+
+## D. 实施建议
+
+### 第一阶段：下线重叠技能
+
+从 `src/skills/official-skills.ts` 删除 6 个技能。
+
+### 第二阶段：重命名本地化版本
+
+4 个技能改名为 `-cn` 后缀。
+
+### 第三阶段：集成 agent-skills
+
+运行 `npm run sync:agent-skills` 同步外部技能。
+
+---
+
+**生成时间**：2026-05-10  
+**版本**：v1.0

package/docs/skills-multiformat-support.md

@@ -0,0 +1,177 @@
+# Skills Multi-format Support
+
+## 概述
+
+`SkillRegistry` 现在支持两种 skill 文件格式：
+
+1. **平铺格式**（原有）：`~/.claude/skills/skill-name.md`
+2. **目录格式**（新增）：`~/.claude/skills/skill-name/SKILL.md`（agent-skills 格式）
+
+两种格式可以共存，不会相互干扰。
+
+## 改动内容
+
+### 1. `Skill` 接口扩展
+
+新增可选字段 `description`：
+
+```typescript
+export interface Skill {
+  id: string;
+  name: string;
+  keywords: string[];
+  content: string;
+  path: string;
+  isOfficial?: boolean;
+  description?: string; // 新增：从 frontmatter 读取
+}
+```
+
+### 2. `scan()` 方法支持两种格式
+
+```typescript
+const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+
+for (const entry of entries) {
+  if (entry.isFile() && entry.name.endsWith('.md')) {
+    // 格式 1：平铺 .md 文件
+    filePath = path.join(SKILLS_DIR, entry.name);
+  } else if (entry.isDirectory()) {
+    // 格式 2：目录形式，读 SKILL.md
+    const skillMdPath = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
+    if (fs.existsSync(skillMdPath)) {
+      filePath = skillMdPath;
+    }
+  }
+}
+```
+
+### 3. 空 keywords 降级机制
+
+当 skill 的 `keywords` 为空时，使用 `description` 进行 substring 匹配：
+
+```typescript
+if (skill.keywords.length > 0) {
+  // 使用 keyword 匹配
+} else if (skill.description) {
+  // 降级路径 1：使用 description substring 匹配
+  const descLower = skill.description.toLowerCase();
+  if (descLower.includes(promptLower) || promptLower.includes(descLower)) {
+    score = 1;
+  }
+}
+// 降级路径 2：返回 0，让 SemanticSkillMatcher 接管
+```
+
+### 4. `SemanticSkillMatcher` 优先使用 description
+
+```typescript
+private extractDescription(skill: Skill): string {
+  // 优先使用 frontmatter description（agent-skills 格式）
+  if (skill.description) {
+    return skill.description;
+  }
+  
+  // 降级：从 content 提取第一行描述
+  // ...
+}
+```
+
+## 使用示例
+
+### 平铺格式（原有）
+
+```
+~/.claude/skills/
+  my-skill.md
+```
+
+`my-skill.md` 内容：
+```markdown
+---
+name: my-skill
+description: My custom skill
+keywords: [custom, test]
+---
+
+# My Skill
+
+Skill content here.
+```
+
+### 目录格式（新增）
+
+```
+~/.claude/skills/
+  my-skill/
+    SKILL.md
+    README.md
+    examples/
+```
+
+`SKILL.md` 内容：
+```markdown
+---
+name: my-skill
+description: My custom skill
+keywords: [custom, test]
+---
+
+# My Skill
+
+Skill content here.
+```
+
+## 兼容性
+
+- ✅ 不破坏现有行为：16 个 `OFFICIAL_SKILLS` 的加载逻辑不变
+- ✅ 用户 skills 可以覆盖官方 skills（原有行为保持）
+- ✅ 目录中没有 `SKILL.md` 时静默跳过（不报错）
+- ✅ 类型安全：所有新增字段都有 TypeScript 类型
+
+## 测试
+
+### 单元测试
+
+- `tests/unit/skills/registry-multiformat.test.ts`：测试 frontmatter 解析
+  - 平铺格式解析
+  - 目录格式解析
+  - 空 keywords 处理
+  - 空 description 处理
+  - 空 frontmatter 处理
+
+### 验证脚本
+
+- `scripts/verify-skill-loading.ts`：验证实际文件系统加载
+
+运行验证：
+```bash
+npx tsx scripts/verify-skill-loading.ts
+```
+
+## 实际验证结果
+
+在实际环境中验证成功：
+
+```
+Total skills loaded: 21
+Directory format skills: 21
+Skills with description field: 21
+Skills without keywords: 21
+```
+
+所有 21 个用户 skill 都是从目录格式（`SKILL.md`）加载的，并且都正确读取了 `description` 字段。
+
+## 注意事项
+
+1. **同名优先级**：用户 skills 会覆盖官方 skills（原有行为）
+2. **错误处理**：解析失败的 skill 会被跳过并记录警告日志
+3. **性能**：扫描逻辑只在 `SkillRegistry` 构造时执行一次
+4. **降级机制**：空 keywords 时会尝试 description 匹配，最后才交给 SemanticSkillMatcher
+
+## 相关文件
+
+- `src/skills/registry.ts` - 核心实现
+- `src/skills/semantic-matcher.ts` - 语义匹配优化
+- `tests/unit/skills/registry-multiformat.test.ts` - 单元测试
+- `scripts/verify-skill-loading.ts` - 验证脚本