Skill: jamesrp13/soulforge (version 2.0.1)

--- 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", "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. 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 ```bash 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 ```bash 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 ```bash 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).


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)