Skip to main content
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

Running agentic-spec init tooltip --out ./specs produces: specs/tooltip/index.md
specs/tooltip/tokens.json
Both files are valid stubs. Running 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 a Draft spec is not ready for code generation. Work through these steps to promote it:
  1. Fill semantic_parts. Name every region inside the component (root, label, arrow, etc.).
  2. Fill interaction_states. List every state that must exist in code and Storybook.
  3. Fill required_aria. List every ARIA attribute the component must expose.
  4. Build tokens.json. Add one entry per token the component will use, referencing existing semantic tokens. Never add a primitive directly.
  5. Add each token name to token_contract in the frontmatter.
  6. Implement the component in packages/ui/src/components/ against the spec.
  7. Add Storybook stories — one per entry in interaction_states.
  8. Flip each checks: gate to true as it passes.
  9. Set status: AI-Ready only when all five checks are true.
See the first component workflow for a full walkthrough of steps 1 through 9 with a real example.