installation

name	installation
description	Draft, review, and revise experiential / installation-art concept proposals using the standard anvil lifecycle.
domain	installation
type	skill
user-invocable	false

anvil:installation — Experiential / installation artwork

The installation skill produces defensible concept proposals for experiential and installation artwork — one-of-a-kind placed art whose value is conceptual, perceptual, and architectural (no commercial model, no TAM, no investor ask). It runs the canonical anvil lifecycle: draft → review → revise → figures, with revise looping to review until the rubric threshold is met or the iteration cap is reached.

These artifacts are memo-shaped — a LaTeX prose document with callouts, spec/budget tables, hero images, and an Open Decisions close. The lifecycle, state machine, and rubric format mirror anvil:memo exactly; the LaTeX template + figures + examples + tests scaffolding mirrors anvil:paper and anvil:ip-uspto (the LaTeX-producing skills). Only the section template and rubric dimensions are specific to installation art.

Artifact contract

An installation thread is a single concept proposal for one piece, authored across one or more revisions. A thread is identified by a slug (e.g., quiet-place, cloud-chamber). Each thread occupies a portfolio directory that contains:

<portfolio>/
  <thread>/                Optional thread root with brief and reference material
    BRIEF.md               Optional structured or freeform brief (frontmatter + prose)
    refs/                  Optional reference material (precedent images, site plans, transcripts)
  <thread>.1/              First drafted version (immutable once written)
    installation.tex       Proposal body (XeLaTeX; uses templates/anvil-installation.cls)
    figures/               Hero renders, interiors, site plans, light studies referenced from body
    _progress.json         Phase state for this version
    changelog.md           (revisions only) Maps prior critic notes to changes
  <thread>.1.review/       Reviewer output for version 1 (read-only)
    verdict.md             Top-level decision (advance / block) + total /44
    scoring.md             Per-dimension scores against the installation rubric
    comments.md            Line-level comments keyed to installation.tex
    _meta.json             { critic, scorecard_kind: "human-verdict", ... } (see lib/snippets/scorecard_kind.md)
    _progress.json         Phase state for the reviewer
  <thread>.1.critic/       Optional substantive critic sibling (e.g., a spatial or ethics specialist)
  <thread>.2/              Revised version (after revise consumes v1 + all critic siblings)
  <thread>.2.review/
  ...
  <thread>.{N}/            Terminal version, marked READY in its _progress.json

Versioned dirs (<thread>.{N}/) and critic sibling dirs (<thread>.{N}.<critic>/) are immutable once their _progress.json records the phase as done. Revisions are produced as a new version dir, never by editing in place.

State machine

Per-thread state, derived from on-disk evidence (not flags):

EMPTY → DRAFTED → REVIEWED → REVISED → … → READY
                                          ↘ AUDITED  (optional, via auditor critic sibling)

State	Evidence
EMPTY	No <thread>.{N}/ directories exist
DRAFTED	Latest <thread>.{N}/ exists with installation.tex and _progress.json.draft == done; no sibling review at the same N
REVIEWED	<thread>.{N}.review/verdict.md exists for the latest N
REVISED	A <thread>.{N+1}/ exists after a prior <thread>.{N}.review/
READY	Latest <thread>.{N}.review/verdict.md records advance: true AND no unresolved critical flag
AUDITED	<thread>.{N}.audit/ exists alongside a READY version

Thresholds: ≥35/44 advances. <35/44 requires revision. Any critical flag short-circuits regardless of total — block until addressed.

