malakhov-dmitrii/forge

# Forge **矿石进，钢出。** 铁匠不会责怪矿石。它熔炼、塑形、回火、淬火——直到产出的东西拥有锋芒。Forge 对代码做同样的事情：接受任何任务，无论多么原始，通过规划门、独立审查和验证执行进行加工，直到结果被证明有效。 Claude Code 插件。三项技能：规划流水线、文档卫生和代码卫生。支持从每次运行中学习的持久化记忆。 ``` "fix the auth bug" → research → plan → 2 independent reviews → TDD execute → independent verify → done ``` ## 安装 ``` git clone https://github.com/malakhov-dmitrii/forge.git ~/.claude/plugins/forge bun run ~/.claude/plugins/forge/scripts/install.mjs ``` 安装程序会创建技能符号链接，在 `settings.json` 中注册钩子，并初始化知识数据库。 ## 技能 ### `/forge` — 规划 + 执行 + 验证 主流水线。将任务从想法推进到已验证的实现。 ``` /forge "add rate limiting to the API" — plan → execute → verify /forge --full "migrate to new auth system" — deeper research + spike /forge --discuss "improve engagement" — clarify vague input first /forge --plan-only — stop after final plan ``` 两台机器按顺序工作： **Plan Forge** — 精炼循环。搜索项目的隐患、过往计划和架构文档。探测高风险假设。从不同的 AI 模型获取第二意见。循环直到两位独立审查者发现零个问题。最多 5 次迭代。 **Verification Chain** — 两名从未见过执行器输出的代理独立验证每一个验收标准。审计员抽查 30-50% 的证据。缺口会反馈给执行阶段。 **铁律**（硬编码，系统无法覆盖）： - 每个计划至少 2 次独立审查 - 规划者 ≠ 审查者。不共享上下文。 - 流水线配置是项目范围的。不会在项目之间自动传播。 ### `/docs-refresh` — 文档卫生 审计所有项目文档的新鲜度。删除已失效的内容，更新发生偏移的部分，压缩臃肿的内容。同时作为 Forge 的最终阶段运行。 ``` /docs-refresh — full audit: memory, CLAUDE.md, lessons, references /docs-refresh --scan-only — report only, no changes /docs-refresh --memory-only — scope to memory files ``` ### `/code-hygiene` — 代码库健康分析 运行静态分析工具，解释结果，映射架构，评估测试质量。将结构化结果存储在 `.omc/hygiene/` 中以便长期跟踪。 **工具优先方法**：运行 tsc、scc、semgrep、knip、jscpd、dependency-cruiser，然后解释 JSON 输出。生成健康分数（0-100）、按严重性分类的发现（P0-P3）、包含 Mermaid 图表的架构概览，以及测试质量分析。P0/P1 发现可以转化为待处理的 Forge 任务以便重构。 ## Forge 智能 每次 Forge 运行都会写入 SQLite 数据库（`.omc/forge.db`）。系统从自身历史中学习。 **跟踪内容：** - 每次迭代的门结果（哪些审查失败、发现了什么） - 尖峰缓存（带有 TTL 的已确认/反驳的假设） - 每个系统的风险分数（自动从过去的失败中聚合） - 共同故障模式（哪些系统倾向于一起出错） **实现的功能：** - `--park` / `--resume` — 保存工作，在新会话中继续 - `--spawn "子任务"` — 创建带有依赖跟踪的子 Forge - 上下文窗口重置时保留状态 - PRECEDENT 阶段在规划前查询历史运行（“上次这个系统需要 3 次迭代”） **跨项目知识** 存储在 `~/.forge/global.db` 中——适用于所有工具的已验证事实。关于外部工具的尖峰会自动提升。 模式已版本化（`PRAGMA user_version`）——未来更新会自动迁移。 ## 工作原理 ### 计划 Forge ``` PRECEDENT ── gotchas, past plans, forge.db risk scores, cached spikes │ RESEARCH ─── read every file, grep all usages, spike anything testable in <5 min │ CHALLENGE ── second opinion on approach (codex CLI or fresh opus agent) │ PLAN ─────── concrete steps with acceptance criteria (static + unit + e2e) │ REVIEW ───── 2+ binary gates: Skeptic (mirages) + Second Opinion (production failures) │ └── fail? → fix specific issue → re-run failed gate only → max 5 iterations ``` ### 验证链 ``` Layer 0: Static ── tsc, semgrep, lsp diagnostics Layer 1: Unit ──── test suite on changed modules Layer 2: E2E ───── trigger real flows, verify actual behavior Layer 3: Agents ── Evidence Collector (sonnet) → Auditor (opus), no executor access ``` ### 文档刷新（最终阶段） 验证完成后：检查本次工作是否产生新的隐患、使旧文档过时，或发现值得记录的模式。自动从永久尖峰创建课程文件，从重复的门审查结果中添加 CLAUDE.md 隐患。 ## Forge 命令 ``` /forge "task" — new forge, start pipeline /forge --park [reason] — save state to forge.db /forge --resume [slug] — continue from where you left off /forge --spawn "sub-task" — child forge, optionally blocks parent /forge --switch [slug] — park current + resume another /forge --list — all forges with status /forge --complete — mark done, record lesson, unblock dependents /forge --abandon [reason] — mark abandoned, preserve context ``` ## 项目结构 ``` skills/ forge/SKILL.md # Planning pipeline specification docs-refresh/SKILL.md # Documentation hygiene hooks/ forge-schema.mjs # SQLite schema, migrations, triggers forge-crud.mjs # CRUD operations, risk aggregation forge-hooks.mjs # SessionStart/End/PreCompact handlers forge-global.mjs # Cross-project knowledge DB agents/ skeptic.md # Mirage hunter — verifies claims against reality evidence-collector.md # Independent verification, no executor access auditor.md # Spot-checks evidence, catches gaps researcher.md # Deep codebase investigation planner.md # Concrete, testable plans ... # 13 agents total commands/ forge.md # Main command forge-setup.md # One-time project setup templates/ semgrep-starter.yml # Starter gotcha rules docs-structure.md # Knowledge vault template scripts/ install.mjs # Symlinks, hook registration, DB init ``` ## HUD 集成 当 Forge 活跃时，终端状态栏会显示进度： ``` forge:REV·2 S✓I✓2✗ +1parked — Review iter 2, Skeptic pass, Integration pass, 2nd fail, 1 parked forge:EXE 4/6 — Execute phase, 4 of 6 steps done forge:VER — Verification chain running ``` ## 哲学 1. **矿石进，钢出。** 系统精炼而不拒绝。模糊的输入会被澄清。错误的假设会被探测。薄弱的计划会被锤炼。 2. **独立验证。** 塑造金属的代理不能测试刀刃。独立的代理，不共享上下文。 3. **先尖峰，后理论。** 五分钟的测试胜过三十分钟的辩论。 4. **Forge 有记忆。** 每次运行都教会下一次。风险分数、缓存的尖峰、共同故障模式——知识会累积。 5. **铁律成立。** 每个计划都有两次独立审查。系统可以在边界内优化，但不能移除自身的安全检查。 ## 要求 - [Bun](https://bun.sh) — 运行时（用于 hooks 中的 bun:sqlite） - [Claude Code](https://claude.ai/code) — AI 编码助手 可选： ``` brew install semgrep scc # static analysis + complexity metrics ``` [Codegen CLI](https://github.com/openai/codex) 推荐用于跨模型的第二意见。 ## 许可证 MIT — [Dmitrii Malakhov](https://github.com/malakhov-dmitrii)

标签：AI 编码辅助, Claude Code 插件, Forge, Ironclad Planning, Ruby, SEO: AI 编码插件, SEO: TDD 工具, SEO: 代码质量工具, SEO: 项目规划, TDD, XML 请求, 代码卫生, 安全开发, 审核管道, 审计追踪, 开源框架, 执行器隔离验证, 持久化记忆, 持续集成, 数据可视化, 文档卫生, 独立评审, 独立验证, 知识库, 自定义脚本, 规划管道, 项目规划, 黑smith 隐喻