Soulforge

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