Iteration cap: default max_iterations: 4 (so worst-case terminal version is <thread>.5/). The cap is configurable per-thread by writing { "max_iterations": <N> } to <thread>/.anvil.json in the thread root. Exceeding the cap marks the thread BLOCKED (in the portfolio orchestrator's report) and requires human review.

Command dispatch

Command	Role	Reads	Writes
installation	portfolio orchestrator	all <thread>.* dirs under cwd	(none; reports state per thread + recommends next command)
installation-draft <thread>	drafter	<thread>/BRIEF.md (+ <thread>/refs/); for revisions, also <thread>.{N}/ + all <thread>.{N}.*/ siblings	<thread>.1/ (or <thread>.{N+1}/ on revise-from-feedback path; see installation-revise)
installation-review <thread>	reviewer	latest <thread>.{N}/	<thread>.{N}.review/
installation-revise <thread>	reviser	latest <thread>.{N}/ + all <thread>.{N}.*/ critic siblings	<thread>.{N+1}/ with changelog.md
installation-figures <thread>	figurer	latest <thread>.{N}/installation.tex	renders/stubs under <thread>.{N}/figures/

The portfolio orchestrator is the user-facing entry point for status; the four lifecycle commands are dispatched from it (or invoked directly by the orchestrating agent).

Renderer

LaTeX via the shipped templates/anvil-installation.cls class. PDFs are produced by XeLaTeX (xelatex installation.tex), not pdflatex — the class uses fontspec for system fonts (Helvetica Neue, with a documented Latin Modern Sans fallback so it compiles on a stock TeX Live install). The installation.tex.j2 template is the canonical 11-section skeleton; the drafter elaborates each section into prose, tables, and figure references.

Progress tracking

Each <thread>.{N}/ directory contains _progress.json recording phase state. The canonical schema, read-merge-write recipe, and crash recovery contract live in anvil/lib/snippets/progress.md (in an installed consumer repo: .anvil/anvil/lib/snippets/progress.md); every command in this skill follows that convention.

Version-dir sample (no for_version — that field is only on critic siblings):

{
  "version": 1,
  "thread": "<thread>",
  "phases": {
    "draft":   { "state": "done",        "started": "2026-05-29T14:00:00Z", "completed": "2026-05-29T14:12:00Z" },
    "figures": { "state": "in_progress", "started": "2026-05-29T14:15:00Z" }
  },
  "metadata": {
    "iteration": 1,
    "max_iterations": 4
  }
}

Critic-sibling sample (adds for_version naming the version critiqued):

{
  "version": 1,
  "thread": "<thread>",
  "for_version": 1,
  "phases": {
    "review": { "state": "done", "started": "<ISO>", "completed": "<ISO>" }
  }
}

Phase states: pending, in_progress, done, failed. Validation is by file existence (does installation.tex exist? does the figure referenced as figures/hero.png exist?), not by flag — _progress.json is a resume hint, not a source of truth. A phase that crashed mid-write should be re-runnable from pending after deleting any partial output.

Critic siblings (e.g., <thread>.{N}.review/) follow the human-verdict scorecard kind documented in anvil/lib/snippets/scorecard_kind.md: they emit verdict.md + scoring.md + comments.md for human consumption. A _meta.json with {"scorecard_kind": "human-verdict"} is recommended (the default if _meta.json is absent). This is the same triple the legacy adapter in anvil/lib/critics.py (LEGACY_MEMO_FILES) already reads — no schema changes are introduced by this skill.

Rubric

See rubric.md for the 9-dimension /44 scoring schema, the ≥35 advance threshold, and the critical-flag short-circuit policy. The dimensions are tuned for installation art (conceptual coherence, spatial resolution, sensory language, visitor experience, buildability, ethics & safety, references & lineage, open decisions, rhetorical economy), not for an investment recommendation.

Skill-specific phases

None. The installation lifecycle is exactly draft → review → revise → figures. There is no pre-draft research phase and no separate audit phase in v0 — following anvil:memo, fact/feasibility checking is rolled into the reviewer's buildability and ethics dimensions. An auditor sibling critic can be added later by an installing repo without changing this skill's contract.

installation-review render-gate hook (deterministic pre-flight). installation-review runs a deterministic render-gate pre-flight via anvil/lib/render_gate.py (the LaTeX-skill analog of marp_lint for the deck/slides skills). The gate checks page count (page_cap=None — installation proposals run long; consumers can override per-thread via <thread>/.anvil.json: render_gate.page_cap), overfull boxes (>5.0pt threshold), compile success (xelatex), and source-side placeholders (TODO / [TBD] / (figure) / .MISSING). This is the first command in the installation lifecycle to invoke the LaTeX compiler — no upstream command produces installation.pdf; the gate triggers xelatex via compile_and_gate(...) and gates the resulting PDF + log in one step. On engine-unavailable (xelatex not on PATH), the gate degrades gracefully and the review proceeds. On failure, the gate emits a typed Review(kind=tool_evidence) with one CriticalFlag per failed gate dimension, which the existing anvil/lib/critics.py::compute_verdict path treats as BLOCK. See commands/installation-review.md step 4b.

An installation-vision critic (rendered-artifact review of hero renders, site plans, and light studies) is a valuable future addition but is out of scope for v0: it depends on anvil/lib/render.py / vision.py, which are not yet on disk, and wiring it would violate the "no anvil/lib/ changes" scope guard. It is tracked as a follow-up to #30.

Defaults and overrides

This skill ships with opinionated defaults. Consumers are expected to override liberally via .anvil/skills/installation/ in their own repo:

• voice.md (optional) — Studio or curator voice/style guidance the drafter reads in addition to its base prompt.
• rubric.overrides.md (optional) — Add domain-specific critical-flag examples or adjust the open-ended "any deal-breaker" instruction.
• templates/anvil-installation.cls (optional) — A replacement LaTeX class (e.g., a studio house style or a different signature font).
• BRIEF.md.example — Reference brief shape; freeform prose with optional YAML frontmatter is accepted (see templates/BRIEF.md.example).

Git sync hook (opt-in, off by default)

Consumers running anvil under an external orchestrator (a sphere channel-agent, a Loom-style daemon) can opt in to a per-phase git commit hook so every lifecycle phase leaves the working tree clean: a repo-level .anvil/config.json with git.commit_per_phase: true (and optionally git.push: true) has each write-bearing installation command end its phase by staging only the dirs it wrote and committing as anvil(installation/<phase>): <thread>.{N} [<state>]. The full contract — knob shape, defaults-off rule, commit-message format, staging scope, warn-and-continue failure semantics, and ordering after the _progress.json done write and the #350 sidecar atomic rename — lives in anvil/lib/snippets/git_sync.md (.anvil/anvil/lib/snippets/git_sync.md in an installed consumer repo). All 4 write-bearing installation commands adopt it; the read-only installation portfolio orchestrator is exempt by definition. When .anvil/config.json is absent or the knob is false, behavior is byte-identical to a pre-#426 install — the hook is default off.