soulforge_skill

Overview

This skill dispatches multi-step development workflows to Claude Code or Codex CLIs via a persistent background daemon. It automates end-to-end feature runs (plan → implement → verify → PR) while pausing at human-review checkpoints. Use it to delegate long-running coding tasks to run in the background and integrate callbacks or branch automation.

How this skill works

A local soulforge daemon reads YAML workflow definitions and dispatches each step to an executor CLI (claude or codex). It creates a git worktree or uses a provided workdir, runs steps in sequence, and stops for human approval when a step uses executor: self. The daemon exposes CLI commands to start runs, approve or reject checkpoints, stream events, and manage the process lifecycle.

When to use it

• Implement a feature end-to-end without blocking your workstation
• Run background development tasks while you focus on other work
• Automate creation of feature branches, builds, tests, and PRs
• Enforce human review checkpoints during automated workflows
• Integrate workflow completion notifications to external systems via callbacks

Best practices

• Install and configure the required CLIs: soulforge, claude/codex, gh, and git before running workflows
• Store detailed specs as GitHub issues and reference the issue URL in the task string for clearer context
• Use --var to pass repo, build_cmd, and test_cmd so workflows run reproducibly
• Prefer worktrees for isolated runs; use --workdir or --no-worktree only when needed
• Provide a callback URL with authentication headers for CI/CD or notification integration

Example use cases

• Run a feature-dev workflow to add authentication: plan, implement code, run tests, and open a PR automatically
• Delegate refactor tasks to run overnight and get a callback when finished for review
• Create a workflow that requires a human to approve design decisions mid-run, then let automation continue after approval
• Automate generating a feature branch, running build and test commands, and creating a PR when tests pass