athola night-market-build-and-env
Recreate a working claude-night-market development environment from a bare machine, verify it in under an hour, and avoid the traps that have broken it before. Everything below was verified against the repo on 2026-07-02 (v1.9.15).
One rule dominates: every Python tool runs through uv run. uv is
Astral's Python package and environment manager. On first uv run it
creates .venv/ and syncs it from uv.lock. Never install repo
dependencies with bare pip.
Toolchain setup
Install in this order. "via uv" means the tool resolves from uv.lock
automatically. There is no manual install step for those rows.
| # | Tool | Required? | Install hint | Verify command |
|---|---|---|---|---|
| 1 | uv | REQUIRED | official installer at astral.sh/uv | uv --version |
| 2 | Python 3.12 | REQUIRED | uv python install 3.12 |
python3 --version |
| 3 | make + bash | REQUIRED | distro package (build-essential, Xcode CLT) | make --version |
| 4 | ruff >=0.14.13 | via uv | none (dev dependency in uv.lock) |
uv run ruff --version |
| 5 | bandit | via uv | none (pre-commit env is pinned separately, see traps) | uv run bandit --version |
| 6 | mypy >=1.13 | via uv | none | uv run mypy --version |
| 7 | pre-commit >=4 | via uv | uv run pre-commit install |
uv run pre-commit --version |
| 8 | Python 3.9 | optional | uv python install 3.9 |
uv venv --python 3.9 /tmp/py39-check |
| 9 | node + npm | optional | needed for conjure Gemini delegation | node --version |
| 10 | Rust + cargo | optional | rustup (only for make skrills-build) |
cargo --version |
| 11 | skrills binary | optional | make skrills-build or make skrills-install |
make skrills-verify |
| 12 | mdbook | optional | cargo install mdbook; builds book/ |
mdbook --version |
| 13 | gh CLI | optional | cli.github.com (releases and Discussions) | gh --version |
Notes on the optional rows:
- Python 3.9 is ONLY for local hook-compatibility testing. Hooks are
scripts Claude Code runs on tool events under the host system Python
(macOS ships 3.9.6), outside any virtual environment. CI enforces
this in
.github/workflows/python39-compat.yml. - The conjure plugin delegates to Gemini. The root
package.jsonpins@google/gemini-cliat^0.25.1. Runnpm installat the repo root only if you use conjure delegation. - skrills is a Rust CLI that validates and analyzes skill files. Every
Makefile target that uses it (
make validate-skills,make analyze-skills) has a Python fallback, so you can skip Rust entirely. - gh is needed for releases and for GitHub Discussions. Discussions
have no
gh discussionsubcommand. They are reachable only throughgh api graphql.
Version numbers observed on the reference machine (2026-07-02):
uv 0.8.22, Python 3.12.3, ruff 0.14.13, mypy 1.19.1, bandit 1.9.2,
pre-commit 4.5.1. Newer versions of uv are fine. The ruff version must
match uv.lock (see traps).
First-hour verification sequence
Run these in order after installing rows 1-3 above. Each step lists the output shape that means success.
Step 1: clone and check uv.
git clone git@github.com:athola/claude-night-market.git
cd claude-night-market
uv --version
Expected: a single line like uv 0.8.22. Any 0.8+ version works. CI
pins astral-sh/setup-uv@v8.2.0.
Step 2: validate all plugin structures (also proves the venv syncs).
make validate-all
Expected: one block per plugin (26 directories) shaped like:
>>> Validating plugins/abstract:
Plugin Validation Report: abstract
...
OK Plugin validation passed
Blue "Recommendations" lines are advisory and fine. A red failure line
or (validation failed) is not.
Step 3: run one fast plugin test suite.
make -C plugins/leyline test
Expected: verbose pytest output ending with a coverage table and a
summary like 710 passed, 6 warnings in 9.96s (counts and timing
drift, but zero failures is the invariant). This proves uv run, pytest,
and per-plugin coverage thresholds all work.
Step 4: install the git hooks.
uv run pre-commit install
Expected: pre-commit installed at .git/hooks/pre-commit. From now on
commits run the full hook chain (file validation, bandit, ruff, mypy,
changed-plugin tests, structure validation). Never bypass it with
--no-verify; CONSTITUTION.md forbids that.
If any step fails, load night-market-debugging-playbook.
Python version tiers
This is the number-one onboarding misconception. The README says "Python 3.9+ for hooks", and newcomers read that as "the repo runs on 3.9". It does not. There are three tiers:
| Tier | Version | Enforced by | Why |
|---|---|---|---|
| Root tooling (pytest, ruff, mypy) | 3.12 | root pyproject.toml requires-python = ">=3.12", ruff target-version = "py312", mypy python_version = "3.12" |
dev toolchain runs inside the uv venv |
| Plugin packages | varies, 3.9 to 3.12 | each plugins/<name>/pyproject.toml |
plugins are independent deployables (ADR-0001) |
| Hook import chains | 3.9 | .github/workflows/python39-compat.yml |
hooks run under the HOST system Python (macOS 3.9.6), outside any venv |
Per-plugin requires-python as of 2026-07-02 (22 of 26 plugin dirs
have a pyproject.toml):
- 3.12: abstract, conjure (also
<3.14), imbue, leyline, minister, sanctum, scry - 3.10: attune, conserve, hookify, memory-palace, parseltongue, pensive, scribe, spec-kit
- 3.9: archetypes, egregore, gauntlet, herald, oracle, phantom, tome
Why the hook tier exists: Claude Code executes hook scripts with
whatever interpreter the host provides, not the repo venv. A hook file
AND everything it transitively imports must therefore stay
3.9-compatible, even inside a plugin whose package requires 3.12. CI
enforces this with two gates in python39-compat.yml: gate 1 runs
ruff check --select UP007 --target-version py39 on hook files (bare
X | Y union annotations), gate 2 builds a real 3.9 venv with
uv venv --python 3.9 and runs hook tests with
--override-ini="addopts=".
Consequences you must respect in hook-reachable code:
- Use
timezone.utc, neverdatetime.UTC(a 3.11+ alias). The root ruff config extend-ignores UP017 specifically so autofix does not reintroduce the alias. This break recurred three times before the ignore plus an AST guard test held the line. - Guard third-party imports (
yaml,anthropic) in hook entrypoints. The system interpreter has none of the repo's dependencies, and an unguarded import makes every git commit emit ModuleNotFoundError.
Known traps
| Trap | Symptom | Fix or guard |
|---|---|---|
setup-uv@v8 bare tag |
CI fails: the bare v8 tag does not exist upstream |
pin exact tag astral-sh/setup-uv@v8.2.0 (commit f81d89a5). Guard: scripts/check_pinned_versions.py |
| bandit 1.9+ under system 3.9 | pre-commit bandit hook env fails to install | .pre-commit-config.yaml pins rev: 1.8.6, the last release supporting 3.9 (commit 25bf5a9d). The project-venv bandit (1.9.x via uv run) is a different install and is fine |
stale .uv-tools binary shadows ruff |
bare ruff reports an old version (0.7.3 observed) and disagrees with CI |
root Makefile sets UV_TOOL_DIR ?= $(abspath .)/.uv-tools and prepends .uv-tools/ruff/bin to PATH. Always lint via make lint or uv run ruff, never bare ruff. Guard: scripts/check_ruff_version.py compares uv.lock to PyPI |
| root pytest silently skips plugins | uv run pytest at the root collects only tests/, never plugin tests |
root pyproject.toml sets norecursedirs = ["plugins/*", ...] on purpose (root conftest.py documents ImportPathMismatchError). Run make -C plugins/<name> test or make <name>-test |
| imbue coverage artifacts | every pytest run in plugins/imbue writes htmlcov/, coverage.xml |
imbue's pytest addopts force --cov=scripts with term, html, and xml reports. Artifacts are gitignored. Expect them and never commit them |
make skrills-build fails |
Error: skrills repo not found at $HOME/skrills |
SKRILLS_REPO defaults to $(HOME)/skrills. Set SKRILLS_REPO=/path/to/skrills or skip: make validate-skills falls back to a Python checker when no skrills binary exists |
| plugins run from a cache dir | plugin hook cannot find a file by relative path | installed plugins execute from the Claude Code cache dir, not the repo. Hooks must never use paths relative to the current working directory |
When NOT to use
- Daily test, lint, release, and publish commands: use night-market-operations. This skill only bootstraps the machine.
- A previously working environment started failing: use night-market-debugging-playbook first to triage the symptom.
- Configuration axes, env vars, and their defaults beyond setup
(
VOW_SHADOW_MODE, quality gates): use night-market-config-catalog. - Plugin, skill, and hook mechanics (how the pieces work rather than how to install the tools): use claude-code-plugin-reference.
Exit Criteria
-
uv --versionprints a version at the repo root. -
uv run ruff --versionprints theuv.lockversion (0.14.13 as of 2026-07-02), not the.uv-toolsversion. -
make validate-allprintsPlugin validation passedfor every plugin and no(validation failed)lines. -
make -C plugins/leyline testends withN passedand zero failures, plus a coverage table. -
uv run pre-commit installcreated.git/hooks/pre-commit. - The reader can state why hook code is 3.9-constrained while root tooling requires 3.12 (hooks run under the host system Python).
Provenance and maintenance
Compiled 2026-07-02 against repo v1.9.15 (branch discussions-fix-1.9.14). Observed tool versions and test counts in this file are snapshots and will drift. Re-verify with:
- Root Python floor:
rg -n "requires-python" pyproject.toml - Per-plugin floors:
rg -n "requires-python" plugins/*/pyproject.toml - Locked ruff version:
rg -n -A1 'name = "ruff"$' uv.lock - setup-uv pin:
rg -n "setup-uv" .github/workflows/*.yml - bandit pin:
rg -n -B2 "id: bandit" .pre-commit-config.yaml - Makefile defaults:
rg -n "UV_TOOL_DIR|SKRILLS_REPO \?=" Makefile - Root pytest exclusion:
rg -n "norecursedirs" pyproject.toml - imbue coverage addopts:
rg -n -A8 "addopts" plugins/imbue/pyproject.toml - gemini-cli pin:
rg -n "gemini-cli" package.json - Leyline test count drift:
make -C plugins/leyline test
Source: athola/claude-night-market → .claude/skills/night-market-build-and-env/SKILL.md