Metis Build Spec

---
name: metis-build-spec
description: Produce SYNTHESIS.md (final form) and BUILD.md (the ordered backlog of build items).
---

# $metis-build-spec

Produce the build's two standing files: `.metis/SYNTHESIS.md` in its final form (what is being built) and `.metis/BUILD.md` (the ordered backlog of items that build it).

## Preflight

Run this skill's `references/build-spec-preflight.sh` before drafting. It exits non-zero if `.metis/BUILD.md` already exists (surface the error, suggest the user delete the file manually if a fresh rewrite is intended, and stop). Otherwise it reports `DOCS_PRESENT`, `RECONCILE_DONE`, and `WALK_PENDING`.

## Input shape

Determined from the preflight + the trailing prompt:

- **Docs-first ready** — `DOCS_PRESENT=yes`, `RECONCILE_DONE=yes`, `WALK_PENDING=no`. Synthesize from the reconciled corpus.
- **Reconcile or walk pending** — `RECONCILE_DONE=no` or `WALK_PENDING=yes`. Suggest the prerequisite command (`$metis-reconcile` or `$metis-walk-open-items`) and proceed only if the user explicitly insists.
- **No docs** — `DOCS_PRESENT=no`. The trailing prompt is required; if absent, stop and ask. If present, classify as **prompt-seeded** (fresh project) or **existing-codebase** (delta on top of code in the repo) based on what the prompt describes.

## Load

- For docs-first: `.metis/SYNTHESIS.md`, `.metis/INDEX.md`, and the source docs under `docs/` at the cited passages.
- For existing-codebase: code from the source tree, via `metis-code-explorer` subagent dispatches.

## Do not load

- `.metis/CONTRADICTIONS.md`, `.metis/QUESTIONS.md`, `.metis/RESOLVED.md`.

## Read first

This skill's `references/writing-build-spec.md` — read before drafting.

## Write scope

Two files:

- **`.metis/SYNTHESIS.md`** — rewritten to its final standing form. When it already exists (docs-first, from reconcile), `Read` it before the `Write` so the overwrite succeeds on the first attempt.
- **`.metis/BUILD.md`** — created: the ordered backlog, every item under *To build*, *Built* empty.

## Invocation prompt

Trailing prompt: see this skill's `references/command-prompts.md`.

## Return

One message to the user:

- **Paths written** — `.metis/SYNTHESIS.md` (finalized) and `.metis/BUILD.md`, with the item count and a one-line naming of the first item.
- **Open assumptions** — anything an item committed to that the corpus did not settle, surfaced so the user can audit the bet before implementation begins.
- **Next step** — `$metis-plan-task "<first item title>"`. The first item under *To build* is the natural target.