Forge

Forge 🔨 — 维修-监理自动循环

Automated repair-inspect loop with state persistence, dependency analysis, and safety guardrails.

When to Use

• Multiple repair tasks from review board / audit / user instructions
• Need independent verification (not just "looks fixed")
• Want protected file safety + auto-commit on PASS

Quick Start

cd /path/to/project

# 1. Initialize
python3 ~/clawd/skills/forge/scripts/forge.py init

# 2. Add tasks
python3 forge.py add "修复空值处理" --criteria "空输入不崩溃" --priority P0
python3 forge.py add "清理废弃代码" --criteria "无import报错" --depends task-001

# 3. See execution plan
python3 forge.py plan

# 4. Run (outputs spawn instructions)
python3 forge.py run

# 5. Execute spawns, then run again to check results
python3 forge.py run   # checks results, auto-loops on FAIL

# 6. When all done
python3 forge.py summary

CLI Reference

How It Works

State Machine (per task)

pending → repairing → inspecting → done
                ↑          │
                └── fail ──┘   (auto-loop, max 5 rounds)

inspecting → needs_human  (pause, escalate)
inspecting → escalated    (>5 rounds)
repairing  → needs_human  (all BLOCKED)

Dependency-Aware Parallel Execution

Tasks without dependencies run in parallel. forge.py plan shows execution waves:

Wave 1: task-001, task-002, task-003  (并行)
Wave 2: task-004 ← task-001          (等task-001完成)

Safety Guardrails (3 layers)

1. Protected files — protected-files.txt in project root. Listed files cannot be modified by repair agents. Touching them → BLOCKED → NEEDS_HUMAN.
2. Pre-commit diff check — forge.py check detects: file deletions, protected file modifications, abnormally large changes.
3. Prompt constraints — Repair engineer prompt explicitly forbids deletions, protected files, cron changes.

Experience Accumulation

Each repair produces a repair_pattern with error classification and reusable solution templates. These are stored in forge-reflections.jsonl and the most recent 5 patterns are injected into future repair tasks as context.

Integration with AI Agents

When the agent receives repair tasks (from code review, audit, or user):

# 1. Init forge in project dir
exec("cd /path/to/project && python3 ~/clawd/skills/forge/scripts/forge.py init")

# 2. Add tasks
exec("python3 forge.py add 'Fix null handling in processor' --criteria 'No crash on empty input' --priority P0")

# 3. Run to get spawn instructions
exec("python3 forge.py run")
# → Script outputs spawn instructions

# 4. Execute spawns
sessions_spawn(task=read(task_file), label=label, model=model)

# 5. After spawn completes, run again
exec("python3 forge.py run")
# → Checks repair result → prepares inspector spawn
# → Or auto-loops on FAIL → prepares next repair spawn

# 6. On all PASS → git commit + notify

File Layout

forge/
├── SKILL.md                           # This file
├── scripts/
│   └── forge.py                       # Core orchestrator
├── references/
│   └── protocol.md                    # Full protocol documentation
└── assets/
    └── templates/
        ├── repair-engineer.md         # Repair agent role reference
        └── inspector.md              # Inspector role reference

Project-side files (created by forge)

project/
├── forge-state.json                   # State persistence (crash recovery)
├── forge-reflections.jsonl            # Project-specific experience (stays with project)
├── forge-output/                      # Task files and results
│   ├── task-001-repair-r1.task.md     # Repair spawn task
│   ├── task-001-repair-r1.json        # Repair result
│   ├── task-001-inspect-r1.task.md    # Inspect spawn task
│   └── task-001-inspect-r1.json       # Inspect result
└── protected-files.txt                # (optional) Protected file list

Experience: Two-Layer Architecture

forge/reflections/patterns.jsonl       # Universal patterns (cross-project, stays with skill)
project/forge-reflections.jsonl        # Project-specific patterns (stays with project)

• Universal layer (forge/reflections/patterns.jsonl): Abstract lessons stripped of file paths and project context. Auto-extracted from project patterns after each repair. Deduped by pattern_name. Injected into ALL future repairs across any project.
• Project layer ({project}/forge-reflections.jsonl): Full detail with file names, paths, project-specific context. Only injected when working on that project.
• Auto-extraction: After each repair, extract_universal_pattern() checks if the pattern is generalizable (not too many project-specific paths). If so, it's added to the universal layer with dedup.

Doc-Sync Check (文档同步检查)

Forge收尾时自动检查：修改的代码文件是否有关联文档需要同步更新。

工作原理

1. 优先运行 scripts/tools/doc-sync-checker.py --json（如果存在）
2. 回退到 references/doc-sync-manifest.yaml：交叉对比forge修改的文件与manifest中的authority→consumer映射

项目配置

在项目中创建 references/doc-sync-manifest.yaml：

facts:
  api_config:
    authority: src/config.py
    consumers:
      - docs/api-reference.md
      - docs/deployment-guide.md
    last_synced: 2026-03-01

Forge完成报告会显示：

📄 文档同步检查 — 2 个文档可能需要更新:
  ⚠️ docs/api-reference.md 可能需要同步更新（api_config 的权威源 src/config.py 已修改）

Configuration

Via init flags or forge-state.json config section: