Why semantic structure matters
A good Markdown specification can be excellent. Semantic structure matters when its meaning must survive authoring, review, adaptation, distribution, and implementation.
The problem is not Markdown
A capable model can build useful software from a prompt, and a well-authored Markdown specification can be an excellent implementation input. SeedSpec does not assume that adding files or YAML automatically improves either one.
The harder problem appears when product and domain knowledge must survive handoffs: from an expert to an authoring agent, from an author to an adopter, from one team to another, from a catalog to a project, or from one implementing agent to another.
Without standardized roles, every recipient must still rediscover which passage is authoritative, which parts are examples, which choices remain open, what applies to this adopter, and what counts as evidence.
The semantic roles
SeedSpec gives recurring concerns stable ownership so people and tools can preserve these distinctions instead of inferring them again at every handoff.
- Product intent
- What must be true: the outcome, actors, obligations, invariants, constraints, non-goals, and decision latitude.
- Configuration
- What the adopter may choose. An example shows a valid shape; it is not silently treated as a selection.
- Decisions and provenance
- Who proposed and selected what, for which context, and what remains open or delegated.
- Acceptance
- How success should be evaluated. A plan for evidence is not evidence that the outcome already exists.
- Implementation resources
- Guidance, profiles, skills, tools, and ordered reminders about how to do the work.
- Evidence
- What has actually been observed or verified, and which specific claim that evidence supports.
What changes when the specification travels
Authority stays visible
An agent proposal does not quietly become an author requirement, and an adopter choice does not rewrite the reusable baseline.
Examples remain examples
Valid configuration demonstrates what is possible without pretending that a particular adopter selected those values.
Guidance stays subordinate
Implementation advice can be useful and specific without becoming product intent or execution authority.
Evidence keeps its subject
A passing technical check is evidence about that realization—not proof of every product outcome or the whole project.
What the authoring tools add
Protocol validity only establishes that a package can be interpreted. It cannot establish that the author discovered the important product rules or supplied enough context for a strong implementation.
The guided authoring workflow helps an author or authoring agent:
- separate product intent, configuration, acceptance, and implementation guidance;
- apply a useful review lens without imposing a rigid template;
- identify ambiguity that could materially change behavior or authority;
- record decision provenance while preserving genuine unknowns;
- check consistency across the package; and
- inspect the handoff an independent implementing agent will actually receive.
Empty folders do not add expertise. Stable semantic roles plus guided authoring create a better opportunity to capture, review, and reuse the expertise that exists.
An enterprise example
Suppose several teams repeatedly deploy a customer-support widget. A shared document may describe the widget well while still leaving operational questions: which copy is current, which sections are policy, whether example values were approved, which deployment constraints apply, and what evidence is required before release.
An internal library can publish an exact SeedSpec package version and digest. The package separates required widget behavior from adopter configuration, preserves decision provenance, carries platform guidance, and keeps release checks inspectable. The organization—not the neutral protocol—decides which exact package is approved.
It creates an identifiable, inspectable object about which agreement can be expressed and reproduced.
The claim boundary
Semantic structure improves the opportunity to preserve meaning; it does not make agent execution deterministic. A valid package may still be sparse, mistaken, or a poor fit. Authoring tools can surface gaps, but they cannot replace unavailable expertise or the authority to make material decisions.