pi-superworkers

Minimal autonomous GitHub issue workers for Pi, pi-superagents, and Superpowers.

Phase 1 processes exactly one unassigned, unblocked ready-for-agent child issue at a time. The worker claims it, creates an isolated worktree, launches a fresh Pi RPC session, writes and reviews a just-in-time Superpowers plan, runs /sp-implement, performs Matt's final Standards + Spec review through the local Pi Superagents adapter, records controller-run focused-test evidence for the exact commit, and opens a PR containing Closes #N. A separate no-tools LLM merge authority must approve the reviewed head before deterministic, fail-closed GitHub gates execute the merge. Once every child is closed, /sw-close-parent runs the configured full suite on the current base-branch head and closes the parent only if it passes.

Requirements

• Pi >=0.80.7
• Node.js >=22
• git
• authenticated GitHub CLI (gh auth status)
• @teelicht/pi-superagents
• Superpowers skills installed through skills.sh
• Matt Pocock's grilling, to-tickets, and code-review skills; pi-superworkers adapts the latter to Pi Superagents' sp-code-review and sp-spec-review roles
• GitHub sub-issues and issue dependencies, or Blocked by: #N body fallbacks

Install

pi install git:github.com/legout/pi-superworkers

Restart Pi, then run:

/sw-setup --full

--full installs missing pi-superagents and skill dependencies, after checking GitHub authentication and required system tools. Without it, /sw-setup configures the package and shows manual installation commands without changing dependencies. Run /sw-doctor afterwards to see the full status.

Restart once more so pi-superagents reloads its command settings, then verify:

/sw-doctor

Setup is idempotent. It writes ~/.pi/agent/pi-superworkers.json and safely merges the required sp-plan and sp-implement settings into ~/.pi/agent/extensions/subagent/config.json. It never patches third-party package source. scripts/setup.mjs remains available for a checkout-based bootstrap or CI check.

Commands

• /sw-ticketize <approved-spec> — create a human-approved parent/child issue graph using Matt's to-tickets workflow.
• /sw-setup [--full] — configure the package; --full installs missing package and skill dependencies, while the default only checks and shows manual commands.
• /sw-doctor — check tools, authentication, skills, and parent-integration-suite configuration.
• /sw-worker 123 [--herdr|--mode=herdr] — launch a detached controller for issue #123 and return immediately; the worker survives Pi reloads/exits, the live widget reconnects from durable progress, and --herdr still controls the actual worker session.
• /sw-run 100 [--herdr|--mode=herdr] — launch a detached controller for the first claimable issue on the current dependency frontier under parent issue #100 and return immediately; the worker survives Pi reloads/exits, the live widget reconnects from durable progress, and --herdr still controls the actual worker session.
• /sw-merge 123 — ask an independent LLM merge authority, rerun deterministic gates, and merge issue #123 through its protected PR.
• /sw-close-parent 100 — verify every child is closed, run the repository full suite on the current base branch, and close parent #100 only on success; full suites remain exclusive to this command.
• /sw-status — show the controller PID/state/log path for the current repository.
• /sw-uninstall — remove package-owned configuration before pi remove.

Issue contract

A claimable child issue is open, has the configured ready-for-agent label, has no assignee, and has no open blocker. Assignment is the claim. Use one dispatcher per repository to avoid claim races.

If a worker encounters a missing product or architecture decision, it comments with NEEDS_INFO context and stops rather than guessing. Workers needing information release the assignee and apply needs-info; failures retain the assignment and worktree for diagnosis; successful runs retain assignment while the PR is open.

Configuration

~/.pi/agent/pi-superworkers.json:

{
  "version": 1,
  "maxWorkers": 1,
  "readyLabel": "ready-for-agent",
  "baseBranch": "main",
  "fullSuiteCommand": "uv run pytest -q -n 4",
  "sessionMode": "rpc",
  "workerTimeoutMinutes": 120
}

The configured full suite is owned by the deterministic parent-integration controller. Child workers instead run controller-owned, issue-relevant focused tests selected by the final review. fullSuiteCommand is required only when /sw-close-parent closes a parent issue. Controller logs stay local to the machine and are not inserted into conversation context. Set sessionMode to herdr to use background Herdr panes by default; it requires Pi to run from a Herdr-managed pane. --herdr and --mode=herdr override this setting for one worker run.

Phase 1 safety

• exactly one worker per dispatcher run;
• explicit, revisioned lifecycle transitions with machine-readable evidence;
• no planning or implementation on the parent checkout;
• one worktree and Pi session per issue;
• plan/review contracts live outside the repository and are schema-checked;
• dirty worktrees and no-op implementations fail;
• review and focused-test evidence are bound to each exact PR head;
• parent full-suite evidence is bound to the exact integrated base-branch head and is invalidated if that branch or its child set changes during the run;
• the merge authority has no tools and can only return merge or block JSON;
• the controller reruns all gates immediately before gh pr merge and pins --match-head-commit;
• --admin is never used;
• changed heads and merge conflicts fail closed;
• Phase 1 does not resolve merge conflicts autonomously;
• GitHub branch protection or merge queues remain the final merge authority.

Development

npm install
npm test
npm run typecheck

License

MIT