SeedSpec specification

The normative SeedSpec Protocol 0.4 contract and its supporting schemas and conformance corpus.

Protocol 0.4 in one view

A SeedSpec package requires one nonempty SPEC.md. Tool-readable declarations may live in its YAML frontmatter, a root seedspec.yaml, or both. The resolved manifest requires id, name, and version. kind is optional.

SPEC.md

Required Markdown prose. Optional YAML frontmatter can contain the manifest.

seedspec.yaml

Optional root manifest. SPEC.md frontmatter overrides it when both exist.

Configuration

Typed adopter choices, inline or split into one level of YAML sections.

Success

Acceptance claims that can be linked to prose with [success:<id>] anchors.

Capabilities

Observable package functionality, outcomes, and related success criteria.

Tasks

Ordered implementation guidance tied to capabilities or success criteria.

Context modules

Optional typed Markdown inputs with direct entrypoint paths.

Bundled packages

Optional child packages bound by ID, version, digest, and path.

What is normative

Protocol behavior is defined by the specification, versioned schemas, and conformance corpus. Guides and examples explain the design but do not add rules.

Language definition

The package model, manifest sources, authority boundaries, and claims made by protocol operations.

Protocol 0.4 specification

The required SPEC.md entrypoint and the declarations for configuration, success, tasks, capabilities, context modules, and bundled packages.

Operation contracts

The offline validate, digest, inspect, and flatten operations.

Versioned schemas

The three JSON Schemas for packages, conformance cases, and conformance reports.

Conformance corpus

The cases an independent implementation must satisfy and the narrow claim that passing establishes.

Keep the claims separate

Claim	Established by
A tool can interpret this package.	Validation and protocol conformance.
The specification communicates useful intent.	Author review and judgment.
An implementation satisfies that intent.	Independent evidence against its success criteria.

A valid package is not automatically a strong specification or a correct implementation.