AI Agents Build And Env

ai-agents Build and Environment Runbook

Recreate a working dev environment for this repository from a fresh clone, verify it actually works, and avoid the traps that have cost prior contributors real time. Audience: a zero-context mid-level engineer or Sonnet-class model. Every command below was verified against the repo on 2026-07-03; the Provenance section gives a re-verification one-liner for each volatile fact.

Triggers

• set up this repo
• bootstrap the environment
• fresh clone setup
• ModuleNotFoundError: No module named yaml
• environment traps

Scope

This skill is environment setup and survival only. Adjacent problems route to siblings:

Process

Phase 1: Prerequisites

The interpreter version has ONE source of truth: .python-version (currently 3.14.6, as of 2026-07-03). Do not hardcode versions anywhere; read the pin.

Container or VM setup: bash scripts/bootstrap-vm.sh automates all of the above on Ubuntu (needs sudo; export GH_TOKEN first). It installs uv, the pinned Python via uv python install --default, Node 22, pwsh, gh, syncs dependencies, and installs Lefthook. Do not copy its shell implementation for new scripts; ADR-042 requires Python for new automation.

Manual Python install when not using the bootstrap script:

uv python install --default "$(cat .python-version)"

Phase 2: Core Install

From the repo root:

uv sync --frozen --extra dev
uv run --frozen lefthook install --reset-hooks-path
uv run --frozen lefthook check-install

What these do:

• uv sync --frozen --extra dev builds .venv/ from uv.lock exactly as locked (--frozen never rewrites the lockfile) with dev extras. The pre-push gate runs validation through uv run --frozen, so this .venv is the environment a push validates against (scripts/bootstrap-vm.sh:109-115).
• lefthook install installs Git shims for the events in lefthook.yml. check-install verifies that the shims are active. Lefthook reads the configuration at runtime, so editing the jobs under an already-installed hook type needs no reinstall. Adding or removing a hook type does: with no_auto_install: true set, the new type has no shim until install runs again.

Phase 3: Verify the Install

Run each; expected output shown. If any differs, stop and fix before working.

uv run --frozen lefthook version
# expect: 2.1.10

uv run --frozen lefthook check-install
# expect: exit 0

uv run pytest tests/test_paths.py --collect-only -q
# expect: "28 tests collected" (count as of 2026-07-03)

uv run python -c "import yaml; print(yaml.__version__)"
# expect: 6.0.3 (PyYAML pin in pyproject.toml project.dependencies)

Phase 4: MCP Layer

.mcp.json at repo root defines two servers. Copy .env.example to .env and fill keys (ANTHROPIC_API_KEY, PERPLEXITY_API_KEY, TAVILY_API_KEY, CONTEXT7_API_KEY, YDC_API_KEY; optional COMPRESS_TOKENIZER). Never commit .env (universal.md MUST 5: no secrets).

Proxy and TLS note (generic, not environment-specific): the stdio server is fetched by uvx on first launch, so a corporate proxy must allow uv's downloads and uv must trust the proxy CA. Use standard HTTPS_PROXY plus uv's system-certificate option (UV_SYSTEM_CERTS; the older UV_NATIVE_TLS name is deprecated as of uv 0.11.26). Never disable TLS verification.

Phase 5: Editor and LSP Reality

This repo prefers LSP-first navigation (ADR-062, .claude/rules/lsp-first.md): use Serena symbol tools over grep for code navigation. This is static steering now, not a runtime gate. The PreToolUse LSP gate and its environment escapes (SKIP_LSP_GATE, LSP_GATE_MODE, LSP_DOWN) were retired in #3216; no Read call is blocked and there is nothing to set.

Known Traps

Each row verified 2026-07-03. Longer stories live with the sibling skills ai-agents-failure-archaeology and ai-agents-debugging-playbook.

Verification

The 15-minute smoke checklist. All boxes checked means the environment works.

• uv run --frozen lefthook version prints 2.1.10
• uv run --frozen lefthook check-install exits 0
• uv run python -c "import yaml" exits silently (venv has project deps)
• uv run pytest tests/test_paths.py -q passes (28 passed, under 1 second, as of 2026-07-03)
• uv run ruff --version prints a version (0.15.16 as of 2026-07-03)
• python3 --version matches cat .python-version
• node --version prints v22.x, gh --version prints 2.60+, pwsh --version prints 7.5+
• .env exists locally (copied from .env.example) and is NOT tracked: git ls-files .env prints nothing
• Optional, requires network: the Serena MCP server starts (harness lists mcp__serena__* tools); if not, confirm the ADR-007 fallbacks in Phase 4 before proceeding

Anti-Patterns

• Following CONTRIBUTING.md or templates/README.md build instructions. They predate ADR-042; the pwsh commands cannot run.
• pip install anything, or uv pip install into the interpreter. PEP 668 blocks it; the venv from uv sync --frozen --extra dev is the environment.
• Pushing with --no-verify or recreating a skip flag for the pre-push hook. Escape hatches here get teeth or get abused (session 1187); skipping hooks is on the AGENTS.md Never list.
• Committing .env, or putting keys anywhere but env vars (universal.md MUST 5).
• Editing files with a CRLF editor profile. One CRLF save can break Copilot CLI YAML frontmatter parsing downstream.
• Treating a missing MCP server as a blocker. ADR-007 mandates graceful degradation: fall back per the Phase 4 table and keep working.
• Hand-fixing .venv contents or relying on whatever system python3 happens to resolve to. Re-run uv sync --frozen --extra dev instead.

Provenance and Maintenance

Authored 2026-07-03. All commands in this file were executed read-only against the repo on that date. Re-verify volatile facts before trusting them:

Maintenance rule: if any re-verify command disagrees with this file, the repo won. Update this skill in the same PR that changes the underlying fact. Do not touch .claude-plugin/plugin.json: the manifests carry no version (ADR-092, see ai-agents-change-control).