getting-started.md

Getting started

ARC Loop works best when you treat it as the run boss, not as a nicer checklist.

A contract has two halves:

• arc.toml says what is allowed, what is forbidden, and how "done" is proven.
• prompt.md tells the agent what to do in normal human language.

The agent can read both. Only arc gets to decide whether the run is finished.

Create a run

From the repo you want the agent to work in:

arc new goal auth-refresh --title "Fix auth refresh"

That creates:

.agent/contracts/auth-refresh/
  arc.toml
  prompt.md
  state.json
  events.jsonl
  evidence/
  artifacts/
  proposals/

Open arc.toml first. Replace the starter echo ok verifier with a real command for your project.

Good examples:

[[done]]
id = "tests-pass"
description = "Auth refresh tests pass"
proof = "command"
required = true
cmd = "cargo test auth_refresh"
required_exit_code = 0
timeout_seconds = 600

[[done]]
id = "scope-clean"
description = "No forbidden files changed"
proof = "diff_scope"
required = true

Then edit prompt.md. Keep it short. Tell the agent what to fix, what to read first, and what to hand back.

Lint before launch

arc lint auth-refresh --strict

Strict lint fails on vague acceptance language, missing machine scope, invalid proof definitions, and empty path or command policies.

Launch

arc launch --agent codex auth-refresh --print

or:

arc launch --agent claude auth-refresh --print

This activates the run and records the hash of arc.toml. After launch, direct edits to arc.toml are treated as drift. Use proposals for changes.

Validate

When the agent says it is done:

arc doctor --agent all auth-refresh
arc validate auth-refresh

If a required proof is still Unproven, Evidenced, or Rejected, the run is not done.

The final report is:

arc report auth-refresh

That writes .agent/contracts/auth-refresh/final.md and prints the same report.