Module Specs

Merlin’s own modules are specified in specs/. These are read by fledge spec check as part of the verify lane and serve as the source of truth when the agent is asked to modify them.

Active Specs

Module	File	Status	Description
`agent`	`specs/agent/agent.spec.md`	v2, draft	The agent state machine and its public API
`provider`	`specs/provider/provider.spec.md`	v1, draft	The `LlmProvider` trait and types
`fledge-protocol`	`specs/fledge-protocol/fledge-protocol.spec.md`	v1, draft	The fledge-v1 plugin protocol

Required Sections

Every spec must include:

Section	Purpose
`Purpose`	One paragraph: what this module exists to do
`Public API`	Tables of exported types, functions, traits
`Invariants`	Numbered list of properties the module must uphold
`Behavioral Examples`	Given/When/Then scenarios
`Error Cases`	Table of error conditions and behaviors
`Dependencies`	Other modules / crates this one depends on
`Change Log`	Version, date, changes

The agent spec also contributes the four sections that get injected into the LLM system prompt: Purpose, Invariants, Public API, Error Cases.

Adding a Spec

Create specs/<module>/<module>.spec.md with frontmatter:

---
module: mymodule
version: 1
status: draft
files:
  - crates/merlin-core/src/mymodule.rs

db_tables: []
depends_on: []
---

Add all required sections.
Register: fledge spec register specs/mymodule/mymodule.spec.md
Verify: fledge spec check

The agent will pick up new specs automatically — specsync-list returns whatever spec-sync knows about.

Stale Specs

fledge spec check does not automatically detect drift between spec text and code. Discipline matters: bump version, add a Change Log row, and update the API tables when the public API changes. The agent system prompt and the verify gate together make divergence expensive — the verifier will at minimum complain about missing sections; the LLM should refuse to violate the contract.

Notes

enforcement = "strict" in .specsync/config.toml means every code file in source_dirs (currently crates/, plugins/) must be referenced by some spec’s files: list. Untracked files fail the lane.
Companion files (requirements.md, tasks.md, context.md, testing.md) are warnings only — these are spec-sync extensions not currently used by Merlin.