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.

npx @seedspec/cli init application --output my-package cd my-package npx @seedspec/cli author

Concern separation

Keep ideation, requirements, planning, implementation, and evidence distinct.

Kind-aware discovery

Explore the decisions and failure modes that matter for this package kind.

Material ambiguity

Ask when plausible answers would produce meaningfully different specifications.

Decision provenance

Separate author decisions, sourced facts, and agent-supplied defaults.

Internal consistency

Find conflicts across intent, requirements, constraints, and acceptance criteria.

Progressive hardening

Increase depth only where additional detail changes the resulting work.

Agent-ready packaging

Produce a portable package with explicit authority and stable context modules.

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
`init <kind>`	Create a kind-aware starting package with a seed and success document.
`author`	Find or resume the local authoring workspace and suggest the next step.
`author prompt`	Print the short prompt you paste into your own agent.
`author review`	Print the versioned operating brief the agent follows.
`author record`	Record findings, questions, inventory, and contradictions.
`author answer`	Record your answer, or decline a question you do not own.
`author attach-source`	Attach material the review may draw findings from.
`author reviewed`	Close the current thread with a disposition.
`author questions`	Show what is waiting on you.
`author check`	Check structure, guidance, and publication readiness.
`author pack`	Create the distributable archive with its receipt sidecars.

Additional interfaces can provide conversational authoring, forms, visual editors, or organization-specific review while compiling to the same portable package.

Evaluate the handoff without pretending it is proof

Authors can ask the CLI to create an evaluation workspace for a fresh agent. The workspace binds the exact package digest and contains agent instructions plus a structured result record for observations, blockers, deviations, evidence, and proposed package improvements.

npx @seedspec/cli author evaluate ./my-package --output ./my-package-eval

The author decides which findings reflect intended product meaning, revises through the preparation workflow, and starts a new evaluation for the new digest. One successful run is evidence about that scenario—not a certification or general quality score.

Start authoring

npx --yes @seedspec/cli@0.3.1 init application --output my-application npx --yes @seedspec/cli@0.3.1 prepare ./my-application npx --yes @seedspec/cli@0.3.1 publish-check ./my-application npx --yes @seedspec/cli@0.3.1 pack ./my-application

Read the complete authoring guide ↗Why semantic structure matters →See an authored example →