First run

Five steps: init → onboard → prime → run → review. The rough edges are flagged as they come up, so you don't trip on them.

This assumes alc is already on your PATH — see Installation if not.

1. Scaffold the Operator Layer#

cd your-project
alc init --setup

This creates .alc/ — the Operator Layer, your agentic configuration. It is deliberately kept apart from your app code and from your editor's own config (.claude/, and so on). The Operator Layer acts on the codebase, not inside it.

--setup also installs the user-level editor skill. Drop it if you only want the directory.

Inside you get a manifest.yaml, a few starter Blueprints (chore, bug, feature, plan), a ship Flow, and check sets for whatever stacks were detected in your project root.

2. Adopt the checks you already have#

alc onboard

alc init writes generic per-stack checks. But most projects already declare their own — a make test target, an npm run typecheck script, a lint command. alc onboard harvests those from your Makefile and package.json, proposes them as a reusable project check set, and — once you approve — wires them into your Blueprints.

It proposes first and writes nothing without approval. alc onboard --yes skips the prompt; alc onboard --dry-run prints the proposal and exits.

Then validate what you have:

alc lint

alc lint validates the Operator Layer, not your source code and not your editor's agents. Right after init it is a trivial pass. It earns its keep once you start editing Blueprints. See The Policy Gate for the rules it enforces.

Two rules that save real pain: checks are judged by exit code, and a check that already fails on a clean checkout makes every run fail. Run each check yourself once before trusting it. Make the checks real covers this properly.

3. Prime the context (optional, worth it)#

Don't make the agent rediscover your codebase on every run. Write a small curated pointer — where the relevant code lives, the convention to follow — and pass it by name:

alc primer new payments               # scaffolds .alc/primers/payments.md

Small, high-value context beats a large always-on memory file — a Primer is a file naming where the relevant code lives, and nothing more.

4. Run it#

alc run chore "remove the unused export endpoint" --primer payments

You get live progress — each file read and edited, the model in use, the running cost — then the Assurance Loop running your checks.

Two heads-ups:

• A run can cost up to four model turns. The Assurance Loop takes one attempt and repairs up to three times — max_repairs defaults to 3 — so a run that keeps failing its checks invokes the model four times before it gives up. Multiply that by the Blueprint's compute tier: chore above runs at standard, while the scaffolded feature Blueprint uses deep, which maps to the most expensive model. Pass --tier standard to override the tier for one invocation without editing the Blueprint.
• Cancelling leaves work behind, and where depends on --isolate. Without it, partial edits stay in your working tree — including new, untracked files, so check git status and not just git diff --stat, which hides them. With --isolate, cancelling still commits whatever the engine had already written onto the run's branch and removes the worktree; the CLI names that branch as it exits. Either way the run report lists what the agent changed.

To keep your working tree clean, add --isolate and the whole run happens on a throwaway branch in a git worktree:

alc run chore "remove the unused export endpoint" --isolate

See Isolation and landing for what that branch is and how to integrate it.

5. Review — the human gate#

ALC guarantees the change compiles and your checks pass. It does not guarantee the change is right.

Read the diff, judge it, keep or discard. That is the one step ALC deliberately leaves to you.

Where this goes#

That is the attended loop, with you present for every run. Thicken the Operator Layer over time — more Blueprints, Flows composed out of them, Specialists that keep notes on an area — and the agent takes on more of the work with the guardrails always on.

When you are ready to stop being present for every run, the queue takes over: see Unattended work.

Known rough edges#

Honest, and still being smoothed. Every one of these is written up where it bites; collected here so the list is not one item long while the real traps sit scattered as inline warnings.

• The claude-code engine inherits your project's .claude/ config. It runs inside your project, so your hooks and settings apply and can add harmless noise to the output. Set clean_config: true on the engine entry in manifest.yaml to restrict it to user-level settings.
• A check that already fails on a clean checkout makes every run fail, forever. The agent cannot fix problems that were not its task, so it burns the whole repair budget and reports failure. Run each check yourself once first — Make the checks real covers this properly.
• Checks are judged by exit code, and some tools do not use it. gofmt -l exits 0 even when files are unformatted. Wrap those in a shell: one-liner that turns the output into a status.
• A fresh scaffold verifies nothing. alc init writes command: ["true"] when it cannot find your tools, and a check that always passes is not a guarantee. Replace it, or run alc onboard to adopt the checks your project already declares.
• --isolate is a no-op outside a git repository. There is no worktree to make, so the run happens in place and the CLI says --isolate ignored: not inside a git repository. It is a warning, not a refusal — your files are edited directly.
• uv tool install --force silently reuses a cached build when the version is unchanged. If you are iterating on ALC itself and reinstalling as a tool, bump the version first or your changes will not land.