fx Agent Rules

A native coding-agent CLI written in Zig with an embeddable runtime.

Overview

fx requires runtime evidence from the binary just built, not only a green test run. The guide also covers architecture, Zig style, exact-commit CI, repeatable terminal replays, performance limits, and the difference between optimizer training and correctness checks.

Verification by change type Contribution etiquette

Documents

├── 
├── sdk
│   └── 
├── 
├── 
└──

Techniques in this file

01 / Verification by change type

Explain what passing tests do not establish

Tests may omit the full application, a TTY, and background threads. Completion therefore requires a real interaction, or an explicit note that the environment cannot run the binary.

7Do not say the work is "ready", "done", "good to go", "complete", or similar until you have personally run the binary and exercised the change on its happy path. A passing test suite is necessary, not sufficient — tests in this repo do not always construct the full runtime, attach a TTY, or spawn background threads, so they will not catch startup crashes, render regressions, or thread-lifetime bugs.

02 / Verification by change type

Bind verification to the binary containing the change

Verify with the newly built executable from the checkout; an installed binary on PATH is not evidence. Investigate incomplete fixes before blaming the user's binary.

25* `zig build` writes to `zig-out/bin/fx`. That is the only binary that contains your latest change.

03 / Verification by change type

Separate optimizer training from correctness coverage

Classify every root E2E file as training, verification-only, or intentionally excluded. Rare and security-sensitive cases can stay mandatory without influencing hot-path optimization.

95* **Verification-only:** important correctness, recovery, security, or rare96  behavior that the final candidate must pass without making it hot

Turn a live terminal failure into replayable evidence

The render-debugging section records output bytes and resize events in a deterministic tape. It then routes the reproduced failure into an in-process regression test, connecting manual observation with a repeatable check.

317The tape is deterministic — any reviewer can replay it without a TTY, and a golden file can be checked in as a regression test.

05 / Verification by change type

Name the authoritative environment for a performance budget

Linux CI owns the raw startup-latency contract. Local macOS results remain informational because loader and process overhead vary; the guide forbids subtracting a baseline to manufacture a passing result.

349local runs report raw means without assigning a substitute product budget. The350process baseline is diagnostic only and is never subtracted.

06 / Contribution etiquette

Tie CI evidence to the current revision

The readiness rule rejects stale or partial CI results and requires all four native platform aggregates to pass. A follow-up repair needs a new run on its own commit.

284A Full CI result is valid only when it belongs to the exact current commit and all four `Full suite (...)` jobs succeed. Each platform aggregate requires its ReleaseSafe native check plus all four ReleaseSafe E2E shards. Do not mark the draft PR ready or request review from a stale, partial, queued, cancelled, skipped, or failed run. If Full CI fails, make the smallest repair, rerun the focused local proof, push the new commit to the same draft PR, and wait for Full CI on the new exact commit. After CI passes, run the final ship gate and mark the PR ready only when it reports `SHIP` for that exact commit.

Ideas for your repo

State which runtime failures unit tests cannot observe.
Verify the executable built from the edited checkout.
Separate performance-training inputs from required correctness cases.
Convert live terminal failures into deterministic replay and regression tests.
Name the environment that owns a performance budget.