init creates two files in a target directory: index.md with a YAML frontmatter stub, and tokens.json with an empty token list. Both files are shaped exactly as the validator expects, so you start from a passing (Draft) baseline rather than from a blank file that fails on first run.
Usage
Options
What gets created
Runningagentic-spec init tooltip --out ./specs produces:
specs/tooltip/index.md
specs/tooltip/tokens.json
agentic-spec validate specs/tooltip immediately after init produces a clean pass at Draft status with no errors.
After scaffolding
The stub gets you to a passing baseline, but aDraft spec is not ready for code generation. Work through these steps to promote it:
- Fill
semantic_parts. Name every region inside the component (root,label,arrow, etc.). - Fill
interaction_states. List every state that must exist in code and Storybook. - Fill
required_aria. List every ARIA attribute the component must expose. - Build
tokens.json. Add one entry per token the component will use, referencing existing semantic tokens. Never add a primitive directly. - Add each token name to
token_contractin the frontmatter. - Implement the component in
packages/ui/src/components/against the spec. - Add Storybook stories — one per entry in
interaction_states. - Flip each
checks:gate totrueas it passes. - Set
status: AI-Readyonly when all five checks aretrue.