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

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) 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), 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 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 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:

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:

{
  "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:

# 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	Core CLI implementation containing findProjectRoot(), loadDesignDocuments(), parseDesignDocument(), collectChangedPaths(), expandInputPaths(), and matchDesignDocuments()
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	Unit tests validating matching logic and CLI behavior

Summary

• design-docs is a TypeScript CLI tool in 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) 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}