A brief. A branch.
A result you can inspect.

01 / Install

Get aid ready.

curl -fsSL https://aid.agent-tools.org/install.sh | sh
aid --version
aid setup

The installer resolves the latest GitHub release, verifies its SHA-256 checksum, and installs without root to ~/.cargo/bin. Add that directory to PATH if needed.

Set AID_VERSION to select a release or AID_INSTALL_DIR to choose a directory. Unsupported targets use Cargo, which requires Rust. Supported-target download failures stop.

In your repository, configure project defaults and inspect detected agents:

aid project init
aid config agents

Read the installer before running it. The official operating guide covers configuration and complete workflows.

02 / First research task

Ask for a saved answer.

Use an installed research-capable agent. This example uses Gemini; replace it with your chosen agent.

aid run gemini "Summarize the design in README.md" \
  --dir . --read-only -o /tmp/aid-summary.md \
  --difficulty simple --budget standard \
  --urgency normal --rigor draft

The answer is saved to the declared output file. Read-only enforcement checks the Git run directory after the agent exits; it detects changes rather than preventing every write.

03 / First code task

Keep changes in their own worktree.

Preview routing, then explicitly choose an installed agent. There is no auto agent.

aid advise "Add request validation and regression tests" \
  --difficulty moderate --budget standard \
  --urgency normal --rigor standard --kind complex-impl

aid run codex "Add request validation and regression tests" \
  --dir . --worktree feat/request-validation \
  --difficulty moderate --budget standard \
  --urgency normal --rigor standard --verify --bg

Replace Codex with the route you choose. Background dispatch returns a task ID. Configure a real project verification command; bare verify uses project or supported defaults.

For Cargo projects, remote-build support routes builds and verification through rbox. See the run flag reference.

04 / Watch, show, accept, merge

Read the evidence.

Replace t-1234 with the returned task ID. Watch progress, wait for settlement, then inspect the result and verification.

aid watch --tui
aid wait t-1234
aid show t-1234 --summary
aid show t-1234 --diff
aid show t-1234 --diff --branch
aid show t-1234 --output

Done is a lifecycle state, not proof of success. Check the derived outcome: Verified and Delivered are successful; Unverified is inconclusive and Broken is a check failure. AI judgment and peer review supplement verification.

After reviewing and approving the delivered artifact, record acceptance and integrate code into your intended current branch:

aid accept t-1234
aid merge t-1234

Acceptance records your decision; merge integrates code. Neither substitutes for the other. When you are ready to collect the accepted task worktree:

aid gc --task t-1234

GC requires a matching accepted artifact, a clean worktree, and reachable durable commits, including recursive submodules. An inconclusive proof preserves the work.

05 / Independent cross-audit

Separate providers. Separate reports.

Keep the change's HEAD fixed. From a terminal outside an aid task, choose installed CLIs configured for different providers. Different CLI names alone do not establish independence; check each route's provider and model. Do not choose a weaker model on the caller's pool.

audit="Read-only cross-audit of HEAD. Report SHIP/FIX/BLOCK with evidence. Do not modify files."
aid run codex "$audit" --read-only --dir /path/to/change --bg \
  --difficulty moderate --budget standard --urgency normal --rigor standard
aid run claude "$audit" --read-only --dir /path/to/change --bg \
  --difficulty moderate --budget standard --urgency normal --rigor standard
aid run gemini "$audit" --read-only --dir /path/to/change --bg \
  --difficulty moderate --budget standard --urgency normal --rigor standard

Each background run returns a task ID. Replace these example IDs with those returned:

aid wait t-audit-1 t-audit-2 t-audit-3
aid show t-audit-1 --summary
aid show t-audit-1 --output
aid show t-audit-1 --output --full

Read-only audit prompts select ~/.aid/tasks/<id>/result.md automatically. Repeat summary and output inspection for each auditor. If no report was delivered, aid show says so; a tool log is not an audit report.

--read-only forbids modifying the repository under test and cannot combine with --worktree. Use --dir for the checkout. Enforcement compares the repository after the run; it is not a sandbox.

Optional: extract a verdict and evidence hint for each saved report. aid classify sends that report to an external API and needs a key in the macOS keychain. Read the classify guide for setup and JSONL batch extraction.

aid show t-audit-1 --output --full | aid classify \
  --choice verdict='What final verdict does this audit give?' --options SHIP,FIX,BLOCK \
  --noul evidence='Does the audit cite test output or command output as evidence?'

Compare the typed answers. A differing verdict is a reason to inspect the reports and actual test output, not to take a majority vote. You decide; acceptance remains explicit.

For tasks already in a workgroup, keep reviewable findings and a compact group summary:

aid group finding add wg-review --task t-audit-1 \
  --title "Audit verdict" "FIX: inspect cited evidence"
aid group finding list wg-review
aid group summary wg-review

--audit adds post-task cross-audit via aic. --rigor critical requires verification and post-task audit.

06 / Failure & custody

Keep the work. Fix the cause.

aid show t-1234 --summary
aid show t-1234 --diff --branch
aid reject t-1234
aid retry t-1234 --feedback "Reproduce the failing check and fix it"

Rejection preserves artifacts. Failed work in task worktrees is salvaged; shared checkouts preserve recovery commits under recovery refs without changing your active index or branch.

Do not delete task worktrees or prune their Git metadata manually. Inspect the evidence, correct the task, review again, and use acceptance plus GC for collection.