@winspan/claude-forge 8.53.2 → 8.54.3

package/docs/ruflo-learning-strategy.md

@@ -1,322 +0,0 @@
-# 让 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

@@ -1,83 +0,0 @@
-# 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

@@ -1,177 +0,0 @@
-# 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` - 验证脚本