xiv implement

Implement a Linear issue on a dedicated branch — plan, implement, validate, review. Local only; no PR.

xiv implement <issueId> [--tdd] [--skip-acceptance-review] [--max-iterations <n>]
 
# examples
xiv implement ENG-123
xiv implement ENG-123 --tdd --max-iterations 5

issueId is a Linear issue key, for example ENG-123.

What it does

xiv implement launches the linear-implement Smithers workflow, pinned to the repo you run it from (SMITHERS_TARGET_CWD). The run:

1. Fetches the issue from Linear (title, description, acceptance criteria).
2. Plans the change.
3. Implements it on a dedicated branch created in your repo.
4. Validates — runs the repo's own tests, lint, and typecheck.
5. Reviews — a local review agent reads the working-tree diff against the issue's acceptance criteria and returns approve / comment / request_changes plus prioritized findings, applying the xiv-review-core judgment.

Steps 3–5 form a loop: only request_changes sends the work back for another pass, and validation is always the real gate — a review that crashes or returns nothing can never wedge the loop. The loop is capped by --max-iterations; when the cap is hit, the run returns its last attempt rather than spinning.

The pack must be installed first (xiv init) — the command errors otherwise.

Flags

Raising --max-iterations only costs anything for issues that actually fail a pass — a clean issue still exits after one. --max-iterations 1 fails fast when you want to see the first attempt before spending more.

Local only — what that means

xiv implement never pushes and never opens a PR. The result is a local branch in your repo, reviewed and validated, that you control the publication of. "Implement ENG-123 but don't push" maps to this command exactly — don't add a git push afterward unless that's actually wanted.

To publish later:

• xiv pr refine --branch <name> — push the branch, open a PR, and settle it (see xiv pr).
• Or use xiv ship from the start when you know you want a PR.

What to expect while it runs

This is a multi-step agent run and it takes time. Long quiet stretches during a hard implement or review step are normal — judge by progress, not silence:

xiv ps       # is it still running?
xiv logs     # what step is it on / did something fail?
xiv ui       # live workflow graph in the browser

See Operations for the full observe/recover loop.

Cost

Agents default to the cheap model tier, which is right when the issue is already well specified in Linear. For a genuinely hard issue, prefix with XIV_TIER=quality to raise the implement, review, and planning steps. See Model Tiers.

When to use it vs siblings

Related

• Backing workflow: linear-implement
• The local review step: Review Model