What XYZ is
Built in four layers, all local-first:
1 · The kernel — tick
A dependency-free Node CLI over an append-only event log. Agents take
path-scoped claims serialized by an O_EXCL lock, so two agents
editing overlapping paths serialize instead of racing. No server, no remote.
2 · The execution layer
Headless turns driven through each agent's own CLI — Consult, Relay, Swarm, Marathon — with path allowlists, worktree isolation, a commit-bypass guard, wall-clock watchdogs, and typed exit codes enforced by one shared containment core.
3 · The operations layer
Issue-first intake, a scored backlog, a collision-checking wave planner, preflight readiness, verification gates with resource caps, a receipted release ledger, PDDA doc governance, HQ for multi-repo control, and ~50 reusable skills.
4 · Docs as runtime state
Agent work has to be stoppable, resumable, and handed off from PROJECT/**
alone — the doc tree is serialized machine state, and drift between docs and code is a
defect rather than untidiness.
Code quality you can verify. Repositories you can maintain.
Autonomous coding is useful when you can check the result and continue the work later. XYZ Forge brings independent review, executable checks, and maintained project records into the delivery workflow.
Independent review for each task
In a Builder–Reviewer relay, a separate reviewer examines the implementation against the agreed requirements. Findings return to the builder for correction, and the review records what was checked and what remains unresolved.
Test evidence tied to the delivered revision
Configured automated gates run the required checks and record their results against the exact commit. Delivery checks verify that the evidence matches the proposed change and that the repository’s configured requirements are satisfied. A reviewer’s approval does not replace passing tests.
Project records that support the next change
Plans, decisions, verification results, and delivery status stay with the repository, giving the next maintainer or agent the context needed to resume.
These checks reduce avoidable mistakes and make gaps visible. Their strength depends on the requirements, tests, and review behind them.
The operations layer — what makes it a lifecycle system
Unattended agents fail for boring reasons: the work was under-specified, two lanes collided, a gate never ran, or nobody can tell afterward what actually landed. Each of those failures produced a durable surface:
| Surface | Answers |
|---|---|
| Issue-first intake — GH issue → capture doc → parked ledger row | “Is this work written down anywhere?” |
Scored backlog — pri / sev / appeal / effort ratings | “What should run next, and why that?” |
| Wave planner — exact write-set intersection, zone caps, dependency gating | “Can these lanes run together without colliding?” |
| Preflight — freshness probes, already-landed detection, readiness verdict | “Is this specified well enough to run while I sleep?” |
| Verification gates — a gate must be able to start before turn 1, with CPU/wall/RSS caps | “Did anything actually prove this works?” |
| Deterministic gate receipts — machine-checkable on-disk proof before PR or push | “Did the exact commit SHA pass the qualification suite?” |
| Release ledger — SQLite + a git-mergeable SQL dump, receipted writes | “What did we promise, and what shipped with evidence?” |
| Doc governance (PDDA) — frontmatter, status tables, ledger coverage | “Can an agent resume this work tomorrow from the docs alone?” |
| HQ — multi-repo resolution, capability tiers, previewed writes | “Do that, for project Acme, from wherever I am” |
| ~50 skills | Reusable procedures for all of the above |
Two design commitments hold this together: machine-readable boundaries — state crossing a subsystem boundary travels as a schema-stamped JSON artifact with explicit nulls, never parsed out of logs or prose — and deterministic before advisory — anything expressible as a regex, schema, or file check may block, while LLM review may warn, rank, or propose but never block.
The four execution modes — they stack
1 · Consult
Answers “what do the other models think?” A one-shot, parallel second opinion: the same question fans out to two models, each answers in an isolated copy of the repo, and the answers are reconciled into one. Advisory; nothing is modified.
2 · Relay
Answers “build this and have it reviewed until it's right.” A turn-based loop between a Producer and a Reviewer on one shared artifact, handing off through files instead of you copy-pasting between two agent windows.
3 · Swarm
Answers “do several independent things at once.” Multiple agents working
concurrently on disjoint, path-scoped lanes across separate clones, coordinated by the
tick kernel so they never collide.
4 · Marathon
Answers “do all of today's queued work while I sleep.” A queue of preflighted work runs unattended, gated at every phase boundary — end-of-day or overnight.
Consult and Relay need only this repo. Swarm and Marathon effectively require PDDA, a separate repo-governance project whose checkers ship alongside: the unattended path refuses any repo without it. PDDA is a prerequisite for the unattended path, not an optional enhancement. See Use Cases and the FAQ.
Scope, stated plainly
It is: a local-first operations system for a small number of humans directing a larger number of agents across their own repositories. The operator is the sole decision authority; every write path of consequence previews first or requires an explicit gate.
It is not application lifecycle management. No multi-user identity, no role-based access control, no SSO, no compliance certification. Those require multi-user, server-backed, permissioned state — and local-first is a deliberate constraint here, not a missing feature.
It is not, yet, a spec-generation system. The machinery assumes specified
work; nothing here authors the spec. Writing it is left to the operator and the LLM working
with them — /idea and /triage are thin front doors, and adjacent
tools (GitHub Spec Kit, Task Master) can land their output as a capture doc.
Prove the kernel works — 60 seconds, no accounts
git clone https://github.com/HiQS-Labs/XYZ-forge.git
cd XYZ-forge
npm install
npm run test:unit # ~1 second — 14 kernel unit tests
./validate.sh # full suite — budget 5–10 minutesTested on Node 18+; requires git. See the README for the full quickstart, install paths, and hardware sizing for unattended runs.