Specification
Clear intent and checks
A spec, SDD flow, or bug brief produces a well-described GitHub issue. Sandman only needs the work to be precise enough to run.
Autonomous delivery for coding agents
AFK coding agents orchestration in isolated sandboxes
Sandman turns one clear GitHub issue into an autonomous delivery loop. It plans the implementation, runs the agent in an isolated environment, stores progress in task.md, drives review, and merges the PR when the gates pass.
SANDMAN- 01Create isolated environment
- 02Render
task.md - 03Plan the implementation
- 04Build with TDD and checks
- 05Self-review and open PR
- 06Drive review to merge
Validation
Validate before release
Merge lands on a reference branch. Run smoke, e2e, and QA before promoting to production, just like fast human work.
Issue quality
Good input is still the unlock.
Sandman can run while you sleep when the issue has crisp intent, bounded scope, and visible checks.
SSpecific outcome
MMeasurable checks
AAchievable slice
RRelevant context
TTime-bounded scope
Operate the loop
Autonomous does not mean invisible.
Sandman is a CLI application. Portal is a visualization layer for current runs, queued issues, blockers, review state, logs, and merge readiness.
You do not babysit the agent, but you can inspect the loop at any time.
sandman main ? ❯ ./sandman run 2042: [260708175122-5395-2042] 17:51:39 [260708175122-5395-2042] 17:51:39 > build · MiniMax-M3 [260708175122-5395-2042] 17:51:39 [260708175122-5395-2045] 17:51:39 [260708175122-5395-2045] 17:51:39 > build · MiniMax-M3 [260708175122-5395-2045] 17:51:39 [260708175122-5395-2045] 17:51:40 [260708175122-5395-2043] 17:51:40 > build · MiniMax-M3 [260708175122-5395-2043] 17:51:40 [260708175122-5395-2045] 17:51:42 I'll start by loading the sandman skill and following the mandatory execution contract. [260708175122-5395-2045] 17:51:42 [260708175122-5395-2045] 17:51:42 → Skill "sandman" [260708175122-5395-2042] 17:51:42 I'll start by loading the sandman skill and checking the current state of the worktree. [260708175122-5395-2042] 17:51:42
It stays repo-native.The run starts where the code, branches, config, logs, and agent context already live.
It is scriptable.Teams can compose Sandman with shell scripts, CI, cron, hooks, and their existing release process.
It keeps ownership local.Sandman does not require the delivery loop to move into another SaaS control plane.
It leaves receipts.
task.md, events, logs, PRs, and review state remain inspectable after the agent stops.Receipts, not vibes
Every run leaves an auditable trail.
task.md
Rendered task, progress notes, and the continuation point for sandman run 1234 --continue.
Logs and events
Agent output, targeted checks, repair loops, and review responses.
Pull request
Code diff, review thread, green CI, merge decision, and linked issue.
Run state
Active, queued, reviewing, merged, or needs validation, projected from events.
Validation
Sandman feeds validation, never skips it.
Treat agent output the way you treat fast human output: the loop can merge to a reference branch, but release confidence comes from recurring validation across changes.
Good engineering still applies.
TDD is not an AI novelty. It is a traditional control that helps agents work in smaller, safer loops. Keep it, then add broader validation where risk demands it.
- Targeted tests during implementation
- Self-review before PR creation
- Green CI before merge
- Smoke, e2e, QA, or wider suites after groups of merged work
Reference branch is not production.
The reference branch Sandman merges into should be a branch you can validate, not a direct production promotion.
Today Sandman integrates with GitHub for source control and issues, and OpenCode as the implementation agent. That boundary may broaden over time, but the durable idea is the same: workflow-agnostic AFK delivery.
Methodology, correctly placed
Sandman owns the delivery loop.
Use the upstream method that produces the clearest issues. Sandman should lead the story because it owns the autonomous path from selected issue to reviewed, merged PR.
| Layer | Precise role | Relationship to Sandman |
|---|---|---|
| Matt Pocock workflow | grill-with-docs/wayfinder->to-spec->to-tickets->Sandman->Validation.Plus diagnosing-bugs, improve-codebase-architecture and others. | Use the skills to resolve uncertainty, publish the spec, and slice GitHub tickets. Sandman runs the ready ticket frontier AFK. |
| Spec-Driven Development | Executable specifications become the source of truth that tasks are derived from, for example GitHub Spec Kit or Kiro specs. | Optional upstream source of agent-ready issues. Sandman does not need to own the spec layer. |
The handoff stays stable regardless of method: Specification -> Sandman -> Validation.
OpenCode integration
Sandman runs OpenCode without hiding it.
Sandman uses OpenCode as implementation agent.
Host sessions stay inspectable.
Sandman live-mounts the host OpenCode database, so runs created by Sandman remain visible as native OpenCode sessions.
Debug in the right surface.
Use Portal for delivery state: run status, logs, review gates, and merge readiness. Use OpenCode for the agent transcript when you need to inspect what the model saw or did.
Sandman Review
Review stays inside the AFK gate.
Sandman Review is the local review module for PR feedback. It follows the same idea as OpenCode's GitHub /oc integration: a PR comment triggers agent work. In Sandman, the trigger is /sandman review and the review runs locally.
Comment-driven review.
Sandman Review listens for review request comments in repository PRs, reviews it, and posts feedback requesting changes or approving.
Not an afterthought.
The implementation agent builds and self-reviews first. Sandman Review then handles feedback, repair, green checks, and merge readiness as part of the gate.
Comparison
Sandman, SDD, and Loop Engineering occupy different layers.
Sandman is the operational delivery layer. SDD is the upstream specification layer; GitHub's Spec Kit article is the clearest reference. Loop Engineering is the broader discipline of designing agent loops; Addy Osmani's Loop Engineering article is the reference.
SDD describes. Sandman delivers.
SDD helps teams describe the work. Sandman helps teams leave the keyboard while the described work gets implemented, reviewed, and merged.
Sandman applies Loop Engineering.
Loop Engineering frames the management system around agentic work. Sandman applies those principles to one concrete loop: CLI-owned AFK delivery from GitHub issue to merged PR.
Careful wording matters. Sandman is not all of Loop Engineering; it is a concrete loop inside that discipline.
Ready for implementation
Wake up to merged PRs, then validate like an engineer.
Sandman makes AFK coding operational: explicit input, isolated environment, durable progress, review gates, merge discipline, and a clear post-merge validation step.