Soulforge

Run high-signal autonomous coding loops with Soulforge (feature-dev/bugfix/review-loop) using strict worktree isolation, review gates, and scoped fix cycles.

Security Scan

The skill is an instruction-only playbook for the Soulforge CLI that consistently requires the soulforge and gh CLIs and stays within that scope — nothing in the files requests unrelated credentials, installs, or hidden endpoints.

Purpose & Capability

The name/description match the requested binaries and examples. Requiring 'soulforge' (the orchestration CLI) and 'gh' (used for PR creation) is proportional to the stated goal of running feature/bugfix/review loops.

Instruction Scope

The SKILL.md stays on-topic and repeatedly warns operators not to embed secrets or untrusted text into shell snippets. However, examples use --callback-exec with template variables such as {{callback_message}}; if an operator wires those into a shell wrapper unsafely, it could enable command-injection or data exfiltration. The skill itself documents the correct safety boundaries, but safe operator practices are required.

Install Mechanism

No install spec is provided (instruction-only), so nothing will be downloaded or written by the skill package itself. This is the lowest-risk install model.

Credentials

No environment variables or credentials are requested by the skill. Usage of 'gh' implies the operator must have configured GitHub auth locally, which is appropriate and not requested by the skill itself.

Persistence & Privilege

The skill is not always-enabled and does not request persistent system-wide privileges or modify other skills. Autonomous invocation is allowed by default for skills and is not a red flag here.

Assessment

This is a coherent operator playbook, not a payload installer, but you should: (1) ensure the soulforge binary you run is from a trusted distribution (the skill does not install it), (2) have gh authenticated locally if you expect PR creation to work, (3) avoid passing untrusted input directly into shell callback wrappers — prefer handlers that accept callback bodies via stdin or files rather than interpolating {{callback_message}} into shell arguments, and (4) follow the advice in the SKILL.md to always run in isolated worktrees. If you need higher assurance, request the provenance (download/source) for the soulforge binary before using this skill in sensitive repos.

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).