Spec-Driven Development with Convention Files¶

A colleague spent forty minutes debugging a Terraform change that had been planned — and partially applied — in a chat thread the previous week. Nobody remembered the exact prompt, the reasoning had evaporated, and the agent's recommendation no longer matched the current state. The fix itself took five minutes. The archaeology took the rest.

That is the problem with AI-assisted work that lives in chat threads. The intent, the plan, the decisions, and the evidence all disappear the moment the conversation scrolls out of view.

Liatrio's Spec-Driven Development (SDD) workflow tackles this by keeping every stage of AI-assisted work in markdown artefacts that live in Git. Four prompts — specify, plan, implement, validate — turn a vague request into a reviewed spec, an audited task list, committed proof artefacts, and a final validation report. Everything is versioned, reviewable, and auditable.

If you already use convention files such as AGENTS.md, .prompt.md, .instructions.md, and .agent.md, the SDD prompts slot in naturally. This post explains how.

What SDD does¶

SDD is four markdown prompts. No dependencies, no tooling, no installation required. You paste a prompt into your AI assistant — or install them as slash commands — and the AI follows a structured workflow.

Step	Prompt	What it produces
1 · Specify	`SDD-1-generate-spec.md`	Scope check, clarification questions, specification with demo criteria
2 · Plan	`SDD-2-generate-task-list-from-spec.md`	Parent tasks, subtasks, baseline commit, planning audit gate
3 · Implement	`SDD-3-manage-tasks.md`	Single-threaded execution, checkpoints, proof artefacts before each commit
4 · Validate	`SDD-4-validate-spec-implementation.md`	Coverage matrix, proof verification, PASS/FAIL gates

Every artefact lands in docs/specs/[NN]-spec-[feature-name]/, giving you a lightweight, file-based backlog that travels with the repo.

The highest-leverage work happens in steps 1 and 2. When the spec is clear and the plan is audited, the implementation and validation steps are far more likely to run without human rescue.

Where SDD fits in the convention file taxonomy¶

SDD mapped to convention files

Convention files already solve "how should agents behave in this repo?" SDD addresses a different question: "how should agents approach a specific piece of work from start to finish?"

The mapping is straightforward:

Convention file	Role in SDD
AGENTS.md	Sets the baseline — naming conventions, quality gates, workflow steps. SDD prompts inherit this context.
.instructions.md	Path-scoped rules for language, framework, or infrastructure conventions. Applied automatically during the implement step.
.prompt.md	The SDD prompts themselves. Install them as slash commands in `.github/prompts/`.
.agent.md	Optional agent personas — a spec reviewer that only reads, an implementer with full tool access.
SKILL.md	Reusable capabilities the implementation step can invoke — e.g. a skill for running database migrations or generating Helm charts.

AGENTS.md and .instructions.md are always loaded. They form the standing instructions. The SDD .prompt.md files are invoked on demand — one per step. Agent personas are optional but useful for teams that want separation between planning and execution.

Adapting SDD prompts for your repos¶

The raw SDD prompts from Liatrio work out of the box, but they work better when they reference your repo's conventions. Here is how to wire them together.

1. Install the prompts as slash commands¶

The simplest approach uses Liatrio's slash-command-manager:

uvx --from git+https://github.com/liatrio-labs/slash-command-manager \
  slash-man generate \
  --github-repo liatrio-labs/spec-driven-workflow \
  --github-branch main \
  --github-path prompts/

This installs /SDD-1-generate-spec, /SDD-2-generate-task-list-from-spec, /SDD-3-manage-tasks, and /SDD-4-validate-spec-implementation as native slash commands in your editor.

Alternatively, copy each prompt into .github/prompts/ and they become VS Code .prompt.md slash commands automatically:

.github/prompts/
├── SDD-1-generate-spec.prompt.md
├── SDD-2-generate-task-list-from-spec.prompt.md
├── SDD-3-manage-tasks.prompt.md
└── SDD-4-validate-spec-implementation.prompt.md

2. Wire AGENTS.md into the spec step¶

Your AGENTS.md already defines workflow steps, quality gates, and naming standards. Reference it from the spec prompt so that SDD-1 inherits your conventions:

# AGENTS.md

## Workflow
1. Plan → scope, success criteria, risks
2. Build → implement with tests
3. Document → update runbooks
4. Release → owner sign-off + monitoring

## Quality gates
- Every change has an owner
- Risks documented before build
- Docs updated before release

## Standards
- Naming: <team>-<service>-<env>
- Environments: dev → staging → prod

## Spec-driven development
- Use `/SDD-1-generate-spec` for any change that spans more than one file
- Specs live in `docs/specs/`
- No implementation starts without an audited task list (SDD-2 gate)

That last section is the key addition. It tells agents (and humans) when to use the SDD workflow and where artefacts go.

3. Add path-scoped rules for the implement step¶

.instructions.md files apply automatically when the agent touches files matching a glob. During SDD-3 (implement), these keep the agent aligned with your language and framework conventions without repeating them in the SDD prompts:

---
applyTo: "infra/**/*.tf"
---
# Terraform conventions
- Use modules from the internal registry
- Tag all resources with team and environment
- No inline IAM policies

---
applyTo: "k8s/**/*.yaml"
---
# Kubernetes conventions
- All manifests use kustomize overlays
- No hardcoded image tags — use digest references
- Resource limits required on all containers

