FAQ

The questions that come up first. Fuller answers live in the README and GUIDING-PRINCIPLES.md.

What is XYZ Forge, in one paragraph?

A local-first engineering operations system for running AI coding agents as a workforce. It coordinates several agents — Claude Code, Codex, agy (Google's Antigravity CLI), and others — working on the same repositories, and carries the machinery an unattended run actually needs: specified work, collision-free lanes, verification gates, and a receipted record of what happened. It started as a coordination kernel and became the loop around it: capture → rate → plan → preflight → execute → gate → land → record.

Is it application lifecycle management (ALM)?

No, and the boundary is deliberate. There is no multi-user identity, no role-based access control, no SSO, no cross-team capacity planning, and no compliance certification. Those require multi-user, server-backed, permissioned state — local-first is a deliberate constraint here, not a missing feature. If you need Polarion or Azure DevOps, you need Polarion or Azure DevOps.

Does it generate specs from a prompt?

Not yet. XYZ Forge has no structured intake → spec → PRD → project-plan generator; the machinery assumes specified work, and 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 that scaffold a capture doc, not a rigid intake pipeline. If you want prompt-to-spec generation, adjacent tools cover it — GitHub Spec Kit for spec-driven flows, Task Master for PRD-to-task breakdown — and their output can land in PROJECT/1-INBOX/ as a capture doc.

What is PDDA, and why do Swarm and Marathon need it?

PDDA is a separate repo-governance project whose checkers are vendored into XYZ Forge; the dependency runs one way only (the harness reads governance structure; PDDA never calls the harness). Consult and Relay need only this repo — preflight degrades every doc-shaped check to advisory and still reaches a verdict. Swarm and Marathon effectively require PDDA: the unattended path refuses any repo that isn't Tier A (PDDA plus a vendored XYZ install), because the wave planner cannot rank a backlog it cannot read. PDDA is a prerequisite for the unattended path, not an optional enhancement.

The test suite prints nothing for minutes, then fails — is it broken?

Probably not. Under a sandboxed agent harness (Claude Code's default Bash sandbox, for example), the suite's mktemp -d scratch directories are blocked: it sits silent for several minutes and then fails. It looks like a hang, not a permissions error, and it is the repo's single most common false alarm. Run ./validate.sh un-sandboxed before concluding anything is broken.

Is XYZ a “graph” — does it do graph engineering?

Partly, and the parts it leaves out are deliberate.

What matches: phases are real nodes — each gets a relay doc, a tick token, a reviewer, a brief, and an artifact allowlist. Inside a phase there is a genuine LLM-selected edge: the reviewer writes STATUS:, and approved/closed is terminal while anything else is another round, bounded by a round cap. Every phase boundary runs a verification gate, and the whole run is an inspectable state machine rather than a model's self-report.

What doesn't: there is no DAG. depends_on is scalar-only, so a join (“p4 after p2 and p3”) is inexpressible. There is no parallel execution within a plan; depends_on validates the order you authored rather than deriving one. A failure halts the chain — there is no conditional edge to a remediation node. The scheduling a graph engine automates is handed to the operator on purpose; parallelism exists as swarms across separate clones, arranged by you.

Do phases run in parallel? What does depends_on actually do?

Inside a single marathon plan: no. Phases run strictly one at a time, in plan order. A phase without depends_on is not “parallel-safe” — it simply runs when its turn comes. depends_on takes exactly one phase id (depends_on: p3) and validates the authored order; chain them (p3 → p4 → p5) for longer orders. Concurrency exists across separate runners, live sessions sharing the tick log, and read-only triage fan-outs. Always --dry-run a new plan first — it prints the real execution order at zero cost.

What do I need to run it?

Node 18+ and git for the kernel and test suite; Python 3.8+ for the default harness runtime. Live Consult/Relay/Marathon turns additionally need the Codex and agy CLIs installed and authenticated. XYZ is a macOS toolkit today — that's the platform the gates run on — with Linux and Windows on the roadmap.

Which agents and models can it drive?

The default headless builders are the subscription-billed Codex and agy CLIs; Claude is fully supported as an explicit, cost-acknowledged opt-in (default budget $0.50, 12 turns). The Models & Harnesses page lists the evaluated harnesses and model grades from the committed registry.

What does it cost?

XYZ itself is open source (see the repo's license files). Builder turns bill against the CLI subscriptions you already have (Codex, agy); the API-billed Claude builder is capped per call and never a silent default.

Is it safe to run unattended?

XYZ is designed around reversibility and containment — branches, path claims, gates with resource caps, typed escalation — but it is provided “AS IS,” without warranty. Models may choose commands outside the intended harness workflow. Maintain tested, independent backups, keep the verification gates on, and read the recovery report after any interrupted run before trusting its commits.

How is code review and quality assurance handled across a Marathon or Jog run?

Through a strict two-tier architecture that decouples deep code auditing from macro delivery gates:

1. Per-issue code-level QA: For every individual GitHub issue or marathon phase, the harness drives an autonomous Builder ↔ Reviewer relay loop using separate model roles (e.g. Agy builder, Codex reviewer). The Reviewer audits modified files in full (swept file: yes), checks acceptance probes, and must emit an explicit Approved status before the harness runs local test suites (validate.sh) and generates an on-disk cryptographic gate receipt (.xyz/receipts/<SHA>.json).

2. PR-level mechanical framework checks: On final branch PR closeout and landing, deterministic scripts (marathon-closeout.sh, gate_receipt.py, githooks/pre-push) and the main orchestrator model verify system invariants: base branch targeting (strictly development, never main), diff size sanity (< 500 lines for targeted bugs), gate qualification receipts, and CI mergeability. The orchestrator performs a mechanical framework check rather than an ungrounded second-pass diff read.

Where does the Roadmap page's data come from?

Straight from the repository's committed releases ledger (releases.db / releases.sql) — the same source of truth the repo's own dashboard renders from. The page is regenerated on every deploy; nothing on it is edited by hand.

How do I report a bug?

Open an issue on GitHub. If you hit a harness bug while working in a different repo, the file-xyz-bug skill files it here — capture doc and roadmap parking included — without touching the repo you're standing in.