/codebase-index

name: codebase-index
description: "Generate a pre-computed component index from a design system codebase — YAML infrastructure files containing a component inventory, relationship graph, and summary statistics that AI agents and MCP servers consume. This produces machine-readable index files in .ai/index/, NOT a health report or quality assessment. Trigger when someone says: index my codebase, build a relationship graph, create a component map, codebase index, what depends on what, dependency graph, map component relationships, or anything about producing queryable infrastructure files for AI agents or developer tooling. Do NOT trigger for component health assessments, quality scores, or audit reports — use component-audit for those."
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-governance.md

Codebase index

A skill for generating a pre-computed, machine-readable index of a design system's codebase. The index contains three pieces: a component inventory, a relationship graph, and summary statistics. Together they form a queryable map that eliminates the need for AI agents or developers to explore the codebase from scratch every time they need to understand the system.

Context

When an AI agent needs to work with a design system codebase, it has two options: explore or navigate. Exploration means scanning directories, grepping for imports, reading files one by one. Navigation means loading a pre-computed index and reasoning over cached data.

The difference matters. Exploration is slow, incomplete, and non-deterministic. An agent scanning `src/components` might miss components in `src/layouts`, `src/pages`, or utility directories that don't follow naming conventions. It might report a deeply-nested component as "unused" because it can't trace the dependency chain. It might recreate an existing component because it didn't find it.

A pre-computed index front-loads this cost. The agent loads the index once — typically a few thousand tokens — and gets a complete picture of what exists, where things live, and how they relate. Follow-up questions become cheap because the agent reasons over cached data instead of triggering new file reads.

This skill generates that index. Run it after adding or removing components, and commit the output alongside the code.

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `system.framework` — pre-selects framework detection (React, Vue, Svelte, Astro, Angular, etc.)
• `system.component_paths` — overrides default component directory scanning
• `system.category_model` — atomic design, functional, or custom categorisation
• `integrations.*` — enables auto-pull for component data
• `recurring.*` — enables comparison with previous index

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically:

**Figma MCP** (`integrations.figma.enabled: true`):

• Read the published library from `integrations.figma.file_key`
• Cross-reference the Figma component inventory against the code inventory to detect components that exist in design but not in code (or vice versa)
• Pull description status per component to populate the metadata coverage field

**Storybook** (`integrations.storybook.enabled: true`):

• Fetch the story index from `integrations.storybook.url/index.json`
• Extract component list and documentation status
• Use as a secondary source for component discovery

**GitHub** (`integrations.github.enabled: true`):

• Use `gh api search/code` to count import references across consuming repositories
• Pull PR activity for recency signals

If an integration fails, log it and proceed with manual scanning.

---

Step 1: Detect the framework and structure

Scan the project root to determine:

• **Framework**: React (JSX/TSX), Vue (SFC), Svelte, Astro, Angular, Web Components, or mixed
• **Component directories**: Where components live — scan common locations: `src/components/`, `src/lib/`, `components/`, `packages/`, and any paths in `tsconfig.json` or framework config
• **Category model**: How components are organised — atomic design (`atoms/`, `molecules/`, `organisms/`), functional (`forms/`, `navigation/`, `feedback/`), flat, or monorepo packages
• **Styling approach**: CSS modules, CSS-in-JS, Tailwind, SCSS, or design tokens — this determines how to trace token dependencies

Ask for or confirm (skip questions already answered by config or detection):

• The component source root if auto-detection finds multiple candidates
• Whether there are components in non-standard locations (e.g., a shared `utils/` directory with reusable UI primitives)
• Whether to include internal/private components in the index (underscore-prefixed, `internal/` directories, components not re-exported from barrel files)

**Framework detection rules:**

| Signal | Framework | |---|---| | `.jsx` / `.tsx` files with JSX returns | React | | `.vue` files with `<template>` blocks | Vue | | `.svelte` files | Svelte | | `.astro` files | Astro | | `.component.ts` with `@Component` decorator | Angular | | `customElements.define()` | Web Components | | Mixed signals | Ask the user |

Step 2: Scan and build the component inventory

For every component file found, extract:

• **Name**: The component's exported name
• **Path**: Relative path from project root
• **Category**: Based on the category model (atom, molecule, organism, etc.) or functional category (navigation, form, feedback, layout, data display)
• **Metadata status**: Whether the component has structured metadata (a `.metadata.ts`, `.metadata.json`, description in Storybook, JSDoc/TSDoc block, or Figma description)
• **Export type**: Default export, named export, or re-exported through a barrel file

**What counts as a component:**

• Files that export a renderable element (JSX, template, render function)
• Files explicitly registered in a component index, barrel fi