Auto Repo Setup

Auto Repo Setup

Make the repository usable without changing the user's normal way of working. Treat setup as an evidence-driven repository task, not as a special interface for people with a particular job title.

Entry router

Classify the request before changing anything. Do not combine modes merely because they all contain the word "setup".

Operating principles

1. Do not infer competence from role. Match the user's demonstrated altitude. A collaborator can tell an agent "sync the remote first"; do not invent a launcher, shortcut, or wizard unless the user asked for one.
2. Use the least mechanism that satisfies the outcome. Prefer, in order: direct Agent instruction → project instruction → explicit command → lifecycle hook. A hook is not a more professional version of a sentence.
3. Inspect authority before producing. Read the current user request, then project instructions, onboarding/runbooks, manifests, lockfiles, and actual command output. Do not make ONBOARDING.md, Python, uv, ffmpeg, or .env mandatory for repositories that do not declare them.
4. Preserve user work. Never auto-stash, merge, rebase, force, discard, or overwrite local changes to make setup look successful. Already-authorized delivery of this task's isolated changes may use the repository's declared scoped workflow under Authorized shared-checkout delivery; this does not authorize integrating unrelated local commits or shared WIP.
5. Define a falsifiable success state. "Dependencies installed" is not enough; run the project's real smoke test or startup command and verify the observable result.
6. Keep diagnosis read-only until the cause is known. Installation, config edits, hook registration, commits, and external writes require the authority implied by the user's request; destructive or public actions require explicit approval.

Workflow A — Environment repair

A1. Read the project map

Read only files that exist, in this order:

1. AGENTS.md and AGENTS.override.md
2. CLAUDE.md and scoped project rules
3. ONBOARDING.md or the repository's named setup/runbook
4. README.md
5. Manifests, lockfiles, task runners, CI, and container configuration
6. Existing Claude/Codex settings only when the request concerns agent behavior

If no onboarding guide exists, infer the setup path from authoritative manifests and exercised commands. Do not stop to ask whether to create documentation unless a durable handoff is part of the request.

A2. Run a read-only capability inventory

Use the bundled scripts/check_env.py against the repository root when a Python 3.10+ runner is already available. It detects the declared ecosystem and checks only the relevant toolchain; it does not install dependencies or read secret values. If Python is itself the missing prerequisite, perform the same read-only manifest inventory directly instead of installing Python merely to run the audit.

uv run python scripts/check_env.py --repo <repo-root>
uv run python scripts/check_env.py --repo <repo-root> --json

Treat the inventory as evidence, not as the project setup specification. A custom runbook or CI workflow can require tools the generic inventory cannot infer.

Expected result:

• exit 0: all toolchains inferred from manifests are available;
• exit 1: one or more inferred prerequisites are missing;
• exit 2: the repository or its metadata could not be inspected safely.

A3. Repair the root cause

For each failed requirement:

1. Capture the exact command, exit code, stdout, and stderr.
2. Trace the failure to the declaring source: project guide, manifest, lockfile, configuration, or runtime log.
3. Apply the smallest project-consistent repair.
4. Re-run the failed check before moving on.

Do not restart, reinstall everything, or switch package managers as a first move. Do not print .env or credential contents; verify presence and behavior without echoing values.

A4. Verify the product path

Run the project's documented smoke test, build, or start command. If none exists, derive one from CI/task-runner configuration and label the derivation. Verify the observable result, not merely a zero exit code.

Report:

• what was broken and the evidence;
• what changed;
• the exact verification and result;
• any remaining user action or blocked authority.

Workflow B — Routine Git sync

For "sync before work", prefer a short project instruction shared by the agents that use the repository. The routine is:

1. Inspect branch, upstream, and working-tree state.
2. If the task includes already-authorized delivery and the repository declares usable scoped tools that preserve unrelated shared HEAD, index, and WIP, use Authorized shared-checkout delivery. Dirty or divergent state alone is not a reason to leave that delivery waiting.
3. Otherwise, if the working tree is clean, run git pull --ff-only.
4. If there are local changes, do not auto-stash or pull; explain the state.
5. If local and remote histories diverged, do not auto-merge, rebase, or force; explain the state.
6. If the network fails, say so and continue locally only when the user's task can safely proceed on the local version.

A collaborator may also simply say:

Sync the latest remote version before starting.

That is a normal Agent instruction, not a degraded fallback.

Do not register SessionStart merely to automate this routine. Static behavior belongs in AGENTS.md/CLAUDE.md; the Agent can inspect context and handle exceptional Git states instead of hiding them in a shell process.