Design Document Discovery Workflow in Magnitude: A Complete Guide

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. This workflow is enforced through the bun design-docs CLI helper implemented in 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:

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:

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:

bun design-docs --all

Step 4: Debug Pattern Matching with --explain

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

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 at line 76.

Updating Design Documents During Development

According to 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:

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:

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:

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

Commit both files together:

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, 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 (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 and 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.
• 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, 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 (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. 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.

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