> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agentic-spec init: Scaffold a New Component Spec Directory

> agentic-spec init scaffolds a new spec directory with index.md and tokens.json stubs — the starting point for adding a component to the system.

`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

```bash theme={null}
agentic-spec init <component-name> --out ./specs --ds-version "clementine-ds@HEAD"

# Example
agentic-spec init tooltip --out ./specs --ds-version "clementine-ds@HEAD"
# → created specs/tooltip/index.md
# → created specs/tooltip/tokens.json
```

## Options

| Flag | Description |
| - | - |
| `--out` | Directory in which to create the `<component-name>/` folder. Defaults to `./specs`. |
| `--ds-version` | Value written to the `ds_version` field in the generated spec frontmatter. Use the current repo version or `clementine-ds@HEAD` during active development. |

## What gets created

Running `agentic-spec init tooltip --out ./specs` produces:

**`specs/tooltip/index.md`**

```yaml theme={null}
---
component: tooltip
ds_version: clementine-ds@HEAD
status: Draft
last_verified: <today's date>
category: Component
required_aria: []
semantic_parts: {}
token_contract: []
interaction_states: []
checks:
  aria_correct: false
  structure_correct: false
  states_complete: false
  tokens_valid: false
  no_invented_styles: false
sources:
  code:
    path: packages/ui/src/components/Tooltip.tsx
    framework: react
    underlying_library: mantine
  storybook:
    path: apps/storybook/stories/Tooltip.stories.tsx
  tokens:
    component: packages/tokens/src/components/tooltip.json
---
```

**`specs/tooltip/tokens.json`**

```json theme={null}
{
  "component": "tooltip",
  "tokens": []
}
```

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](https://clementineds.mintlify.site/first-component.md) for a full walkthrough of steps 1 through 9 with a real example.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.