New Candidate

You are running the /new-candidate skill. Adding a component touches seven places in lockstep. Miss one and either the agent can't emit it, the CLI rejects it, or the runtime crashes on it.

Args ($ARGUMENTS): the proposed component name (kebab-case, single word preferred), e.g. timeline, progress, code-diff. If missing, ask the user.

Step 0 — sanity check the name

node -e "const r = require('./aio-registry.json'); const all = [...r.stable, ...r.candidate].map(c => c.info); console.log(all.join('\\n'))"

The new name must not collide with any info in stable or candidate. The schema component id will be <name>-v1.schema.json, the spec <name>-v1.md, the info string aio:<name>@1.

Step 1 — design before code

Before writing any file, get clear answers from the user. Don't guess — wrong data shape now means a breaking @2 later.

Ask:

1. What's the data shape? (e.g., for timeline: array of events with date, title, description; for progress: array of steps each with label, value 0–100, optional tone).
2. What are the limits? Max items, max string length per field, what tones (if any), what numeric ranges.
3. What's the cross-field invariant? (e.g., timeline events must be in chronological order; progress values must be 0–100). JSON Schema can't express most of these — they go in the CLI validator.
4. What does it render as? A short description of the visual. The runtime renderer should be pure SVG / static HTML, no JS.
5. What does it intentionally NOT support? (Stacked variants, callbacks, custom colours, etc.) Write these into the spec's "Intentionally excluded" section so future contributors don't add scope creep.

Step 2 — write the spec at specs/<name>-v1.md

Follow the structure of specs/chart-v1.md (the most recently-added candidate). Required sections:

• Title line: # aio:<name>@1 (candidate)
• Status banner: "candidate — may receive optional fields before promotion to stable"
• Purpose paragraph
• Schema summary (JSON example)
• Hard rules list (matches what the CLI validator will enforce)
• "Intentionally excluded" list
• Examples (one per variant if applicable)
• Renderer contract (what the reference renderer guarantees; what third parties may differ on)

Step 3 — write the schema at schemas/<name>-v1.schema.json

Mirror the structural rules. Always include:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ai-output.dev/schemas/<name>-v1.schema.json",
  "title": "aio:<name>@1",
  "description": "Structural shape for aio:<name>@1 blocks. Cross-field invariants are enforced by the AIO validator at scripts/aio.mjs and are the source of truth: <list them here>.",
  "type": "object",
  "additionalProperties": false,
  ...
}

Every string field that holds AI-emitted text must include "pattern": "^[^<>]*$" and a sensible maxLength. Numeric fields that must be finite go through the CLI's finiteNumber helper, since { "type": "number" } permits Infinity/NaN in JSON.

Step 4 — add the registry entry

In aio-registry.json, append to the candidate array:

{
  "info": "aio:<name>@1",
  "schema": "schemas/<name>-v1.schema.json",
  "spec": "specs/<name>-v1.md",
  "introducedIn": "<current-or-next-version>",
  "note": "Candidate. Schema is final but may receive optional fields in minor revisions before promotion to stable."
}

Step 5 — add the CLI validator at scripts/aio.mjs

Pattern after validateChart (the most recent addition). Use the existing helpers: rejectUnknownKeys, plain, requireArray, finiteNumber, fail. Register in the validators Map:

const validators = new Map([
  ["table@1", validateTable],
  ["metric-cards@1", validateMetricCards],
  ["callout@1", validateCallout],
  ["chart@1", validateChart],
  ["<name>@1", validate<Name>]
]);

The validator is the source of truth for cross-field invariants. JSON Schema can't express row-length-equals-columns or non-empty unions — those go here.

Step 6 — add the JS renderer at assets/ai-output-runtime.js

Follow the same pattern: a validate<Name> function (mirroring the CLI validator, throwing Error), then a render<Name>(data) function that returns an HTML string via componentShell(). Register in COMPONENTS:

COMPONENTS.set("<name>@1", (_type, data) => render<Name>(data));

Constraints:

• Pure SVG / static HTML. No <script>, no event handlers, no inline JS.
• Colours come from CSS variables — never hardcode. Use --ai-chart-1 through --ai-chart-6 for series colours, --ai-green/--ai-yellow/--ai-red/--ai-accent for tone overrides.
• Long text must truncate with ellipsis, not overflow or rotate.
• Both light and dark themes must work — the existing CSS variables already cover both palettes.

If the component needs new CSS, add it before the @media print block in the css string, and add @media print rules so the component prints sensibly (no shadows, no chrome, page-break-inside avoidance).

Step 7 — add a fixture at examples/<name>-demo.md

A Markdown file demonstrating each variant of the new component. Wire it into package.json test:valid:

node scripts/aio.mjs validate examples/<name>-demo.md

If the component should appear in the live site, also reference it from examples/landing.md and update render:site.

Step 8 — update SKILL.md

Since v0.6.0 the candidate components live in one key-reference table ("Candidate components — key reference"), not per-component subsections. Add:

• One table row: component id, a terse "Use for" phrase, and the COMPLETE allowed key set (? marks optional keys) — the row must list every key the CLI's rejectUnknownKeys accepts, including doc-level title?/subtitle?/asOf?/format? where applicable, plus the cross-field invariants the CLI hard-fails on (lengths, enums, limits).
• The component name in the "Hard Rules" scope list (candidate group).
• If the shape benefits from it, one bullet in "Output Policy" mapping a content shape to the component.

Do NOT add a fenced example for candidates — only the three stable components carry examples (in the compact emission style).

Step 9 — verify and commit

npm test                # validates the new fixture against the new validator
npm run render:site     # confirms the new renderer produces no JS errors

If both pass, commit. Do not bump the package version here — that happens at the next release via /release. The new component lands on main, and the next vX.Y.0 release exposes it through the CDN.

Step 10 — ask about adding fuzz cases

Walk through with the user: what are the 5–10 inputs that should fail validation (NaN, length mismatch, HTML in string, etc.)? Add them as ad-hoc shell tests now, or note them for inclusion when a proper fuzz harness lands.

Hard rules

• The seven artifacts (spec, schema, registry, CLI validator, JS renderer, fixture, SKILL.md) must all land in the same commit. Otherwise the CLI accepts something the runtime can't render, or vice versa.
• Candidate, not stable. Even if the user says "make it stable", default to candidate. Per CONTRIBUTING.md, stable promotions require demonstrated adoption — the candidate buffer protects against breaking changes.
• No new dependencies. The runtime is zero-deps; the CLI is zero-deps. If the new component genuinely requires a chart-library equivalent, raise the trade-off to the user before adding any import.
• Never use raw colour hex values in the JS renderer. Always go through CSS variables, so light/dark themes stay in sync.