The spec-to-PR lifecycle
UseZombie turns a markdown spec into a validated pull request through a deterministic pipeline: validate, implement, gate, score, ship.Step by step
Write a spec
A spec is a markdown file describing what you want built. It can follow any format — structured sections, free-form prose, bullet lists. The agent reads natural language and infers intent from your codebase context.You describe what to build. The agent figures out how.
Submit
Submit via
zombiectl run --spec <path> or the REST API (POST /v1/runs). On submission, UseZombie validates that referenced files exist in the workspace, deduplicates against in-flight runs, and enqueues the work.Agent implements
The NullClaw agent runtime picks up the run and works inside an isolated git worktree — a fresh working directory branched from your default branch. The agent receives the spec plus injected codebase context (relevant file contents, module structure) to produce an accurate implementation.No changes touch your main branch until you approve the PR.
Gate loop
After implementation, the agent runs your project’s standard validation gates in sequence:
make lint— linting and type checksmake test— unit testsmake build— production build
FAILED with full error context.The repair limit is configurable per agent profile. See Gate loop for details.
Score
Every completed run receives a scorecard with four weighted dimensions:
Scores map to tiers:
| Dimension | Weight | What it measures |
|---|---|---|
| Completion | 40% | Did the agent implement everything the spec asked for? |
| Error rate | 30% | How many gate failures occurred before passing? |
| Latency | 20% | Wall-clock time from enqueue to PR. |
| Resource efficiency | 10% | Token and compute usage relative to task complexity. |
| Tier | Score range |
|---|---|
| Bronze | 0 — 39 |
| Silver | 40 — 69 |
| Gold | 70 — 89 |
| Elite | 90 — 100 |
PR
The agent pushes a branch named
zombie/<run_id>/<slug> and opens a pull request on GitHub. The PR body contains an agent-generated explanation of what was implemented and why. A scorecard comment is posted with the quality metrics.From here, it’s a normal code review. Approve, request changes, or close.Runtime architecture
Under the hood, the CLI, API server, queue, worker, and executor coordinate to move a run from submission to PR. Component responsibilities:- zombiectl — CLI client. Submits specs, checks status, streams logs.
- zombied API — HTTP server. Validates specs, manages runs and workspaces, serves the dashboard.
- Redis Streams — Work queue. Durable, ordered, with consumer group semantics for worker fleet scaling.
- zombied worker — Claim runs, orchestrate the gate loop, push results to GitHub. Supports drain and rolling deploys.
- zombied-executor — Sidecar process that owns the sandbox lifecycle. Spawns NullClaw agents, manages worktrees, enforces resource limits.
- GitHub — Target forge. Branch push, PR creation, scorecard comments.
Agent relay model
For lightweight, interactive agent sessions (spec init, run --preview), UseZombie uses a different execution model: the agent relay. Instead of queuing work for a sandbox, zombied acts as a stateless pass-through between the CLI and the workspace’s LLM provider.
Key differences from the pipeline model:
| Pipeline (full runs) | Agent relay (spec init, preview) | |
|---|---|---|
| Execution | Sandbox on worker, queued | Direct handler, no queue |
| File access | Agent reads files in sandbox | CLI reads files locally, sends to model on demand |
| Duration | 1-5 minutes | 3-8 seconds |
| State | Durable (DB + Redis) | Stateless (CLI manages conversation) |
| Provider | Configured per workspace | Same, resolved by zombied |
zombied sits between CLI and provider because API keys are server-side secrets managed per-workspace.