Forge 🔨 — Repair-Inspect loop orchestrator. Automated code repair with independent inspection, dependency-aware parallel execution, protected file guardrail...
---
name: forge
description: "Forge 🔨 — Repair-Inspect loop orchestrator. Automated code repair with independent inspection, dependency-aware parallel execution, protected file guardrails, and crash-recoverable state. Use when: fixing multiple code issues (bug fixes, review board recommendations, audit findings), need verified repairs with independent QA, want safe automated code changes with rollback protection. NOT for: simple one-line fixes, architecture decisions, prompt modifications."
---
# 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
```bash
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):
```python
# 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`:
```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:
| 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 |
don't have the plugin yet? install it then click "run inline in claude" again.