什么是 Soulforge？

Soulforge 是一款专为自主软件工程设计的专用执行引擎。作为 Openclaw Skills 生态系统的一部分，它专注于高信号编码周期，包括端到端功能交付和外科手术式的错误修复。通过强制执行严格的工作树隔离和评审关卡，Soulforge 确保 AI 智能体在不干扰主仓库检出的情况下安全运行，为自动化代码生成和改进提供了一种严谨的方法。

该技能非常适合需要将复杂的编码任务委托给智能体，同时保持高标准代码质量和仓库健康状况的开发人员。通过利用 Soulforge 等 Openclaw 技能，团队可以实施“计划-实现-验证”生命周期，减少人工干预，并简化从问题识别到拉取请求合并的路径。

下载入口:https://github.com/openclaw/skills/tree/main/skills/jamesrp13/soulforge

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Soulforge 应用场景

• 针对特定问题 URL，使用 feature-dev 工作流进行端到端功能交付。
• 使用 bugfix 工作流，以诊断优先的方法进行外科手术式的错误修复。
• 通过迭代评审-修复循环收紧现有拉取请求，确保整洁的合并。
• 在隔离的工作树中进行自动化仓库维护，防止主分支意外数据丢失。
• 在需要极少开发人员干预的情况下，使用 Openclaw Skills 进行高质量的自主编码。

1. 通过选择 feature-dev 或 bugfix 等工作流并定义紧凑的任务合约来初始化运行。
2. 自动配置专用工作树，将编码环境与主仓库检出隔离。
3. 执行自主循环，由智能体制定计划、实施更改并通过测试进行验证。
4. 通过 Openclaw Skills 触发回调执行，以提供状态更新和会话通知。
5. 参与评审关卡以分类发现结果，将范围内的缺陷移至修复阶段，并分离范围外的想法。
6. 通过完成循环并将验证后的更改合并到代码库中来完成任务。

Soulforge 配置指南

确保您已安装所需的二进制文件：soulforge、codex 和 gh。

# 验证依赖项
soulforge --version
gh --version

要使用 Openclaw Skills 启动功能构建，请使用以下命令模式：

soulforge run feature-dev "Implement " r
  --workdir ./worktrees/feature-branch r
  --callback-exec 'openclaw agent --session-key "agent:id" --message "Soulforge {{run_id}} {{status}}" --deliver'

Soulforge 数据架构与分类体系

Soulforge 按如下方式组织其执行数据和元数据：

name: soulforge
description: "Run high-signal autonomous coding loops with Soulforge (feature-dev/bugfix/review-loop) using strict worktree isolation, review gates, and scoped fix cycles."
metadata:
  {
    "openclaw":
      {
        "emoji": "??",
        "requires": { "bins": ["soulforge", "codex", "gh"], "env": [] },
      },
  }

Soulforge (Effective Use Guide)

This is not a full engine reference. This is the operating playbook for getting high-quality autonomous coding outcomes with Soulforge.

Core Operating Model

Use Soulforge when you want: plan → implement → verify/test → PR → review/fix loops with minimal babysitting.

Preferred workflows:

• feature-dev for end-to-end feature delivery
• bugfix for diagnose-first, surgical fixes
• review-loop for tightening an existing PR until clean

Golden Rules (Most Important)

1. Never run from repo main checkout.
   • Soulforge now enforces this guardrail.
2. Always isolate work in worktrees.
   • Default base: /worktrees/
3. Keep tasks tightly scoped.
   • Specific issue, explicit acceptance criteria, explicit DO-NOT list.
4. Treat review findings with discipline.
   • FIX in-scope issues.
   • Mark genuine extras as SEPARATE.
5. Use callback-exec only.
   • HTTP callback mode is removed.

Current Behavior You Should Rely On

Workdir / Worktree safety

• If --workdir is omitted, Soulforge can auto-provision a worktree under /worktrees/....
• Main checkout is blocked (including bare+worktree edge cases).
• Dirty worktrees are rejected for run start.
• Out-of-base workdirs are blocked unless explicitly overridden.

Checkpoint model

• approve/reject is gone.
• Use structured completion via soulforge complete ....
• Pause checkpoints are type: pause.

Callback model

• Use --callback-exec.
• Template vars include:
  • {{run_id}}, {{step_id}}, {{step_status}}, {{status}}, {{task}}
  • {{callback_message}} (step-level, preferred)
  • {{prompt}} remains for backward compatibility in pause scenarios

Recommended Command Patterns

Feature build

soulforge run feature-dev "Implement .
Constraints: max 2 stories. DO NOT refactor unrelated modules." r
  --workdir /abs/path/to/repo/worktrees/feat-xyz r
  --callback-exec 'openclaw agent --session-key "agent:cpto:slack:channel:c0af7b05h28" --message "Soulforge {{run_id}} {{step_id}} {{step_status}}" --deliver'

Bugfix

soulforge run bugfix "Fix  with failing test first; minimal patch only." r
  --workdir /abs/path/to/repo/worktrees/fix-xyz r
  --callback-exec 'openclaw agent --session-key "agent:cpto:slack:channel:c0af7b05h28" --message "Soulforge {{run_id}} {{step_id}} {{step_status}}" --deliver'

Review-only tightening on an existing PR

soulforge run review-loop "Review PR #123 and fix only in-scope findings." r
  --workdir /abs/path/to/repo/worktrees/pr-123 r
  --var pr_number=123 r
  --callback-exec 'openclaw agent --session-key "agent:cpto:slack:channel:c0af7b05h28" --message "Soulforge {{run_id}} {{step_id}} {{step_status}}" --deliver'

How to Maximize Autonomous Quality

1) Give a tight task contract

Include:

• target issue/PR URL
• explicit in-scope list
• explicit out-of-scope list
• objective success criteria

2) Keep iteration loops short

If a PR loops repeatedly:

• create/update .soulforge-progress.md in worktree with exact outstanding fixes
• run review-loop constrained to remaining findings

3) Handle gates like an operator, not a coder

At review gate:

• move in-scope defects to FIX
• separate unrelated ideas into follow-up issues
• avoid “while we’re here” drift

4) Expect long fix steps; optimize signal

Long fix steps are normal for real refactors. Your job is quality control at gates, not interrupting active runs.

Practical Triage Heuristic

When code-review returns findings:

• High/Medium tied to original issue: FIX now
• Low tied to original issue correctness: usually FIX now
• Anything outside scope: SEPARATE

Anti-Patterns (Avoid)

• Running multiple workflows in the same checkout
• Allowing scope creep in repeated review-fix loops
• Merging with known Highs because “tests pass”
• Treating this skill as generic Soulforge docs instead of an execution playbook

Minimal Status Workflow for Operator

• Start run
• Wait for review gate
• Triage with strict scope discipline
• Repeat until pass
• Merge
• Pull main + build + npm link + daemon restart (when local runtime should track latest)

Notes

• If loops hit max_loops, spawn a fresh constrained review-loop run with a scope lock file.
• For long-running initiatives, keep a brief run ledger in the channel (run id → PR → status).