/context-engine-builder

name: context-engine-builder
description: "Generate a context engine — seven structured blueprint files (UX, UI, content, accessibility, ethical, technical, business intelligence) that encode everything an AI agent needs to work with a design system. This produces YAML infrastructure in .ai/context-engine/, NOT a health score or quality assessment. Trigger when someone says: build a context engine, create a system brain, build the seven blueprints, context engine, blueprint stack, encode design system knowledge for AI, make our system AI-navigable, or anything about creating structured knowledge files that AI agents load to understand the system. Do NOT trigger for scoring or assessing system health — use system-health for that."
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/agent-orchestration-guide.md
  - ../../knowledge-notes/mcp-setup-guide.md
  - ../../knowledge-notes/context-engine-blueprints.md

Context engine builder

A skill for generating a context engine — a structured, multi-layered knowledge base that gives AI agents the complete picture of a design system. The engine encodes seven dimensions of system knowledge (UX, UI, content, accessibility, ethical, technical, and business intelligence) as machine-readable blueprints that agents load, reason over, and apply without requiring implicit knowledge or human interpretation.

Context

A design system is more than a component library. It encodes decisions about user experience patterns, visual language, content voice, accessibility requirements, ethical guardrails, technical constraints, and business rules. These decisions live in different places — Figma files, code repos, wikis, Slack threads, the heads of senior team members — and most of them are invisible to AI agents.

When an AI agent interacts with a design system, it typically receives a narrow slice: component props, maybe a description, perhaps some token values. It does not receive the reasoning behind those components, the constraints that govern their use, or the relationships between design decisions and business outcomes. The result is output that is technically valid but contextually wrong — a login form that uses the right components but ignores the system's established authentication patterns, or a dashboard that follows the grid but violates the system's data visualisation principles.

A context engine front-loads this knowledge. Instead of letting agents discover context through trial and error (or not discover it at all), the engine encodes it as structured data that agents load at the start of a task. The seven blueprints are not arbitrary categories — they represent the seven dimensions of knowledge that, when missing, produce the most common classes of AI-generated design system errors.

The practical output is a set of structured files — one per blueprint — that live alongside the codebase and are consumed by AI agents, MCP servers, and developer tooling. Together they form the machine-readable brain of the design system.

Boundaries

This skill builds context infrastructure — it does not assess system health or score quality (use `system-health` for that). If the system has no documented components, tokens, or patterns yet, the context engine has nothing to encode; help the team establish foundations first. If only one or two blueprints are needed (a common case — many teams start with the Technical and UI blueprints only), generate those specifically rather than forcing all seven. The engine is modular; partial generation is a feature, not a gap.

---

Configuration

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

• `system.framework` — pre-selects framework for technical blueprint generation
• `system.component_paths` — directs blueprint scanning to correct directories
• `system.tokens` — identifies token files for UI blueprint extraction
• `integrations.*` — enables auto-pull for blueprint data
• `context_engine.blueprints` — overrides which blueprints to generate (default: all seven)
• `context_engine.output_format` — output format preference (JSON or YAML, default: YAML)

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`
• Extract component descriptions, variant structures, and layer hierarchies for the UX and UI blueprints
• Pull design token definitions (colour, spacing, typography) for the UI blueprint
• Extract accessibility annotations if present for the accessibility blueprint

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

• Fetch the story index and component metadata
• Extract documented states, interactions, and composition patterns for the UX blueprint
• Pull accessibility addon results for the accessibility blueprint

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

• Scan component source files for prop types, default values, and TypeScript interfaces for the technical blueprint
• Pull PR templates and contribution guidelines for governance context
• Check for existing documentation files that inform blueprint content

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

---

Step 1: Assess current context coverage

Before building blueprints, understand what context already exists. Scan for:

• **Existing documentation**: Component docs, pattern libraries, design principles pages, content guidelines, accessibility policies
• **Structured metadata**: JSON/YAML files with component definitions, token files, manifest files
• **Implicit context**: README files, contribution guides, code comments, Storybook stories that encode knowledge informally

Produce a brief context coverage assessment:

| Blueprint | Existing sources found | Coverage estimate | Primary gaps