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

1. 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: []
   ---

2. Add all required sections.

3. Register: fledge spec register specs/mymodule/mymodule.spec.md

4. 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.