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.

This skill assumes a trusted operator is launching runs in a trusted repository/worktree. It is not intended as a generic end-user execution surface.

Soulforge itself is the step orchestration layer. The operator running a Soulforge workflow chooses which executor(s) and callback handler(s) make sense for that environment. The examples in this skill are illustrative patterns, not mandatory integrations.

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. Do not run workflows in the repo main checkout.
   • Use a dedicated worktree for each run.
2. Always isolate work in worktrees.
   • Default base: <repo>/worktrees/
   • Manual daemon start can still be cwd-sensitive in bare+worktree layouts, so keep execution and daemon concerns distinct.
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.
6. Do not hardcode session keys, tokens, or destination identifiers in examples or live commands.
   • Supply destinations and credentials deliberately at launch time.

Current Behavior You Should Rely On

Workdir / Worktree safety

• If --workdir is omitted, Soulforge can auto-provision a worktree under <repo>/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 ....
• Canonical step types are single, loop, and switch.
• Human checkpoints are typically single steps with executor: manual.
• Manual steps must define output_schema so operator completion is valid.

Callback model

• Use --callback-exec.
• Prefer passing through the workflow/runtime-produced callback body unchanged via {{callback_message}}.
• Recommended pattern:
  • --message "{{callback_message}}"
• --callback-exec is the transport/delivery wrapper, not the primary place to author callback content.
• Callback handlers are operator-selected integrations, not core Soulforge requirements.
• Callback examples in this skill are illustrative wrappers for trusted operator-controlled environments. They are not a recommendation to expose arbitrary user input to shell construction.
• Template vars include:
  • {{run_id}}, {{step_id}}, {{step_status}}, {{status}}, {{task}}
  • {{callback_message}} (preferred callback body)
  • {{prompt}} remains only for backward compatibility in older/manual scenarios
• When a callback matters operationally, confirm live state with soulforge status; callback text can lag or be noisy.

Recommended Command Patterns

Feature build

soulforge run feature-dev "Implement <issue-url>.
Constraints: max 2 stories. DO NOT refactor unrelated modules." \
  --workdir /abs/path/to/repo/worktrees/feat-xyz \
  --callback-exec '<CALLBACK_HANDLER_COMMAND_USING_{{callback_message}}>'

Bugfix

soulforge run bugfix "Fix <issue-url> with failing test first; minimal patch only." \
  --workdir /abs/path/to/repo/worktrees/fix-xyz \
  --callback-exec '<CALLBACK_HANDLER_COMMAND_USING_{{callback_message}}>'

Review-only tightening on an existing PR

soulforge run review-loop "Review PR #123 and fix only in-scope findings." \
  --workdir /abs/path/to/repo/worktrees/pr-123 \
  --var pr_number=123 \
  --callback-exec '<CALLBACK_HANDLER_COMMAND_USING_{{callback_message}}>'

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
• only operator-reviewed task text and vars; do not blindly forward untrusted end-user content into privileged workflows

2) Keep iteration loops short

If a PR loops repeatedly:

• create/update .soulforge-progress.md in the run worktree with exact outstanding fixes
• run review-loop constrained to remaining findings
• keep these notes local to the worktree; they are operator scratch state, not a credential/config channel

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
• Treating {{task}} or arbitrary --var values as safe to embed into shell fragments
• Copy-pasting literal session keys or channel identifiers from examples into real environments

Minimal Status Workflow for Operator

• Start run
• Watch callbacks, but verify important transitions with soulforge status
• Handle manual gates promptly
• Triage with strict scope discipline
• Repeat until pass
• Merge
• Pull main + build + npm link + daemon restart (when local runtime should track latest)

Notes

• Deliberately choose the callback destination before launching a run. Do not casually infer a channel when multiple destinations are in context.
• Supply callback destinations or credentials via operator-controlled configuration at launch time; never hardcode live values into a reusable skill example.
• Choose executors and callback handlers per environment; this skill documents orchestration patterns, not a single required integration stack.
• 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).