Prompt Metadata: Enforcing the DevSpark Constitution

Natural language is inherently ambiguous. Writing "DO NOT use raw SQL queries" in a prompt and writing it in capital letters and writing it three times produces the same result: a strong signal that the AI agent will probably respect most of the time. That "probably" and "most of the time" is where governance breaks down.

The insight that shaped DevSpark's metadata approach is that governance through natural language instruction is fundamentally different from governance through structural constraint. You can tell a junior engineer not to push directly to main — or you can configure branch protection that makes it impossible. The former relies on compliance; the latter enforces it mechanically. For constraints that are genuinely non-negotiable, mechanical enforcement is the right answer.

DevSpark's frontmatter-driven contracts are the mechanical enforcement layer for the framework's architectural rules.

What Frontmatter Governs

Every DevSpark spec artifact — the output of /devspark.specify — is a Markdown file with a YAML frontmatter block. Starting in v1.5.0, that frontmatter became authoritative. The plan, tasks, implement, analyze, and critic commands all treat spec frontmatter as the source of truth for what the spec is about and what constraints apply to it.

The frontmatter declares metadata that flows through the entire pipeline:

Status: Draft
route: full-spec
constitution_version: 2.1.0
target_framework: .NET 9
test_requirement: xUnit

When /devspark.plan reads a spec, it reads the frontmatter first. If the spec declares test_requirement: xUnit, the plan knows to generate xUnit test tasks rather than making an assumption. If it declares a specific constitution_version, the plan can flag if the working constitution has evolved past what the spec was written against — a signal to revisit the requirements before implementation begins.

This is what "spec frontmatter as authoritative metadata" means in practice: the commands downstream of specification don't assume generic patterns or make technology choices themselves. They read what the spec declared and operate within those constraints. The frontmatter is the specification's formal commitment to what the implementation must deliver.

The Spec Lifecycle Enforcement

The most consequential metadata field is Status. In DevSpark v1.4.0, the spec lifecycle became formally enforced across all commands:

Draft — created by /devspark.specify, not yet ready for implementation. PR reviews that encounter a Status: Draft spec on a feature branch block approval.

In Progress — set by /devspark.implement at the start of implementation. Signals that active development is underway against this spec.

Complete — set by /devspark.implement when all spec tasks are checked. Required for /devspark.release to archive the spec and for /devspark.pr-review to approve feature branch PRs.

The enforcement is mechanical, not advisory. The PR review command actually reads the spec file, checks the Status field, and blocks approval if the spec isn't Complete. The release command checks before archiving. The site audit flags Draft or In Progress specs on the main branch as CRITICAL findings.

What this prevents is shipping implementations that have drifted from their specifications — which is how "we planned this" gradually becomes "we planned something that vaguely resembled this." The spec lifecycle creates a traceable chain: this code was built to this spec, the spec was fully checked off, the PR confirmed it.

ADR-001 and the Tiered Architecture Contract

DevSpark v2.1.0 formalized the architectural principles behind all of this in ADR-001: Tiered Prompt and Workflow Architecture. The decision record documents the two-tier ownership model, the resolution order, the constraint inheritance rules, and the design rationale in a format that I can reference when questions arise about why the system works the way it does.

The key constraint from ADR-001: lower tiers can extend or strengthen upper-tier rules, but cannot weaken or override them. A project-level override can add a stricter test coverage requirement. It cannot reduce the framework baseline's minimum. A user-scoped personalization can change the emphasis of a command's output. It cannot change what the constitution mandates that output must satisfy.

This non-weakening constraint is what makes the multi-tier system trustworthy. Without it, the constitution would be an aspirational document — guidelines that could be opted out of by anyone with access to the override directories. With it, the constitution is a structural floor. Overrides build on top of it; they can't dig beneath it.

Metadata as Governance Infrastructure

The pattern across all of these mechanisms — frontmatter contracts, spec lifecycle enforcement, tiered constraint inheritance — is the same: converting natural language guidelines into structured, machine-readable declarations that the framework enforces rather than merely communicates.

This is worth naming explicitly because it runs counter to how most AI-assisted development tooling is designed. The default pattern in the field is to write better prompts — more detailed instructions, more explicit examples, more emphatic warnings. DevSpark's approach is to write the constraints into the structure itself, so the framework enforces them regardless of how the prompt is phrased or interpreted.

The analogy that captures the difference: a code review checklist that a reviewer consults manually versus a CI pipeline that fails the build if the checklist conditions aren't met. Both communicate the same requirements. Only one enforces them consistently, at every PR, regardless of reviewer attention or memory.

Prompt metadata is DevSpark's CI pipeline for architectural governance. It's not a substitute for good prompts — the content still has to guide the AI toward the right solution. But for the rules that are genuinely non-negotiable, structural enforcement is the right tool, and natural language instruction is not.