soulforge

name	soulforge
description	Dispatch multi-step coding workflows to Claude Code CLI or Codex CLI from YAML definitions via a persistent background daemon. Use when: (1) implementing a feature end-to-end, (2) running bugfix workflows with human checkpoints, (3) delegating coding tasks in the background, (4) managing custom workflows (list/show/create). Requires @ghostwater/soulforge.
repository	https://github.com/ghostwater-ai/soulforge
metadata	{"openclaw":{"emoji":"🔥","requires":{"bins":["soulforge","gh"],"env":["GITHUB_TOKEN or gh auth login"],"optional_bins":["claude","codex"]},"install":[{"id":"npm","kind":"npm","package":"@ghostwater/soulforge","global":true,"bins":["soulforge"],"label":"Install Soulforge CLI (npm)"}]}}

Soulforge

Daemon-based workflow engine for coding workflows with optional human checkpoints.

Key Updates (current behavior)

• --workdir is required for soulforge run.
• Built-in workflows: feature-dev, bugfix.
• Custom workflow management is available via:
  • soulforge workflow list
  • soulforge workflow show <name>
  • soulforge workflow create <name> [--from <template>] [--force]
• Workflow resolution supports built-ins + custom workflows + path fallback.
• Structured-output steps use schema-driven completion (soulforge complete) with runner-injected completion instructions.
• Legacy expects text gating is deprecated/removed from runtime behavior.
• Bugfix PR step prompt is idempotent (reuse existing PR if present before create).

Quick Start

npm install -g @ghostwater/soulforge
soulforge daemon start

Run a Workflow

soulforge run feature-dev "Implement issue #123" --workdir /path/to/repo

Common options:

--executor codex-cli|claude-code
--model <model-name>
--callback-url <url>
--callback-exec '<shell command>'
--no-callback

Checkpoints

soulforge status
soulforge approve <run-id>
soulforge reject <run-id> --reason "..."

Custom Workflows

soulforge workflow list
soulforge workflow show feature-dev
soulforge workflow create my-workflow --from feature-dev

Custom workflows live in ~/.soulforge/workflows/.

Structured Completion Contract

For structured steps, Soulforge injects completion instructions that require:

soulforge complete --run-id <id> --step-id <id> --data '<json>'

<json> must satisfy the step output_schema.

Monitoring & Lifecycle

soulforge status [query]
soulforge runs
soulforge events --run <id>
soulforge logs 100

soulforge cancel <run-id>
soulforge resume <run-id>

soulforge daemon start
soulforge daemon stop
soulforge daemon status

Security / External Effects

• Coding executors may send repository content to model providers.
• gh is used for PR operations.
• Callback endpoints receive run/step metadata you configure.

Only run on repos/endpoints you trust.

References

• Workflow format: references/workflow-format.md