SeedSpec overview
A portable way to tell an AI agent what you want realized—and how success should be checked.
What is SeedSpec?
SeedSpec is an open protocol for packaging intent into specifications that people can read and agents can act on.
A package describes the outcome, provides useful context and choices, and defines how success should be checked. The agent still decides how to do the work, under the user’s direction.
Why SeedSpec?
Agents are increasingly capable, but important context often lives in prompts, tickets, documents, and people’s heads. SeedSpec turns that context into a portable, versioned handoff.
- Clear intentKeep the outcome, constraints, decisions, and success criteria together instead of scattering them across a chat history.
- Portable handoffsGive the same package to different compatible tools and agents without locking the work to one implementation stack.
- Reviewable resultsCarry acceptance criteria and evidence expectations into the handoff so completion can be checked, not merely claimed.
Example specifications
These public packages show how the same protocol can describe a complete application, a portable feature, and a cross-system workflow. They are maintained as downstream reference material, separate from the normative protocol.
Allowance Tracker
Help a household assign chores, approve completed work, and maintain a trustworthy allowance balance.
Configuration, acceptance criteria, and capability contracts for a complete product.
Chore Streaks
Show a child’s current and longest streak of days with qualifying chore completion.
A portable addition that composes through observable host capabilities.
HubSpot Daily Metric
Configure a HubSpot metric and dashboard, then deliver its previous-day average to Slack on a schedule.
One outcome with three candidate implementation profiles.
Package anatomy
At its core, a SeedSpec package is a folder with a seedspec.yaml manifest and a Markdown definition. It can also include configuration, decisions, acceptance criteria, capability contracts, and implementation resources.
my-package/
├── seedspec.yaml # Required: identity + package map
├── definition/ # Example: native primary intent
│ └── feature.md
├── configuration/ # Optional: choices and defaults
│ ├── schema.json
│ └── example.yaml
├── acceptance/ # Optional: success criteria
│ └── criteria.md
└── capabilities/ # Optional: capability contractsHow does SeedSpec work?
SeedSpec separates reusable intent from a specific implementation in three stages.
Package
An author describes the intended outcome and bundles the context an agent may need.
seedspec validate ./my-packageResolve
The user reviews fit, chooses configuration, and combines any additions into one project handoff.
seedspec begin ./my-packageRealize
The chosen agent realizes the resolved intent. Completion is checked separately against the selected evidence requirements.
seedspec completion ./project
What can SeedSpec describe?
The format is intentionally broad. A package describes the outcome; its kind helps people and agents understand the shape of the work without restricting how packages compose.
Applications
Describe a complete product or solution.
Features
Add portable intent to an existing project.
Workflows
Define an outcome that spans tools or systems.
Configurations
Capture desired state in a service or platform.
Open development
SeedSpec is an open-source protocol released under Apache 2.0. The specification, versioned schemas, reference runtime, CLI, and conformance suite are developed in public.
Protocol 0.1 is a design alpha for implementation and interoperability testing. Pin exact prerelease versions when building integrations.
Join the project on GitHubGet started with SeedSpec
npx --yes @seedspec/cli@next version