{"skill":{"slug":"soulforge","displayName":"Soulforge","summary":"Run high-signal autonomous coding loops with Soulforge (feature-dev/bugfix/review-loop) using strict worktree isolation, review gates, and scoped fix cycles.","description":"---\nname: soulforge\ndescription: \"Run high-signal autonomous coding loops with Soulforge (feature-dev/bugfix/review-loop) using strict worktree isolation, review gates, and scoped fix cycles.\"\nmetadata:\n  {\n    \"openclaw\":\n      {\n        \"emoji\": \"🔥\",\n        \"requires\": { \"bins\": [\"soulforge\", \"gh\"], \"env\": [] },\n      },\n  }\n---\n\n# Soulforge (Effective Use Guide)\n\nThis is **not** a full engine reference. This is the operating playbook for getting high-quality autonomous coding outcomes with Soulforge.\n\n## Core Operating Model\n\nUse Soulforge when you want: plan → implement → verify/test → PR → review/fix loops with minimal babysitting.\n\nThis skill assumes a trusted operator is launching runs in a trusted repository/worktree. It is not intended as a generic end-user execution surface.\n\nSoulforge 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.\n\nPreferred workflows:\n- `feature-dev` for end-to-end feature delivery\n- `bugfix` for diagnose-first, surgical fixes\n- `review-loop` for tightening an existing PR until clean\n\n## Golden Rules (Most Important)\n\n1. **Do not run workflows in the repo main checkout.**\n   - Use a dedicated worktree for each run.\n2. **Always isolate work in worktrees.**\n   - Default base: `<repo>/worktrees/`\n   - Manual daemon start can still be cwd-sensitive in bare+worktree layouts, so keep execution and daemon concerns distinct.\n3. **Keep tasks tightly scoped.**\n   - Specific issue, explicit acceptance criteria, explicit DO-NOT list.\n4. **Treat review findings with discipline.**\n   - FIX in-scope issues.\n   - Mark genuine extras as `SEPARATE`.\n5. **Use callback-exec only.**\n   - HTTP callback mode is removed.\n6. **Do not hardcode session keys, tokens, or destination identifiers in examples or live commands.**\n   - Supply destinations and credentials deliberately at launch time.\n\n## Current Behavior You Should Rely On\n\n### Workdir / Worktree safety\n- If `--workdir` is omitted, Soulforge can auto-provision a worktree under `<repo>/worktrees/...`.\n- Main checkout is blocked (including bare+worktree edge cases).\n- Dirty worktrees are rejected for run start.\n- Out-of-base workdirs are blocked unless explicitly overridden.\n\n### Checkpoint model\n- `approve/reject` is gone.\n- Use structured completion via `soulforge complete ...`.\n- Canonical step types are `single`, `loop`, and `switch`.\n- Human checkpoints are typically `single` steps with `executor: manual`.\n- Manual steps must define `output_schema` so operator completion is valid.\n\n### Callback model\n- Use `--callback-exec`.\n- Prefer passing through the workflow/runtime-produced callback body unchanged via `{{callback_message}}`.\n- Recommended pattern:\n  - `--message \"{{callback_message}}\"`\n- `--callback-exec` is the transport/delivery wrapper, not the primary place to author callback content.\n- Callback handlers are operator-selected integrations, not core Soulforge requirements.\n- 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.\n- Template vars include:\n  - `{{run_id}}`, `{{step_id}}`, `{{step_status}}`, `{{status}}`, `{{task}}`\n  - `{{callback_message}}` (preferred callback body)\n  - `{{prompt}}` remains only for backward compatibility in older/manual scenarios\n- When a callback matters operationally, confirm live state with `soulforge status`; callback text can lag or be noisy.\n\n## Recommended Command Patterns\n\n### Feature build\n```bash\nsoulforge run feature-dev \"Implement <issue-url>.\nConstraints: max 2 stories. DO NOT refactor unrelated modules.\" \\\n  --workdir /abs/path/to/repo/worktrees/feat-xyz \\\n  --callback-exec '<CALLBACK_HANDLER_COMMAND_USING_{{callback_message}}>'\n```\n\n### Bugfix\n```bash\nsoulforge run bugfix \"Fix <issue-url> with failing test first; minimal patch only.\" \\\n  --workdir /abs/path/to/repo/worktrees/fix-xyz \\\n  --callback-exec '<CALLBACK_HANDLER_COMMAND_USING_{{callback_message}}>'\n```\n\n### Review-only tightening on an existing PR\n```bash\nsoulforge run review-loop \"Review PR #123 and fix only in-scope findings.\" \\\n  --workdir /abs/path/to/repo/worktrees/pr-123 \\\n  --var pr_number=123 \\\n  --callback-exec '<CALLBACK_HANDLER_COMMAND_USING_{{callback_message}}>'\n```\n\n## How to Maximize Autonomous Quality\n\n### 1) Give a tight task contract\nInclude:\n- target issue/PR URL\n- explicit in-scope list\n- explicit out-of-scope list\n- objective success criteria\n- only operator-reviewed task text and vars; do not blindly forward untrusted end-user content into privileged workflows\n\n### 2) Keep iteration loops short\nIf a PR loops repeatedly:\n- create/update `.soulforge-progress.md` in the run worktree with exact outstanding fixes\n- run `review-loop` constrained to remaining findings\n- keep these notes local to the worktree; they are operator scratch state, not a credential/config channel\n\n### 3) Handle gates like an operator, not a coder\nAt review gate:\n- move in-scope defects to FIX\n- separate unrelated ideas into follow-up issues\n- avoid “while we’re here” drift\n\n### 4) Expect long fix steps; optimize signal\nLong fix steps are normal for real refactors. Your job is quality control at gates, not interrupting active runs.\n\n## Practical Triage Heuristic\n\nWhen code-review returns findings:\n- **High/Medium tied to original issue:** FIX now\n- **Low tied to original issue correctness:** usually FIX now\n- **Anything outside scope:** SEPARATE\n\n## Anti-Patterns (Avoid)\n\n- Running multiple workflows in the same checkout\n- Allowing scope creep in repeated review-fix loops\n- Merging with known Highs because “tests pass”\n- Treating this skill as generic Soulforge docs instead of an execution playbook\n- Treating `{{task}}` or arbitrary `--var` values as safe to embed into shell fragments\n- Copy-pasting literal session keys or channel identifiers from examples into real environments\n\n## Minimal Status Workflow for Operator\n\n- Start run\n- Watch callbacks, but verify important transitions with `soulforge status`\n- Handle manual gates promptly\n- Triage with strict scope discipline\n- Repeat until pass\n- Merge\n- Pull main + build + npm link + daemon restart (when local runtime should track latest)\n\n## Notes\n\n- Deliberately choose the callback destination before launching a run. Do not casually infer a channel when multiple destinations are in context.\n- Supply callback destinations or credentials via operator-controlled configuration at launch time; never hardcode live values into a reusable skill example.\n- Choose executors and callback handlers per environment; this skill documents orchestration patterns, not a single required integration stack.\n- If loops hit `max_loops`, spawn a fresh constrained `review-loop` run with a scope lock file.\n- For long-running initiatives, keep a brief run ledger in the channel (run id → PR → status).\n","tags":{"latest":"2.0.1"},"stats":{"comments":0,"downloads":1480,"installsAllTime":2,"installsCurrent":2,"stars":1,"versions":25},"createdAt":1771212674695,"updatedAt":1778491552996},"latestVersion":{"version":"2.0.1","createdAt":1776451076378,"changelog":"Release v2.0.1 — see CHANGELOG.md","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"jamesrp13","userId":"s176253px5rqx5y75fgwj0xnzd850qtq","displayName":"jamesrp13","image":"https://avatars.githubusercontent.com/u/11344110?v=4"},"moderation":null}