# What Is the `design-docs` Tooling in Magnitude? CLI Specification Workflow Explained

> Explore magnitudedev/magnitude design-docs tooling. This CLI utility syncs design specs with source code, ensuring discoverable, traceable, and updated documentation.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: internals
- Published: 2026-09-06

---

**The `design-docs` tooling in Magnitude is a CLI utility that connects design specification markdown files to their implementing source code, keeping documentation discoverable, traceable, and synchronized with code changes.**

Magnitude, an open-source agent framework developed by `magnitudedev/magnitude`, treats design specifications as **living documents** rather than static artifacts. The `design-docs` CLI utility ([`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts)) enforces this philosophy by establishing bidirectional links between markdown specifications in the `design/` directory and the TypeScript source files they govern.

## How the `design-docs` Tooling Works

The utility operates through a six-stage pipeline that transforms scattered documentation into a queryable knowledge graph.

### 1. Locate the Project Root

The tool first establishes its working context. The `findProjectRoot()` function executes `git rev-parse --show-toplevel` to anchor all subsequent operations to the repository root, ensuring consistent path resolution regardless of where the command is invoked.

### 2. Load and Parse Design Documents

The `loadDesignDocuments()` function scans `design/**/*.md` (excluding [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md)), reads each file, and extracts its YAML front-matter. Every design document must declare an `applies_to` array containing glob patterns that specify which source files the document governs.

The `parseDesignDocument()` function validates this metadata: it ensures patterns are relative to the project root and are valid `Bun.Glob` expressions. Invalid patterns trigger immediate errors, preventing malformed specifications from entering the system.

### 3. Determine Target Files

Depending on CLI flags, the tool collects files through three modes:

- **`--changed`**: Uses `git diff` and `git ls-files` to capture staged, unstaged, and untracked changes via `collectChangedPaths()`.
- **Path arguments**: Expands directories to their contained files through `expandInputPaths()`.
- **`--all`**: Returns every design document without filtering.

### 4. Match Documents to Targets

The `matchDesignDocuments()` function performs the core logic: for each document, it checks whether the document's own path or any of its `applies_to` globs intersect with the target file set. Matches are preserved as structured records containing the target path and the triggering pattern.

### 5. Output Results

By default, the tool prints matching document paths. With `--explain`, it also outputs the concrete source file and the specific glob that caused each match, enabling precise debugging of specification coverage.

## Why `design-docs` Matters for Specification Workflows

### Bidirectional Traceability

The `applies_to` field creates explicit contracts. A developer reading [`src/agent/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/src/agent/src/index.ts) can run `bun design-docs src/agent/src/index.ts` to discover exactly which specifications apply. Conversely, reviewers of [`design/architecture/query-mutation-state.md`](https://github.com/magnitudedev/magnitude/blob/main/design/architecture/query-mutation-state.md) immediately see which implementation files fall under its scope.

### Change-Driven Awareness

The `--changed` flag prevents documentation drift. Before committing, developers can verify which specifications their modifications affect:

```bash
bun design-docs --changed

```

This surfaces impacted specs without manual bookkeeping, reducing the chance that code evolves while its governing documentation stagnates.

### CI Pipeline Enforcement

Organizations can integrate `design-docs` into pre-merge checks. The `--explain` flag provides actionable output for build failures:

```json
{
  "scripts": {
    "check-specs": "bun design-docs --changed --explain"
  }
}

```

A non-zero exit status blocks merges when changes lack corresponding specification updates or when specifications reference non-existent files.

### Comprehensive Discoverability

The `--all` flag supports repository audits and contributor onboarding by enumerating every active specification. New team members can rapidly map the codebase's design landscape without navigating directory structures manually.

## Practical Usage Examples

Run these commands from the repository root:

```bash

# Find specifications governing a specific source file

bun design-docs src/agent/src/index.ts

# Identify specs affected by uncommitted work

bun design-docs --changed

# List every design document

bun design-docs --all

# Detailed matching with source path explanations

bun design-docs --changed --explain

```

## Key Implementation Files

| Path | Role |
|------|------|
| [`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts) | Core CLI implementation containing `findProjectRoot()`, `loadDesignDocuments()`, `parseDesignDocument()`, `collectChangedPaths()`, `expandInputPaths()`, and `matchDesignDocuments()` |
| [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md) | Central index excluded from automatic scans; serves as meta-documentation |
| `design/**/*.md` | Individual specifications with `applies_to` YAML front-matter |
| [`scripts/design-docs.test.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.test.ts) | Unit tests validating matching logic and CLI behavior |

## Summary

- **`design-docs`** is a TypeScript CLI tool in [`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts) that bridges markdown specifications and source code.
- **YAML front-matter** with `applies_to` globs establishes traceability from design documents to implementation files.
- **`--changed`** enables change-aware workflows by analyzing Git modifications.
- **`--explain`** provides actionable debugging output for CI enforcement and developer verification.
- The tool transforms static documentation into a **queryable, maintainable specification system** that scales with codebase complexity.

## Frequently Asked Questions

### What format must design documents follow to work with `design-docs`?

Design documents must be markdown files located under `design/` (except [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md)) containing valid YAML front-matter with an `applies_to` array. Each entry in `applies_to` must be a `Bun.Glob`-compatible pattern relative to the project root that identifies the source files the specification governs.

### How does `design-docs` detect which files have changed?

The `collectChangedPaths()` function executes Git commands to retrieve staged modifications (`git diff --staged --name-only`), unstaged changes (`git diff --name-only`), and untracked files (`git ls-files --others --exclude-standard`). This comprehensive capture ensures no work-in-progress escapes specification review.

### Can `design-docs` be used outside of Magnitude's repository?

The tool is tightly coupled to Magnitude's directory conventions and depends on Bun's runtime. However, the architecture in [`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts) could be adapted to other projects by modifying the glob patterns for document discovery and adjusting the Git integration to match different repository structures.

### What happens if an `applies_to` pattern is invalid?

The `parseDesignDocument()` function validates each pattern during loading. Invalid `Bun.Glob` expressions or absolute paths trigger immediate errors with descriptive messages, preventing malformed specifications from being silently ignored during matching operations.