A primitive's template is a skeleton of required slots, never a working example — it names the sections a valid instance must contain so validation hooks have something to structurally check.

Pattern

Template-Declared Contracts

The core distinction

Skeleton names slots. Example fills them.

Example as templatepoisons instances

# User Auth Feature

## User Story

As a user, I want to log in...

## Files

- src/auth/login.py

Copy-paste hazard. Readers ship "User Auth Feature" filler in their own plans. The template's content leaks into every instance.

Skeleton as templatedeclares a contract

# <Feature Title>

## User Story

As a <role>, I want <outcome>, so that <value>.

## Relevant Files

- <path> — <why>

Placeholders, not content. Readers see slots and fill them with their own material. The skeleton stays intact across every instance.

If the template contains content, the content becomes the convention. Slots stay inert.

How the contract enforces

Template declares — instance fills — hook validates.

Three roles, one chain. Drop any link and the contract evaporates.

📐

declares

template:

names the required sections, marks optionals

→

author fills

📄

instantiates

plan.md

real content in the named slots

→

hook checks

✓

validates

structure-gate.sh

required section present? else reject

Without the template, the hook has nothing to check — the contract becomes advisory prose.

Marking sections

Required is the default. Optional is explicit.

plan-primitive.md — frontmatter.template

skeleton

## Metadata

Always present — identity + lifecycle.

required

## Description

Always present — what the plan addresses.

required

## Validation Commands

Always present — how to prove it's done.

required

## User Story

Feature plans only — omit for bugs and chores.

optional

## Root Cause Analysis

Bug plans only — omit for features.

optional

The hook checks required presence. Optional sections are omittable without breaking the contract — but their trigger must be stated.

The pattern, everywhere

Every primitive in the KG declares one.

Plan

MetadataDescriptionRelevant FilesStep-by-Step TasksValidation CommandsUser StoryRCA

Command

VariablesInstructionsRelevant FilesFormatReport

Hook

event-receivevalidateexit-code

Absence of a concrete template is how primitives stay vague. The pattern is not aesthetic — it's what makes instances checkable.

What breaks when you violate it

Three anti-patterns. All produce drift.

Example as template

Template contains a real feature's content: User Auth, src/login.py.

Filler leaks into every downstream instance. Every plan looks like a remix of the template's example.

Prose as template

Template says "describe your feature here" — no structural contract.

Instances drift. Authors invent their own sections; no two plans have the same shape.

Unnamed required sections

Template lists sections loosely without marking which are mandatory.

Hook has nothing to check. Contract becomes advisory — enforcement is impossible.

Each anti-pattern destroys a different link: the skeleton, the shape, or the gate.

The discipline

A template is a contract, not a sample.

Name the slots, mark the optionals, let the hook enforce the rest. The skeleton describes the shape of a valid instance — it does not show you one. That's what instances are for.