Prompt Frontmatter

# Domain Model: Meta-Prompt Frontmatter Schema

**Status: Transformed** — Rewritten for meta-prompt frontmatter (ADR-045). Section targeting removed.

**Domain ID**: 08
**Phase**: 1 — Deep Domain Modeling
**Depends on**: None — first-pass modeling (defines schema consumed by domains 02, 03, 05, 06, 07)
**Last updated**: 2026-03-14
**Status**: transformed

---

> **Implementation Note:** This domain model describes the pre-meta-prompt frontmatter schema. The current meta-prompt frontmatter schema is defined in `docs/v2/data/frontmatter-schema.md` (authoritative). The following fields/features from this domain model are NOT in the current schema and should NOT be implemented:
> - `reads` with section-targeted syntax (`SectionTargetedRead`) — current `reads` field uses step names only (per ADR-050/053)
> - `artifact-schema` field with `required-sections`, `id-format`, `index-table`, `min-count`
> - `requires-capabilities` field with platform capability matrix
>
> Current meta-prompt frontmatter fields: `name`, `description`, `phase`, `order`, `dependencies`, `outputs`, `conditional`, `knowledge-base`, `reads` (optional, step names only).

## Section 1: Domain Overview

The Meta-Prompt Frontmatter Schema domain defines the YAML metadata contract that every meta-prompt file in the `pipeline/` directory must satisfy. Frontmatter is the declarative interface between meta-prompt authors and the scaffold CLI — it tells the assembly engine what a step depends on, what it produces, what knowledge base entries to load, and whether the step is conditional.

The frontmatter schema has been rewritten for the meta-prompt architecture. The previous fields (`reads` with section targeting, `artifact-schema`, `requires-capabilities`, mixin markers) have been removed. The new schema fields are:

- `name` — Step identifier (e.g., `system-architecture`)
- `description` — One-line purpose
- `phase` — Pipeline phase (pre, 1-10, validation, finalization)
- `dependencies` — Steps that must complete first (string array)
- `outputs` — Artifact paths this step produces (string array)
- `conditional` — `"if-needed"` or null; controls whether the step is evaluated for relevance
- `knowledge-base` — Knowledge base entries to load during assembly (string array)

**Role in the v2 architecture**: Frontmatter is the metadata glue that enables the assembly engine and pipeline management:

- **Dependency resolution** ([domain 02](02-dependency-resolution.md)) reads `dependencies` to build the execution DAG.
- **Pipeline state machine** ([domain 03](03-pipeline-state-machine.md)) reads `outputs` for completion detection and step gating.
- **Assembly engine** reads `knowledge-base` to load relevant domain expertise during prompt assembly.
- **Platform adapters** ([domain 05](05-platform-adapters.md)) use frontmatter to generate platform-specific wrapper files.
- **Brownfield/adopt** ([domain 07](07-brownfield-adopt.md)) uses `outputs` to map existing files to completed steps during detection.

**Central design challenge**: Frontmatter must be simple enough for meta-prompt authors to write by hand, yet precise enough for machine parsing and validation. The simplified schema reduces the barrier to adding new pipeline steps while maintaining enough structure for the assembly engine and dependency resolver to function correctly.

---

## Section 2: Glossary

**frontmatter** — YAML metadata enclosed in `---` delimiters at the top of a prompt file. Parsed before the prompt body. All fields except `description` are optional for built-in prompts; all fields are optional for custom prompts.

**prompt file** — A markdown file containing frontmatter and prompt body text. One of four types: base prompt, override prompt, extension prompt, or custom prompt.

**base prompt** — A prompt file in the `base/` directory, shared across methodologies. Uses abstract task verbs and mixin insertion points.

**override prompt** — A prompt file in a methodology's `overrides/` directory that replaces a base prompt of the same slug.

**extension prompt** — A prompt file in a methodology's `extensions/` directory with no base equivalent. Exists only within that methodology.

**custom prompt** — A user-provided prompt in `.scaffold/prompts/` (project-level) or `~/.scaffold/prompts/` (user-level). Either overrides a built-in prompt (same slug) or adds a new prompt (listed in `extra-prompts`).

**section targeting** — The mechanism by which the `reads` field specifies individual sections of a predecessor document to extract, rather than loading the entire file. Reduces context window consumption.

**section extraction** — The algorithm that, given a file path and a list of heading texts, returns the content under those headings. The core algorithm of this domain.

**artifact schema** — A validation DSL declared in frontmatter under `artifact-schema` that defines the expected structure of produced artifacts. Checked by `scaffold validate`.

**tracking comment** — An HTML comment on line 1 of a produced artifact that records the prompt name, version, date, and methodology/mixin context. Separate from frontmatter (tracking comments are in *artifacts*, frontmatter is in *prompts*).

**predecessor artifact** — A file produced by a prompt earlier in the pipeline that the current prompt reads as input. Referenced via the `reads` field.

**capability** — A platform-level feature that a prompt declares it needs via `requires-capabilities`. Platform adapters check these declarations against platform support.

**effective source** — The final prompt file selected after applying the customization precedence chain (project-custom > user-custom > built-in). Its frontmatter is merged with the built-in's frontmatter per the merge rules.

---

## Section 3: Entity Model