Forge 🔨 Repair-Inspect Loop

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

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

When to Use

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

| Command | Description | |---------|-------------| | init --workdir DIR | Initialize forge session | | add "desc" --criteria "..." --depends task-001 --priority P0 | Add repair task | | plan | Show dependency graph + parallel execution waves | | run | Advance state machine (spawn or check results) | | status | Show current progress | | check | Pre-commit safety check (protected files, deletions) | | summary | Generate completion report | | reset | Clear state |

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)

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

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

工作原理

项目配置

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:

| Key | Default | Description | |-----|---------|-------------| | model | anthropic/claude-opus-4-6 | LLM model for agents | | max_rounds | 5 | Max repair-inspect cycles before escalation | | repair_timeout | 600 | Repair agent timeout (seconds) | | inspect_timeout | 300 | Inspector timeout (seconds) | | auto_commit | true | Auto git-commit on PASS |

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

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

| Key | Default | Description | |-----|---------|-------------| | model | anthropic/claude-opus-4-6 | LLM model for agents | | max_rounds | 5 | Max repair-inspect cycles before escalation | | repair_timeout | 600 | Repair agent timeout (seconds) | | inspect_timeout | 300 | Inspector timeout (seconds) | | auto_commit | true | Auto git-commit on PASS |