4. Add agent personas (optional)¶

For teams that want to separate planning from execution, add agent personas:

---
# .github/agents/spec-reviewer.agent.md
description: Reviews specs for completeness, ambiguity, and missing demo criteria
tools: ['search']
---
Review the spec at the path provided. Check for:
- Clear scope boundaries (what is in scope, what is not)
- Testable demo criteria
- Identified risks and mitigations
- Consistency with the AGENTS.md workflow

Do not propose implementation. Flag gaps only.

---
# .github/agents/implementer.agent.md
description: Implements tasks from an SDD task list
tools: ['search', 'editFiles', 'terminalLastCommand']
---
Implement the next incomplete task from the task list.
Follow the AGENTS.md conventions and any .instructions.md
rules that apply to the files being changed.

Before committing, create proof artefacts in the proofs directory.

SDD and operational workflows¶

If you have used our AGENTS.md approach for operational automation — querying work trackers, populating sprint review decks, updating dashboards — you might wonder how SDD fits alongside it.

The short answer: they are complementary and cover different shapes of work.

	SDD prompts	AGENTS.md operational agents
Work shape	Project-shaped: a feature, a migration, a new API endpoint	Ticket-shaped: recurring BAU tasks, data population, report generation
Trigger	Engineer invokes `/SDD-1-generate-spec` when starting a piece of work	Agent definition runs when the Copilot agent is asked to execute it
Artefacts	Specs, task lists, proof documents, validation reports	Updated PlantUML diagrams, Marp slides, dashboard metrics
Data source	The codebase itself + human intent	External systems (Jira, GitHub Issues, Azure DevOps)
Quality gate	Planning audit + validation coverage matrix	Human confirmation before each query

For platform engineering teams, SDD covers the development side — golden paths, self-service tooling, migration scripts, new capabilities. Operational agents cover the BAU side — sprint review decks, request metrics, team dashboards.

Both patterns live in the same repo, coexisting without conflict:

.github/
├── prompts/
│   ├── SDD-1-generate-spec.prompt.md
│   ├── SDD-2-generate-task-list-from-spec.prompt.md
│   ├── SDD-3-manage-tasks.prompt.md
│   └── SDD-4-validate-spec-implementation.prompt.md
├── agents/
│   ├── spec-reviewer.agent.md
│   └── implementer.agent.md
├── instructions/
│   ├── terraform.instructions.md
│   └── kubernetes.instructions.md
└── copilot-instructions.md

AGENTS.md              ← workflow + naming + gates
agents.md              ← operational agent definitions (tracker queries, deck population)
docs/specs/            ← SDD artefacts

What makes this approach work¶

Three things separate repos that use SDD effectively from repos where the prompts gather dust:

The spec step catches scope creep early. SDD-1 validates whether the work is too large, too small, or appropriately sized. Too large and it suggests splitting. Too small and it suggests implementing directly. This single check prevents the most common failure mode: a vague requirement that balloons during implementation.

The planning audit creates accountability. SDD-2 generates a task list and then audits it against the spec. If the tasks do not cover the demo criteria, or if they introduce scope the spec did not describe, the audit flags it. Implementation does not start until the audit passes and the engineer approves remediations.

Proof artefacts prevent "it works on my machine." SDD-3 requires proof artefacts — markdown files documenting what was done, what was tested, and what the results were — before each commit. These are not trophies. They are evidence that feeds the validation step and gives reviewers something concrete to check.

Context rot and verification markers¶

SDD includes an unusual feature: emoji markers (SDD1️⃣, SDD2️⃣, SDD3️⃣, SDD4️⃣) at the start of AI responses. These detect context rot — the silent degradation of AI performance as input context grows longer.

Context rot does not announce itself with errors. The agent simply stops following instructions. When the marker appears, it suggests the agent is still tracking the prompt. When the marker disappears, you know to check whether the agent has lost the thread.

This is a lightweight, no-tooling approach to a real problem. If you have run long conversations with AI agents, you have experienced context rot — you just may not have had a name for it.

Practical patterns worth borrowing¶

Even if you do not adopt SDD wholesale, several patterns are worth extracting for your own convention files:

Clarification-before-planning. SDD-1 can generate a questions file with recommended answers and justification notes before writing the spec. Your AGENTS.md can adopt this: "For changes spanning more than three files, the agent must list open questions and recommended answers before proposing a plan."

Audit gates. SDD-2's planning audit is a quality gate that runs before implementation. Any AGENTS.md can include a similar rule: "No implementation starts until the plan has been reviewed against the acceptance criteria."

Proof-before-commit. SDD-3 requires proof artefacts before each commit. Even without the full SDD workflow, you can add to AGENTS.md: "For significant changes, create a proof file in docs/decisions/ before committing."

Single-threaded execution. SDD-3 enforces working on one task at a time. This reduces work-in-progress and avoids the tangled state that comes from partially completed parallel tasks.

Getting started¶

The quickest path:

Read the SDD prompts — they are plain markdown, and the workflow logic is transparent
Install them as slash commands or copy into .github/prompts/
Add a "Spec-driven development" section to your AGENTS.md
Try it on one feature and see whether the spec-then-plan-then-build cadence reduces rework

The prompts are Apache 2.0 licensed and work with any AI assistant. They are not a product — they are a workflow encoded in markdown. Adapt them, extend them, or simply borrow the patterns that fit.