# Design Document Discovery Workflow in Magnitude: A Complete Guide

> Master the Magnitude design document discovery workflow. Learn how the bun design-docs CLI links source files to design docs, ensuring architectural integrity before commits.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: how-to-guide
- Published: 2026-09-08

---

**The design document discovery workflow in magnitudedev/magnitude uses the `bun design-docs` CLI to map every source file to its governing design documents via `applies_to` glob patterns, ensuring architectural decisions are checked before code changes are committed.**

Magnitude treats design documents as the **single source of truth** for architectural decisions. Before modifying any code, developers must locate all design documents whose `applies_to` frontmatter matches the target file path, as specified in [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md). This workflow is enforced through the `bun design-docs` CLI helper implemented in [`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts).

## How the Discovery Workflow Works

The workflow centers on matching source files to design documents using glob patterns defined in YAML frontmatter.

### Step 1: Locate Relevant Design Documents

Before editing a file, run the discovery command to identify governing specifications:

```bash
bun design-docs packages/sdk/src/client.ts

```

This queries all Markdown files in the `design/` directory and returns those whose `applies_to` patterns cover the specified path. For example, the command might return:

```

design/architecture/query-mutation-state.md
design/clients/web-local-inference.md

```

### Step 2: Review Changed Files with `--changed`

To see design documents affected by your current working directory changes:

```bash
bun design-docs --changed

```

This flags documents that apply to files you have modified or staged, ensuring you do not miss architectural constraints during active development.

### Step 3: Audit All Design Documents

For repository-wide audits or onboarding, list every design document:

```bash
bun design-docs --all

```

### Step 4: Debug Pattern Matching with `--explain`

To understand why specific documents match a file path, use the explain flag:

```bash
bun design-docs packages/agent/src/new-subsystem/index.ts --explain

```

This outputs the concrete glob patterns that caused each match, helping debug `applies_to` configurations as documented in [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md) at line 76.

## Updating Design Documents During Development

According to [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md) (lines 64-88), if your change affects architecture, observable behavior, or contracts, you must update the matched design documents in the same commit.

### Creating New Design Documents

When introducing a new subsystem, create a document with proper frontmatter:

```bash
mkdir -p design/agent
cat > design/agent/new-subsystem.md <<'EOF'
---
applies_to:
  - packages/agent/src/new-subsystem/**
---

# New Subsystem Design

## Invariants

- All state transitions must be logged
EOF

```

Then verify the CLI recognizes it:

```bash
bun design-docs packages/agent/src/new-subsystem/index.ts --explain

```

### Modifying Existing Documents

After editing source code, update the related design document to reflect new invariants or acceptance criteria:

```bash
code design/architecture/query-mutation-state.md

```

Commit both files together:

```bash
git add packages/sdk/src/client.ts design/architecture/query-mutation-state.md
git commit -m "Fix client RPC handling – update design doc"

```

## Implementation and Key Files

The discovery logic is implemented in **[`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts)**, which parses the YAML frontmatter of files in the `design/` directory and evaluates glob patterns against input paths.

The workflow requirements are specified in **[`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md)** (lines 90-98), which mandates that reviewers confirm all applicable design docs were consulted before approving changes.

Individual design documents, such as **[`design/architecture/query-mutation-state.md`](https://github.com/magnitudedev/magnitude/blob/main/design/architecture/query-mutation-state.md)** and **[`design/clients/web-local-inference.md`](https://github.com/magnitudedev/magnitude/blob/main/design/clients/web-local-inference.md)**, serve as concrete examples containing `applies_to` declarations that the CLI evaluates.

## Summary

- **Use `bun design-docs <path>`** to find all design documents governing a specific file before editing.
- **Use `bun design-docs --changed`** to identify architectural constraints affecting your current work-in-progress.
- **Update design documents in the same commit** when changing architecture, behavior, or contracts, as required by [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md).
- **Debug matching logic** with `--explain` to verify `applies_to` glob patterns are correct.
- **Enforce compliance** through code review by verifying that all applicable design docs were consulted.

## Frequently Asked Questions

### What is the purpose of the design document discovery workflow in Magnitude?

The workflow ensures that every code change is vetted against stable, version-controlled architectural specifications. By requiring developers to locate and verify design documents via the `bun design-docs` CLI, Magnitude prevents silent divergence between implementation and intent while maintaining explicit ownership boundaries and failure-handling policies.

### How do I find which design documents apply to a specific source file?

Run `bun design-docs <path>` where `<path>` is the relative path to your target file. The command, implemented in [`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts), scans all files in the `design/` directory and returns those whose `applies_to` YAML frontmatter matches the file path via glob patterns.

### What happens if I modify code without updating the relevant design documents?

According to [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md) (lines 90-98), reviewers must reject changes where the implementation diverges from applicable design documents. The `--changed` flag helps catch these cases during development, but enforcement relies on mandatory human review ensuring design and code are updated atomically in the same commit.

### Where is the `bun design-docs` command implemented?

The CLI helper is implemented in **[`scripts/design-docs.ts`](https://github.com/magnitudedev/magnitude/blob/main/scripts/design-docs.ts)**. This script parses Markdown frontmatter, evaluates glob patterns against file paths, and handles flags like `--changed`, `--all`, and `--explain` to support the discovery workflow described in [`design/AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/design/AGENTS.md).