add-primitive

name	add-primitive
description	Add or modify AI primitive definitions in the data layer with correct typing and complete metadata. Use when adding new primitives, updating descriptions, or extending primitive categories.

Add Primitive

Add or modify AI primitive definitions for agentconfig.org.

Overview

Primitives appear in three places that must stay synchronized:

1. Primitive Cards - site/src/data/primitives.ts
2. File Tree - site/src/data/fileTree.ts
3. Provider Comparison - site/src/data/comparison.ts

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'
    },
    {
      provider: 'claude',
      implementation: 'How Claude implements this',
      location: '.claude/path/to/file',
      support: 'full',
    },
  ],
  category: 'instructions',  // 'instructions' | 'execution' | 'safety'
}

2. Add to File Tree (if applicable)

If the primitive has associated files, add nodes to both trees in site/src/data/fileTree.ts:

For Copilot - Add to copilotTree:

{
  id: 'copilot-your-primitive',
  name: 'your-file.md',
  type: 'file',
  details: {
    label: 'Short Label',
    description: 'What this file does.',
    whatGoesHere: ['Content item 1', 'Content item 2'],
    whenLoaded: 'When this file is loaded.',
    loadOrder: 5,  // 1 = first loaded
    example: `Example content here`,
  },
}

For Claude - Add to claudeTree with equivalent structure.

3. Add to Comparison Matrix

Edit site/src/data/comparison.ts:

{
  primitiveId: 'your-primitive-id',  // Must match primitives.ts
  primitiveName: 'Display Name',
  copilot: {
    level: 'full',  // 'full' | 'partial' | 'none'
    implementation: 'How Copilot does it',
    location: '.github/path',
  },
  claude: {
    level: 'full',
    implementation: 'How Claude does it',
    location: '.claude/path',
  },
}

Data Types Reference

Primitive Interface

interface Primitive {
  id: string
  name: string
  description: string
  whatItIs: string
  useWhen: string[]
  prevents: string
  combineWith: string[]
  implementations: ProviderImplementation[]
  category: 'instructions' | 'execution' | 'safety'
}

Provider Implementation

interface ProviderImplementation {
  provider: 'copilot' | 'claude'
  implementation: string
  location: string
  support: 'full' | 'partial' | 'diy'
}

Support Levels

• full - Native, well-documented support
• partial - Works but with limitations
• diy - Achievable with custom configuration

Categories

• execution - Capability primitives (what it can do)
• instructions - Customization primitives (how to shape it)
• safety - Control primitives (guardrails and verification)

Checklist

Before considering the primitive complete:

• Added to primitives.ts with all required fields
• Added to fileTree.ts for both Copilot and Claude (if has files)
• Added to comparison.ts with accurate support levels
• id is unique and matches across all three files
• combineWith references valid primitive names
• Examples in file tree are accurate and helpful
• Run bun run typecheck - No TypeScript errors
• Visually verify in all three site sections

Common Mistakes

1. Mismatched IDs - The id in primitives.ts must match primitiveId in comparison.ts
2. Missing file tree entries - If the primitive has files, both trees need updates
3. Stale combineWith - Referencing primitives that don't exist
4. Incorrect load order - File tree loadOrder should reflect actual precedence
5. Missing support level - Every provider implementation needs a support level