add-primitive

Add Primitive

Add or modify AI primitive definitions for agentconfig.org.

Overview

Primitives appear in these places:

1. Primitive Cards - site/src/data/primitives.ts (the single canonical source)
2. File Tree - site/src/data/fileTree.ts
3. Provider Comparison - site/src/data/comparison.ts (derived automatically from primitives.ts; never hand-edited)
4. Provider Profiles - site/src/data/providerProfiles.ts (also derived automatically from primitives.ts; never hand-edited)

Step-by-Step Process

1. Define the Primitive

Edit site/src/data/primitives.ts:

{
  id: 'your-primitive-id',           // lowercase, hyphens
  name: 'Display Name',
  description: 'One-sentence summary.',
  whatItIs: 'Detailed explanation of the concept.',
  useWhen: [
    'First use case',
    'Second use case',
  ],
  prevents: 'What problem/failure this prevents',
  combineWith: ['Other Primitive', 'Another Primitive'],
  implementations: [
    {
      provider: 'copilot',
      implementation: 'How Copilot implements this',
      location: '.github/path/to/file',
      support: 'full',  // 'full' | 'partial' | 'diy'
      sourceUrl: 'https://docs.github.com/...',  // primary provider documentation
    },
    {
      provider: 'claude',
      implementation: 'How Claude implements this',
      location: '.claude/path/to/file',
      support: 'full',
      sourceUrl: 'https://code.claude.com/docs/...',
    },
    {
      provider: 'cursor',
      implementation: 'How Cursor implements this',
      location: '.cursor/path/to/file',
      support: 'full',
      sourceUrl: 'https://cursor.com/docs/...',
    },
    {
      provider: 'codex',
      implementation: 'How Codex implements this',
      location: '~/.codex/path/to/file',
      support: 'full',
      sourceUrl: 'https://developers.openai.com/codex/...',
    },
  ],
  category: 'instructions',  // one of the 8 layer ids — see Categories below
}

Always list all four providers (copilot, claude, cursor, codex) even when support is partial or diy — a missing provider entry silently reads as "no data" rather than "not supported," which the refresh-provider-docs skill and comparison table both rely on to stay honest. Cite a primary sourceUrl for every claim; do not add a primitive with unverified provider claims (use the refresh-provider-docs skill first if you have not already confirmed the paths against current documentation).