Why semantic structure matters
SeedSpec uses structure where tools need stable meaning and leaves the specification itself as prose.
Good Markdown is already a strong input
A well-written Markdown spec is already a strong starting point. Extra files and structure do not automatically produce a better implementation. Protocol 0.4 starts with one required Markdown file and adds structure only where it supports reuse or tooling.
What receives a stable role
Prose intent
SPEC.md remains the primary authored specification.
Package identity
ID, kind, version, metadata, and digest identify the package without proving publisher authority.
Configuration
Typed variables describe choices available to an adopter.
Capabilities
Named functionality gives tools a stable unit for planning and assessment.
Success criteria
Structured claims define what must be true without pretending to be evidence.
Context modules
Typed Markdown adds skills, policy, evaluation, reference, behavior, intent, or implementation guidance.
The feedback loop
- Write product intent in
SPEC.md. - Extract only reusable choices, capabilities, success claims, and ordered guidance.
- Connect success claims back to prose with explicit anchors.
- Use context modules for material that needs a distinct role or loading stage.
- Implement and collect independent evidence outside protocol validation.
- Revise the package when repeated implementations expose ambiguity.
Boundaries
- Structure does not repair weak intent.
- A capability is not a universal ontology entry.
- A success criterion is not its evaluation method or evidence.
- A context module cannot override the package or system instructions.
- A digest proves byte identity, not authorship or safety.