/codebase-index

name: codebase-index
description: "Generate machine-readable index files in .ai/index/ (component inventory, uses/usedBy graph, stats) for AI agents. Triggers: index my codebase, build a relationship graph, what depends on what. Not an assessment; for library health use component-audit."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*), Bash(git diff:*), Bash(git log:*), Bash(git rev-parse:*)
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/output-discipline.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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

An agent exploring a codebase from scratch is slow and misses things; an agent loading a pre-computed index gets the whole picture in a few thousand tokens. This skill writes that index, and it is the pack's single producer of the component inventory and dependency graph: `token-audit`, `component-audit`, `docs-coverage`, `component-decision-tree` and `agent-instructions` read `.ai/index/` rather than building their own. Run it after adding or removing components, and commit the output alongside the code.

---

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `system.framework` — pre-selects framework detection
• `system.component_paths` — overrides default component directory scanning
• `system.category_model` — atomic design, functional, or custom categorisation
• `integrations.*` — component data sources (see below)
• `recurring.*` — delta against the previous index (see Recurring workflow)

Auto-pull integrations

**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`):

• Pull PR activity for recency signals

---

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

If no component files are found under any candidate root, stop and ask where they live; don't write an empty index.

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
• **Token bindings**: the design tokens the component's styles reference (`var(--color-action-primary)`, `$space-gap`, `theme.colors.primary`, Tailwind utilities that map to configured tokens). Record the token names as the codebase writes them. This is the token-to-component edge that `token-audit` and `component-audit` read for blast radius, so they don't each build a second graph

**What counts as a component:*