Authoring a SeedSpec
Start with the material you have. Guided authoring helps identify gaps, clarify authority, and shape a specification another person or agent can actually use.
Authoring is a first-class part of SeedSpec
SeedSpec is not a requirement to hand-edit manifests. Its authoring workflow helps people turn incomplete source material into a fuller, more reviewable specification while producing an ordinary portable package.
Protocol validation and authoring quality are separate results. Validation establishes that a package can be interpreted. It cannot establish that the author supplied the important product rules, resolved the right decisions, or provided enough context.
Begin at the right altitude
Authoring may begin from a sentence, an existing product document, a structured specification, a prototype, an architecture, a runbook, a configured system, or a working application.
Capture
Preserve the source idea in a minimal conforming package without manufacturing detail.
Shape
Identify actors, outcomes, workflows, domain concepts, and meaningful variations.
Harden
Add permissions, invariants, edge cases, failure behavior, acceptance criteria, and explicit evidence subjects.
Compose
Identify capability context, related packages, and supporting artifacts.
Package
Select reusable implementation resources and prepare the independent handoff.
An author may stop at any stage. Depth is a workflow choice, not a different protocol format or a quality score.
The guided review
The reference workflow pairs deterministic CLI checks with a capable authoring agent. The CLI tracks the protocol-aware review; the agent inspects the source material, identifies uncertainty, asks for consequential decisions, edits the package, and explains its judgment.
seedspec audit ./my-package seedspec audit ./my-package --area material-ambiguity seedspec audit ./my-package --statusConcern separation
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
Kind-aware discovery
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
Material ambiguity
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
Decision provenance
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
Internal consistency
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
Progressive hardening
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
Agent-ready handoff
One durable review area with recorded findings, questions, changes, and before-and-after package identity.
What belongs in the primary specification
One compact primary intent source should make four areas easy to find. These are semantic areas, not a requirement to create four files.
- Purpose
- The problem, objective, desired change, and affected actors.
- Obligations and boundaries
- Required outcomes, invariants, constraints, forbidden states, and non-goals.
- Success and evidence
- How realization acceptance differs from later evidence about the outcome.
- Decision latitude
- What is fixed, what the adopter chooses, and what the implementing agent may decide.
What the tools do today
| Tool | Purpose |
|---|---|
seedspec init | Create a kind-aware starting package. |
seedspec audit | Run or continue a versioned semantic review. |
seedspec validate | Check whether the package can be interpreted. |
seedspec lint | Surface deterministic authoring feedback. |
seedspec begin | Inspect the handoff an adopting agent will receive. |
Additional interfaces can provide conversational authoring, forms, visual editors, or organization-specific review while compiling to the same portable package.
Start authoring
npx --yes @seedspec/cli@next init application --output my-application npx --yes @seedspec/cli@next audit ./my-application