Ai agents build and env

ai-agents Build and Environment Runbook

<!-- vendor-portability: contributor-facing knowledge pack for the rjmurillo/ai-agents repo itself; intentionally references upstream paths (.agents/, .claude/, scripts/, build/) because its audience is repo contributors, not plugin consumers (issue #2050) -->

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:

You want	Use instead
Regenerate mirrors, run the drift gates, release	ai-agents-generation-and-release
Understand what counts as test evidence, run CI-equivalent gates	ai-agents-validation-and-qa
Full catalog of env vars, skip markers, escape hatches	ai-agents-config-catalog
Triage a failing hook, gate, or test	ai-agents-debugging-playbook

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.

Tool	Floor	Verify
uv	Must resolve the .python-version pin (old container uv builds cannot; reinstall via the astral.sh standalone installer, never uv self update, which hits GitHub API rate limits on shared egress IPs)	uv python list "$(cat .python-version)" prints a row
Python	Exactly the .python-version pin, installed by uv	python3 --version
Node.js	22 LTS (NODE_MAJOR=22 in scripts/bootstrap-vm.sh:40; AGENTS.md floor says "Node LTS")	node --version
PowerShell	7.5.4+ per AGENTS.md Stack. Note: zero .ps1 files remain in the repo (ADR-042 Python migration), so pwsh is rarely exercised, but the floor is still declared	pwsh --version
gh CLI	2.60+ per AGENTS.md Stack	gh --version
git, jq, curl	any recent	git --version

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 config edits do not require another install.

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 three 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).

Server	Transport	Role	When absent
serena	stdio, uvx --from git+https://github.com/oraios/serena (port 24282, context claude-code)	Canonical memory (ADR-007) plus LSP symbol navigation	Memories stay readable as plain files under .serena/memories/ (122 files as of 2026-07-03). The LSP read gate that could misfire on code files was retired in #3216
forgetful	stdio, uvx forgetful-ai	Supplementary semantic memory search	ADR-007 fallback: use the Serena memory-index memory for keyword discovery. MUST NOT block work or skip memory retrieval because Forgetful is down (ADR-007 "Graceful degradation")
deepwiki	http, https://mcp.deepwiki.com/mcp	External GitHub repo documentation	No local impact; fall back to web search

Proxy and TLS note (generic, not environment-specific): the two stdio servers are 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.

Trap	Symptom	Fix
CONTRIBUTING.md build commands were DEAD before PR #2871	CONTRIBUTING.md:155 said build/Generate-Agents.ps1 PowerShell invocation until PR #2871 repointed it to build/generate_agents.py; zero .ps1 files exist in the repo (ADR-042)	Real commands: uv run python build/generate_agents.py and uv run python build/scripts/build_all.py
PEP 668: bare pip fails	pip install X errors with externally-managed-environment on uv-managed interpreters	Everything goes through uv: uv sync, uv add, uv run (scripts/bootstrap-vm.sh:118-123)
Skill scripts need the project venv	.claude/skills/github/scripts/pr/*.py import github_core, which imports yaml at load; bare python3 throws ModuleNotFoundError: No module named 'yaml' unless .venv/bin is first on PATH (bootstrap-vm.sh arranges that; a manual setup usually does not)	Run skill scripts with uv run python, which resolves the venv deterministically
Moving a worktree leaves the uv shebangs stale	Direct .venv/bin/pytest fails with "bad interpreter" after mv; the shebangs in .venv/bin/* (POSIX) or .venv/Scripts/* (Windows) still name the old worktree path (issue #3170)	Run scripts/maintenance/repair_worktree_venv.py with uv run python (or uv sync --frozen --extra dev --reinstall: --reinstall recreates the launchers a bare --frozen sync would leave stale, --extra dev keeps pytest/ruff/mypy, --frozen matches CI); prefer uv run python -m pytest for move-safe validation
Two floors, not one	pyproject.toml project.requires-python says requires-python = ">=3.14" (the dev/install contract), but plugin hooks run under the host's ambient interpreter, which may be older	Develop and test against .python-version (3.14.6). The blocking CI syntax gate parses every file at the hook-portability floor (3.10), NOT 3.14, so hooks stay portable to older hosts (issue #2655, decoupled from requires-python in issue #3008); see ai-agents-debugging-playbook
LF line endings enforced	CRLF in YAML frontmatter breaks the Copilot CLI parser (github/copilot-cli#694); .gitattributes:59 sets * text=auto eol=lf	Configure your editor for LF; never commit CRLF
Pre-push jobs can take minutes	Lefthook runs the named validators in lefthook.yml for matching push files	Budget minutes per push; do not attempt --no-verify (prohibited, AGENTS.md Never list)
Skill test locations differ	New tests belong in tests/skills/NAME/; legacy suites remain under .claude/skills/NAME/tests/	The default suite reaches legacy suites through tests/test_skill_bundle_suites_run.py. Invoke a legacy path directly only for targeted diagnosis; details in ai-agents-validation-and-qa

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: Serena and Forgetful MCP servers start (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:

Fact	Source	Re-verify
Python pin 3.14.6	.python-version	cat .python-version
requires-python >=3.14 install floor	pyproject.toml project.requires-python	grep -n requires-python pyproject.toml
Syntax-gate hook floor 3.10 (separate from install floor)	scripts/validation/validate_python_syntax.py _SUPPORT_FLOOR	grep -n _SUPPORT_FLOOR scripts/validation/validate_python_syntax.py
PyYAML 6.0.3 pin	pyproject.toml project.dependencies	grep -n PyYAML pyproject.toml
uv sync --frozen --extra dev is the canonical sync	scripts/bootstrap-vm.sh:114	grep -n "uv sync --frozen" scripts/bootstrap-vm.sh
Node 22 LTS	scripts/bootstrap-vm.sh:40	grep -n NODE_MAJOR scripts/bootstrap-vm.sh
pwsh 7.5.4+, gh 2.60+ floors	AGENTS.md Stack section	grep -n "gh 2.60" AGENTS.md
Zero .ps1 files (ADR-042)	repo tree	git ls-files "*.ps1" prints nothing
Stale pwsh commands	CONTRIBUTING.md:155,741	grep -n pwsh CONTRIBUTING.md
Git hook jobs, filters, and validators	lefthook.yml	uv run --frozen lefthook validate
MCP servers serena/deepwiki/forgetful	.mcp.json	cat .mcp.json
.env key names	.env.example	cat .env.example
Forgetful fallback table	ADR-007 (.agents/architecture/ADR-007-memory-first-architecture.md:108-130)	grep -n "Graceful degradation" .agents/architecture/ADR-007-memory-first-architecture.md
LF enforcement rationale	.gitattributes:59 and header comments	grep -n "eol=lf" .gitattributes
Serena memory file count (122)	.serena/memories/	python3 -c "from pathlib import Path; print(sum(1 for _ in Path('.serena/memories').iterdir()))"
tests/test_paths.py count (28)	pytest	uv run pytest tests/test_paths.py --collect-only -q
uv TLS var rename	uv 0.11.26 runtime warning	uv run python -c pass under UV_NATIVE_TLS

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).