Docs
Source to Work
How an external issue becomes a Work item, runs as a session, and closes with verified proof. This is the end-to-end narrative of the Zero model.
Overview
Zero structures work in a single pipeline: something needs to be done → a Work item is created → one or more sessions execute the plan → proof is attached → the Work item closes.
That pipeline is the same regardless of where the Work originated: a GitHub issue, a Jira ticket, a Linear task, or a description you typed manually.
Source systems
Work items can originate from:
| Source | How it enters Zero | Status |
|---|---|---|
| GitHub issue | Import — Zero fetches title, body, labels, and writes problem-definition.md | Available (requires local gh CLI setup) |
| Manual entry | Operator describes the Work item directly in Zero | Always available |
| Jira | Import (same pattern as GitHub) | In development |
| Linear | Import (same pattern as GitHub) | In development |
| GitHub comment trigger | A comment on a GitHub issue triggers Work creation in Zero | Available — see comment-triggered Work |
Import is one-time fetch — Zero does not continuously sync with the source. After import, Zero owns the Work item state.
Work item creation
When a Work item is created — from any source — Zero writes a local record with:
- problem-definition.md — the issue description, acceptance criteria, and any imported context
- Work type — bug, feature, investigation, greenfield, refactor, or epic
- Initial state —
OPEN
The Work item is now in Zero's state machine. The source system is not involved further unless the operator triggers a write-back action (e.g., posting a proof comment to the original GitHub issue).
Sessions and execution
A session is a bounded execution cycle against a Work item. Each session:
- Loads the Work item context (problem-definition, memory files, prior session logs)
- Generates a plan — the operator reviews and approves before execution begins
- Executes — the provider runs code changes, tests, or investigations
- Produces a session log — diffs, test output, notes, and a proposed outcome
Multiple sessions are common. A planning session scopes the Work; an implementing session executes it; a verifying session confirms the result. Sessions accumulate in the Work item's memory — future sessions see prior context.
Proof and resolution
A Work item closes when the operator attaches verified proof:
- A diff showing the change
- Test output confirming the result
- An operator note for non-code outcomes (investigation complete, greenfield scoped, etc.)
Without proof, Work stays open. The proof requirement is enforced across all plans — there is no override. Once proof is attached and verified, the Work item transitions to RESOLVED and the outcome is logged in regression memory.
If a write-back action is configured (e.g., post proof summary to the original GitHub PR), Zero triggers that after resolution. The source system receives a record of what happened — but it did not drive the execution.
Architecture note
Source integrations today use local CLI transport — the gh CLI for GitHub. This is a developer-side setup, not a customer-managed integration. Operators with gh installed get import and write-back. Operators without it work fully with manual Work items.
When API-based transport ships, GitHub, Jira, and Linear integrations will use scoped API tokens that Zero manages through the console. The session model, proof model, and memory model stay the same — only the source connection method changes.