Autonomous Coding Loops With Isolation

---
name: autonomous-coding-loops-with-isolation
description: "Run high-signal autonomous coding loops with Soulforge (feature-dev/bugfix/review-loop) using strict worktree isolation, review gates, and scoped fix cycles."
category: "AI & Agents"
author: community
version: "2.0.1"
icon: bot
---

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