{
  "schemaVersion": "1.0",
  "item": {
    "slug": "forge-loop",
    "name": "Forge 🔨 Repair-Inspect Loop",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/melody1015/forge-loop",
    "canonicalUrl": "https://clawhub.ai/melody1015/forge-loop",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/forge-loop",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=forge-loop",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "assets/templates/inspector.md",
      "assets/templates/repair-engineer.md",
      "references/protocol.md",
      "reflections/README.md",
      "scripts/forge.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/forge-loop"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/forge-loop",
    "agentPageUrl": "https://openagent3.xyz/skills/forge-loop/agent",
    "manifestUrl": "https://openagent3.xyz/skills/forge-loop/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/forge-loop/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Forge 🔨 — 维修-监理自动循环",
        "body": "Automated repair-inspect loop with state persistence, dependency analysis, and safety guardrails."
      },
      {
        "title": "When to Use",
        "body": "Multiple repair tasks from review board / audit / user instructions\nNeed independent verification (not just \"looks fixed\")\nWant protected file safety + auto-commit on PASS"
      },
      {
        "title": "Quick Start",
        "body": "cd /path/to/project\n\n# 1. Initialize\npython3 ~/clawd/skills/forge/scripts/forge.py init\n\n# 2. Add tasks\npython3 forge.py add \"修复空值处理\" --criteria \"空输入不崩溃\" --priority P0\npython3 forge.py add \"清理废弃代码\" --criteria \"无import报错\" --depends task-001\n\n# 3. See execution plan\npython3 forge.py plan\n\n# 4. Run (outputs spawn instructions)\npython3 forge.py run\n\n# 5. Execute spawns, then run again to check results\npython3 forge.py run   # checks results, auto-loops on FAIL\n\n# 6. When all done\npython3 forge.py summary"
      },
      {
        "title": "CLI Reference",
        "body": "CommandDescriptioninit --workdir DIRInitialize forge sessionadd \"desc\" --criteria \"...\" --depends task-001 --priority P0Add repair taskplanShow dependency graph + parallel execution wavesrunAdvance state machine (spawn or check results)statusShow current progresscheckPre-commit safety check (protected files, deletions)summaryGenerate completion reportresetClear state"
      },
      {
        "title": "State Machine (per task)",
        "body": "pending → repairing → inspecting → done\n                ↑          │\n                └── fail ──┘   (auto-loop, max 5 rounds)\n\ninspecting → needs_human  (pause, escalate)\ninspecting → escalated    (>5 rounds)\nrepairing  → needs_human  (all BLOCKED)"
      },
      {
        "title": "Dependency-Aware Parallel Execution",
        "body": "Tasks without dependencies run in parallel. forge.py plan shows execution waves:\n\nWave 1: task-001, task-002, task-003  (并行)\nWave 2: task-004 ← task-001          (等task-001完成)"
      },
      {
        "title": "Safety Guardrails (3 layers)",
        "body": "Protected files — protected-files.txt in project root. Listed files cannot be modified by repair agents. Touching them → BLOCKED → NEEDS_HUMAN.\nPre-commit diff check — forge.py check detects: file deletions, protected file modifications, abnormally large changes.\nPrompt constraints — Repair engineer prompt explicitly forbids deletions, protected files, cron changes."
      },
      {
        "title": "Experience Accumulation",
        "body": "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."
      },
      {
        "title": "Integration with AI Agents",
        "body": "When the agent receives repair tasks (from code review, audit, or user):\n\n# 1. Init forge in project dir\nexec(\"cd /path/to/project && python3 ~/clawd/skills/forge/scripts/forge.py init\")\n\n# 2. Add tasks\nexec(\"python3 forge.py add 'Fix null handling in processor' --criteria 'No crash on empty input' --priority P0\")\n\n# 3. Run to get spawn instructions\nexec(\"python3 forge.py run\")\n# → Script outputs spawn instructions\n\n# 4. Execute spawns\nsessions_spawn(task=read(task_file), label=label, model=model)\n\n# 5. After spawn completes, run again\nexec(\"python3 forge.py run\")\n# → Checks repair result → prepares inspector spawn\n# → Or auto-loops on FAIL → prepares next repair spawn\n\n# 6. On all PASS → git commit + notify"
      },
      {
        "title": "File Layout",
        "body": "forge/\n├── SKILL.md                           # This file\n├── scripts/\n│   └── forge.py                       # Core orchestrator\n├── references/\n│   └── protocol.md                    # Full protocol documentation\n└── assets/\n    └── templates/\n        ├── repair-engineer.md         # Repair agent role reference\n        └── inspector.md              # Inspector role reference"
      },
      {
        "title": "Project-side files (created by forge)",
        "body": "project/\n├── forge-state.json                   # State persistence (crash recovery)\n├── forge-reflections.jsonl            # Project-specific experience (stays with project)\n├── forge-output/                      # Task files and results\n│   ├── task-001-repair-r1.task.md     # Repair spawn task\n│   ├── task-001-repair-r1.json        # Repair result\n│   ├── task-001-inspect-r1.task.md    # Inspect spawn task\n│   └── task-001-inspect-r1.json       # Inspect result\n└── protected-files.txt                # (optional) Protected file list"
      },
      {
        "title": "Experience: Two-Layer Architecture",
        "body": "forge/reflections/patterns.jsonl       # Universal patterns (cross-project, stays with skill)\nproject/forge-reflections.jsonl        # Project-specific patterns (stays with project)\n\nUniversal 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.\nProject layer ({project}/forge-reflections.jsonl): Full detail with file names, paths, project-specific context. Only injected when working on that project.\nAuto-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."
      },
      {
        "title": "Doc-Sync Check (文档同步检查)",
        "body": "Forge收尾时自动检查：修改的代码文件是否有关联文档需要同步更新。"
      },
      {
        "title": "工作原理",
        "body": "优先运行 scripts/tools/doc-sync-checker.py --json（如果存在）\n回退到 references/doc-sync-manifest.yaml：交叉对比forge修改的文件与manifest中的authority→consumer映射"
      },
      {
        "title": "项目配置",
        "body": "在项目中创建 references/doc-sync-manifest.yaml：\n\nfacts:\n  api_config:\n    authority: src/config.py\n    consumers:\n      - docs/api-reference.md\n      - docs/deployment-guide.md\n    last_synced: 2026-03-01\n\nForge完成报告会显示：\n\n📄 文档同步检查 — 2 个文档可能需要更新:\n  ⚠️ docs/api-reference.md 可能需要同步更新（api_config 的权威源 src/config.py 已修改）"
      },
      {
        "title": "Configuration",
        "body": "Via init flags or forge-state.json config section:\n\nKeyDefaultDescriptionmodelanthropic/claude-opus-4-6LLM model for agentsmax_rounds5Max repair-inspect cycles before escalationrepair_timeout600Repair agent timeout (seconds)inspect_timeout300Inspector timeout (seconds)auto_committrueAuto git-commit on PASS"
      }
    ],
    "body": "Forge 🔨 — 维修-监理自动循环\n\nAutomated repair-inspect loop with state persistence, dependency analysis, and safety guardrails.\n\nWhen to Use\nMultiple repair tasks from review board / audit / user instructions\nNeed independent verification (not just \"looks fixed\")\nWant protected file safety + auto-commit on PASS\nQuick Start\ncd /path/to/project\n\n# 1. Initialize\npython3 ~/clawd/skills/forge/scripts/forge.py init\n\n# 2. Add tasks\npython3 forge.py add \"修复空值处理\" --criteria \"空输入不崩溃\" --priority P0\npython3 forge.py add \"清理废弃代码\" --criteria \"无import报错\" --depends task-001\n\n# 3. See execution plan\npython3 forge.py plan\n\n# 4. Run (outputs spawn instructions)\npython3 forge.py run\n\n# 5. Execute spawns, then run again to check results\npython3 forge.py run   # checks results, auto-loops on FAIL\n\n# 6. When all done\npython3 forge.py summary\n\nCLI Reference\nCommand\tDescription\ninit --workdir DIR\tInitialize forge session\nadd \"desc\" --criteria \"...\" --depends task-001 --priority P0\tAdd repair task\nplan\tShow dependency graph + parallel execution waves\nrun\tAdvance state machine (spawn or check results)\nstatus\tShow current progress\ncheck\tPre-commit safety check (protected files, deletions)\nsummary\tGenerate completion report\nreset\tClear state\nHow It Works\nState Machine (per task)\npending → repairing → inspecting → done\n                ↑          │\n                └── fail ──┘   (auto-loop, max 5 rounds)\n\ninspecting → needs_human  (pause, escalate)\ninspecting → escalated    (>5 rounds)\nrepairing  → needs_human  (all BLOCKED)\n\nDependency-Aware Parallel Execution\n\nTasks without dependencies run in parallel. forge.py plan shows execution waves:\n\nWave 1: task-001, task-002, task-003  (并行)\nWave 2: task-004 ← task-001          (等task-001完成)\n\nSafety Guardrails (3 layers)\nProtected files — protected-files.txt in project root. Listed files cannot be modified by repair agents. Touching them → BLOCKED → NEEDS_HUMAN.\nPre-commit diff check — forge.py check detects: file deletions, protected file modifications, abnormally large changes.\nPrompt constraints — Repair engineer prompt explicitly forbids deletions, protected files, cron changes.\nExperience Accumulation\n\nEach 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.\n\nIntegration with AI Agents\n\nWhen the agent receives repair tasks (from code review, audit, or user):\n\n# 1. Init forge in project dir\nexec(\"cd /path/to/project && python3 ~/clawd/skills/forge/scripts/forge.py init\")\n\n# 2. Add tasks\nexec(\"python3 forge.py add 'Fix null handling in processor' --criteria 'No crash on empty input' --priority P0\")\n\n# 3. Run to get spawn instructions\nexec(\"python3 forge.py run\")\n# → Script outputs spawn instructions\n\n# 4. Execute spawns\nsessions_spawn(task=read(task_file), label=label, model=model)\n\n# 5. After spawn completes, run again\nexec(\"python3 forge.py run\")\n# → Checks repair result → prepares inspector spawn\n# → Or auto-loops on FAIL → prepares next repair spawn\n\n# 6. On all PASS → git commit + notify\n\nFile Layout\nforge/\n├── SKILL.md                           # This file\n├── scripts/\n│   └── forge.py                       # Core orchestrator\n├── references/\n│   └── protocol.md                    # Full protocol documentation\n└── assets/\n    └── templates/\n        ├── repair-engineer.md         # Repair agent role reference\n        └── inspector.md              # Inspector role reference\n\nProject-side files (created by forge)\nproject/\n├── forge-state.json                   # State persistence (crash recovery)\n├── forge-reflections.jsonl            # Project-specific experience (stays with project)\n├── forge-output/                      # Task files and results\n│   ├── task-001-repair-r1.task.md     # Repair spawn task\n│   ├── task-001-repair-r1.json        # Repair result\n│   ├── task-001-inspect-r1.task.md    # Inspect spawn task\n│   └── task-001-inspect-r1.json       # Inspect result\n└── protected-files.txt                # (optional) Protected file list\n\nExperience: Two-Layer Architecture\nforge/reflections/patterns.jsonl       # Universal patterns (cross-project, stays with skill)\nproject/forge-reflections.jsonl        # Project-specific patterns (stays with project)\n\nUniversal 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.\nProject layer ({project}/forge-reflections.jsonl): Full detail with file names, paths, project-specific context. Only injected when working on that project.\nAuto-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.\nDoc-Sync Check (文档同步检查)\n\nForge收尾时自动检查：修改的代码文件是否有关联文档需要同步更新。\n\n工作原理\n优先运行 scripts/tools/doc-sync-checker.py --json（如果存在）\n回退到 references/doc-sync-manifest.yaml：交叉对比forge修改的文件与manifest中的authority→consumer映射\n项目配置\n\n在项目中创建 references/doc-sync-manifest.yaml：\n\nfacts:\n  api_config:\n    authority: src/config.py\n    consumers:\n      - docs/api-reference.md\n      - docs/deployment-guide.md\n    last_synced: 2026-03-01\n\n\nForge完成报告会显示：\n\n📄 文档同步检查 — 2 个文档可能需要更新:\n  ⚠️ docs/api-reference.md 可能需要同步更新（api_config 的权威源 src/config.py 已修改）\n\nConfiguration\n\nVia init flags or forge-state.json config section:\n\nKey\tDefault\tDescription\nmodel\tanthropic/claude-opus-4-6\tLLM model for agents\nmax_rounds\t5\tMax repair-inspect cycles before escalation\nrepair_timeout\t600\tRepair agent timeout (seconds)\ninspect_timeout\t300\tInspector timeout (seconds)\nauto_commit\ttrue\tAuto git-commit on PASS"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/melody1015/forge-loop",
    "publisherUrl": "https://clawhub.ai/melody1015/forge-loop",
    "owner": "melody1015",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/forge-loop",
    "downloadUrl": "https://openagent3.xyz/downloads/forge-loop",
    "agentUrl": "https://openagent3.xyz/skills/forge-loop/agent",
    "manifestUrl": "https://openagent3.xyz/skills/forge-loop/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/forge-loop/agent.md"
  }
}