night-market-build-and-env
Rebuild the dev environment: uv, Python tiers, pins, traps. Use when onboarding or toolchain breaks. Do not use for daily commands; use night-market-operations.
athola · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add athola/claude-night-market --skill night-market-build-and-envAbout this skill
name: night-market-build-and-env description: "Rebuild the dev environment: uv, Python tiers, pins, traps. Use when onboarding or toolchain breaks. Do not use for daily commands; use night-market-operations."
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 sta
Read the complete source ↗