Stark Local Factory

Stark is the local-first control plane for the BluntDashboard code factory.

Its job is not to replace Git, PR review, or architectural judgment. Its job is to make those things legible and enforceable for both humans and agents.

It sits on top of the repo’s existing architectural reference:

Subsystem Topology
Change Topology
.github/labels.json
.github/pull_request_template.md

What Stark is responsible for

Persisting work items locally so they survive terminal exits, machine sleep, and agent handoffs
Generating subsystem-aware patch trains from repo goals
Recommending local execution backends based on risk and subsystem plane
Carrying merge-control expectations forward into PR labels, patch ordering, and review gates
Keeping knowledge sources explicit so agent work remains grounded in the living docs

Local deployment model

The first deployment target is this always-on Mac mini, not a cloud control plane.

Stark runs as a repo-local command under cmd/stark
Tooling is pinned through mise.toml
The command is executed through the repo uv workspace
Run state persists under XDG_STATE_HOME when available, or falls back to .stark/state.json
Materialized worktrees persist under XDG_DATA_HOME when available, or fall back to .stark/worktrees
Pause and resume semantics are part of the run lifecycle, so a work item can survive shell exit or machine sleep
Local sibling backend repos are expected at workspaces/repos/<project>/repo

Bootstrap path:

mise install
just bootstrap
just dagger-runtime-bootstrap
just stark-doctor

Preferred Dagger Runtime

For the local Mac mini code factory, the preferred Dagger runtime is podman, not Docker.

Preferred: podman
Acceptable but secondary: nerdctl
Experimental on this host: Apple container
Not part of the intended setup: Docker

Why podman:

Dagger supports it directly and documents it as a first-class OCI runtime.
It works on macOS through podman machine while still exposing a Docker-compatible CLI surface.
It matches the repo preference to avoid Docker while keeping Dagger usable locally.

On this Mac mini, just dagger-runtime-bootstrap installs the pinned Podman CLI, extracts the required macOS helper binaries into the XDG cache, writes Podman config under the XDG config directory, and starts a rootful podman-machine-default for Dagger.

Because this environment already points XDG directories into workspaces/macrodata, Podman machine config, state, and extracted helper assets stay under the macrodata tree rather than scattering across ad hoc host paths.

The same Podman runtime also closes the OpenShell gap. Stark discovers Podman’s API socket and exports DOCKER_HOST=unix://... when invoking the nvidia-openshell backend, which lets OpenShell bootstrap and manage its gateway without introducing Docker into the local factory.

Candidate execution backends

Stark is deliberately control-plane-only in the first cut. It does not yet launch these systems automatically, but it knows about them and can recommend them.

Backend	Local role	Why it matters
`secure-exec`	Fast policy and guard execution	Low-latency in-process checks, quick code execution, useful for sanitization and governance logic
`rivet-agent-os`	Planner and workflow kernel	Durable sessions, agent workflows, host tools, and future multi-agent orchestration
`rivet-sandbox-agent`	Repo-mutation session manager	Good fit for remote-controllable coding-agent sessions with transcript streaming
`microsandbox`	High-isolation execution	Best fit for risky platform/data work where strong isolation matters
`nvidia-openshell`	Policy-enforced sandbox runtime	Best fit for agent sessions that need constrained egress, provider injection, and stronger credential fencing than a generic local shell. On this Mac mini it rides on Podman’s Docker-compatible API socket rather than Docker Desktop
`dagger`	Pipeline and artifact fabric	Best fit for reproducible build, test, packaging, and release jobs with shared cache on the Mac mini

Future remote backends like Cloudflare Sandboxes, Containers, and Dynamic Workers fit naturally as additional execution backends once the local control loop is stable.

dagger is intentionally not treated as a planner or sandbox replacement. It complements the other backends by handling deterministic pipeline work after planning and approval, especially where containerized build graphs and artifact caching matter.

Run lifecycle

The first cut uses a simple persisted run lifecycle:

queued
proposed
approved
paused
completed
rejected

Typical flow:

A human or agent creates a Stark run with a title, objective, and primary subsystem.
Stark proposes a patch train and review gates.
Stark materializes isolated git worktrees for each patch step.
Stark can fast-forward clean sessions against the base branch without rewriting diverged ones.
A human or higher-trust agent approves or rejects the proposal.
Execution happens through the chosen backend(s).
The run is paused/resumed as needed.
The run is marked complete once the patch train lands and its worktrees can be archived.

Commands

uv run --package stark stark doctor
uv run --package stark stark backends list
uv run --package stark stark run create --title "Introduce guarded asset retry tuning" --objective "Improve asset ingest reliability without mixing unrelated UI work" --primary-subsystem ORCH.asset-and-export-jobs --secondary-subsystem PLAT.observability --change-type fix --risk medium
uv run --package stark stark worker once
uv run --package stark stark run materialize stark-0001
uv run --package stark stark run sessions stark-0001
uv run --package stark stark run sync stark-0001
uv run --package stark stark run execute stark-0001 --sequence 1 --backend secure-exec --command "git status --short"
uv run --package stark stark run merge-ready stark-0001 --sequence 1
uv run --package stark stark run open-pr stark-0001 --sequence 1 --dry-run
uv run --package stark stark run show stark-0001
uv run --package stark stark handoff dagger export stark-0001
uv run --package stark stark run pause stark-0001 --reason "Waiting on production incident review"
uv run --package stark stark run resume stark-0001
uv run --package stark stark run archive stark-0001

Governance model

Stark should enforce the same GitOps discipline already defined elsewhere in the repo:

every run has one primary subsystem ID
patch trains follow subsystem topology and dependency order
tracker-linked GitHub issue dependencies can block PR creation and merge-ready state
PR labels derive from subsystem, type, shape, and risk
docs and runbooks are part of the delivery surface, not optional cleanup
high-risk work should route to stronger isolation backends and tighter review gates

Current scope vs future scope

Current Stark scope:

persisted work queue
patch-train generation
worktree session materialization
fast-forward-only session sync
branch-preserving worktree archiving
direct command execution through real mutation backends (secure-exec and nvidia-openshell)
GitHub dependency-aware merge-readiness evaluation
PR draft generation from materialized sessions
backend visibility
pause/resume semantics
merge-gate guidance

Planned future scope:

launching backends directly
transcript capture and replay
automated PR creation and label application
merge blocking based on policy evaluation
documentation growth loops and knowledge capitalization
remote execution targets beyond the Mac mini

The first Dagger bridge is already concrete but intentionally narrow: stark handoff dagger export <run-id> writes a JSON handoff artifact for deterministic build/test/package work, without turning Dagger into the planner.

The first repo-local Dagger executor now lives under infra/stark-dagger. Use it with:

just stark-dagger-run stark-0001

That command exports the Stark handoff JSON and then runs the stark-dagger Dagger module against it.

The operator skill for this control plane lives at agent-skills/stark-operator/SKILL.md.