MDD User Guide

Getting Started

Installation

MDD is a global npm package. Install it once and it works in every project.

# Install globally
npm install -g @thedecipherist/mdd

# Install: mdd.md → ~/.claude/commands/  |  mode files → ~/.claude/mdd/
mdd install

# Optional: install to a custom directory
mdd install --dir /path/to/custom/commands

# Check current version
mdd --version

After mdd install, the /mdd slash command is available in every Claude Code session globally - no per-project setup, no repo cloning, no config files.

What mdd install Does

The install command sets up four things in one pass:

All four are idempotent — running mdd install or mdd update again never duplicates any of them.

Branch Guard — Never Work on main

mdd install registers a Claude Code PreToolUse hook that fires before every file write (Write, Edit, NotebookEdit) in any project with a .mdd/ directory. If the current git branch is main or master, the hook blocks the operation and explains what to do:

⛔  MDD BRANCH GUARD

    File modification is blocked on branch 'main'.
    MDD never writes files directly on main or master.

    Create a feature branch, then re-run your /mdd command:
      git checkout -b feat/<feature-name>

Why a hook and not just instructions? Claude's context compaction summarises earlier conversation turns when a session grows long. Instruction-based branch checks can be compacted away — the hook fires at the OS level on every tool call regardless of conversation length. The two layers work together: instructions guide Claude's decisions, the hook enforces the rule even when context is stale.

Branch naming MDD uses automatically:

When on a clean main, MDD creates the branch automatically without prompting. When on main with uncommitted changes, MDD stops and offers to commit or stash first before branching.

The Bootstrap Check

The first time you run any /mdd command in a project, the router performs a silent bootstrap before dispatching to the mode file. This only runs once per project.

Auto-Branch Behavior

When you invoke /mdd on the main or master branch, the router automatically creates a feature branch before any work begins:

# You are on: main
/mdd add user authentication with JWT tokens

# MDD automatically creates:
# git checkout -b feat/user-auth-jwt-tokens

# All work happens on the feature branch.
# At Phase 7d you choose: commit+merge, commit only, or skip.

This is not configurable - it is a guardrail. If you are already on a feature branch, no new branch is created and the router proceeds directly to the mode.

Build Mode - 7 Phases

Build mode is the core of MDD. It runs a structured 7-phase workflow with 3 mandatory quality gates. Every feature starts with documentation. Implementation follows from the doc. No exceptions.

Phase 0 - Bootstrap, Worktree Check & Mode Detection

Before any analysis begins, Phase 0 does three things simultaneously:

1. Worktree check - offers to create an isolated git worktree if you want to run parallel /mdd sessions on different features without interference.
2. Bootstrap - runs the one-time .mdd/ directory setup if this is the first invocation in this project.
3. Mode detection - inspects the argument string to determine whether this is a build, audit, status, note, scan, update, or any other mode, then loads the appropriate command file.

# Example invocations - Phase 0 reads the argument and routes accordingly
/mdd add user auth with JWT             # → Build mode
/mdd audit                              # → Audit mode
/mdd status                             # → Manage mode: status
/mdd note "switched to jose library"    # → Manage mode: note

Phase 1 - Understand the Feature (3 Parallel Agents)

Before asking you a single question, MDD launches 3 Explore agents in parallel to gather the context Claude needs to ask the right questions.

After all three agents return, Claude asks focused, context-aware questions. The exact questions depend on what the agents found.

Questions always asked (for every feature type):

• Does this feature depend on any existing features listed in .mdd/docs/?
• Are there edge cases or error scenarios you already know about?

Questions for backend and API features:

• Does this need database storage? Which model/table?
• Does this have API endpoints? What are the routes?
• Does this need authentication or authorization?
• Does this need real-time updates, background jobs, or external service integrations?

Phase 2 - Data Flow & Impact Analysis

For non-greenfield projects, MDD traces every piece of data the new feature will touch through the full stack. This prevents the most common integration failures.

The analysis traces four layers:

1. Backend origin - where is this value computed? Which file and line?
2. API transport - exact shape in the API response, TypeScript type definition
3. Frontend consumption - how the UI receives, transforms, and renders the value
4. Parallel computations - is the same concept computed elsewhere? Does it use consistent logic?

Results are written to .mdd/audits/flow-<feature>-<date>.md. A mandatory gate presents findings to you before documentation is written.

Automatic greenfield skip condition: Phase 2 is skipped automatically when .mdd/docs/ contains no existing docs and src/ contains fewer than 5 source files. There is nothing to trace on a blank project.

Phase 3 - Writing the Feature Doc

MDD creates .mdd/docs/<NN>-<feature-name>.md with a standard structure. This doc is the source of truth for everything that follows.

YAML frontmatter fields:

---
id: 01-user-auth
title: User Authentication
edition: MyApp
depends_on: []
source_files:
  - src/handlers/auth.ts
  - src/hooks/useAuth.ts
  - src/middleware/requireAuth.ts
routes:
  - POST /api/v1/auth/login
  - POST /api/v1/auth/logout
  - GET  /api/v1/auth/me
models:
  - users
test_files:
  - tests/unit/auth.test.ts
  - tests/e2e/auth.e2e.ts
data_flow: .mdd/audits/flow-user-auth-2026-05-07.md
last_synced: 2026-05-07
status: draft
phase: documentation
mdd_version: 8
tags: [auth, jwt, login, sessions, middleware]
known_issues: []
---

The 8 mandatory body sections:

# 01 - User Authentication

## Purpose
Why this feature exists and what user need it satisfies.

## Architecture
How this feature fits into the overall system design.

## Data Model
Fields, types, constraints, and relationships for any database models.

## API Endpoints
Request/response shapes, status codes, auth requirements.

## Business Rules
Logic that is not obvious from the code - validation rules, limits,
workflow decisions, and anything a new developer would need to know.

## Data Flow
Summary of the Phase 2 analysis - or a link to the full flow doc.

## Dependencies
What this feature requires from other features, services, or libs.

## Known Issues
Empty on creation. Populated during audits and implementation.

Phase 4 - Test Skeletons

From the documented endpoints, business rules, and edge cases, MDD generates test skeletons. These are intentionally failing stubs - real test cases with real assertions that will fail until the implementation exists.

describe('User Authentication', () => {
  describe('POST /api/v1/auth/login', () => {
    it('should return 200 and JWT token on valid credentials', async () => {
      // Arrange
      const payload = { email: 'user@example.com', password: 'correct-password' };

      // Act
      const res = await request(app).post('/api/v1/auth/login').send(payload);

      // Assert - minimum 3 assertions
      expect(res.status).toBe(200);
      expect(res.body).toHaveProperty('token');
      expect(res.body.token).toMatch(/^eyJ/); // JWT prefix
      expect.fail('Not implemented - MDD skeleton');
    });

    it('should return 401 on invalid password', async () => {
      expect.fail('Not implemented - MDD skeleton');
    });

    it('should return 422 on malformed email', async () => {
      expect.fail('Not implemented - MDD skeleton');
    });
  });

  describe('Business Rules', () => {
    it('should lock account after 5 failed attempts', async () => {
      expect.fail('Not implemented - MDD skeleton');
    });
  });
});

For features that require both unit tests and end-to-end tests, two parallel agents write both files simultaneously - unit tests and E2E tests are generated at the same time.

Phase 4b - Red Gate (Mandatory)

Immediately after generating skeletons, MDD runs your test suite against them. All new tests must fail.

# What a passing Red Gate looks like:
🔴 Red Gate: 12/12 failing (expected)
   All skeletons confirmed RED - ready to implement.

# What triggers a diagnosis:
🔴 Red Gate: 11/12 failing - 1 unexpected pass
   ⚠️  "should return 200 on valid credentials" passed without implementation.
   Diagnosis required before proceeding.

An unexpected pass means one of two things, and both must be diagnosed:

• The assertion is wrong (too weak - it would pass for any response)
• Pre-existing code already satisfies this test case (and the skeleton's scope overlaps existing work)

Phase 5 - Block-Structured Build Plan

MDD presents a layered build plan before writing a line of implementation code. Each block has four components:

Block 1 - Database Schema & User Model
  End-state:    Users table exists, migration runs cleanly, model exports User type
  Commit:       feat(auth): add users table migration and User model
  Verify:       pnpm db:migrate && pnpm typecheck
  Handoff:      User type exported from src/models/user.ts, migration in db/migrations/

Block 2 - Login Endpoint (depends on Block 1)
  End-state:    POST /api/v1/auth/login returns JWT on valid credentials, 401 on invalid
  Commit:       feat(auth): add login endpoint with JWT generation
  Verify:       pnpm test:unit -- --grep "auth login"
  Handoff:      generateToken() exported from src/utils/jwt.ts

Block 3 - Auth Middleware (depends on Block 2)
  End-state:    requireAuth middleware validates JWT and rejects invalid tokens
  Commit:       feat(auth): add requireAuth middleware
  Verify:       pnpm test:unit -- --grep "requireAuth"
  Handoff:      requireAuth middleware usable as Express middleware

Parallelization rules: Blocks in the same dependency layer can be marked Runs in: parallel agents. Two gates must pass before parallelism is allowed:

• File declaration gate - no two parallel agents can declare the same file in their block. Conflicts must be resolved by splitting into sequential blocks.
• Type dependency gate - if Block A exports a type that Block B imports, Block B cannot run in parallel with Block A.

Phase 6 - Implement: The Green Gate Loop

For each block in the build plan, MDD implements and then runs the Green Gate. The loop runs up to 5 iterations.

Iteration 1:
  Run: pnpm test:unit -- --grep "01-user-auth" && pnpm typecheck

  RESULT: 3 failing
    DIAGNOSE (required before any fix):
      - Exact error: "Cannot find module 'src/utils/jwt.ts'"
      - Which assumption was wrong: jwt.ts not created yet in this block
      - The ONE targeted fix: create src/utils/jwt.ts with generateToken()

    FIX: implementation only - tests are never modified
    REPORT: "Iteration 1 - Root cause: missing jwt.ts / Fix: created jwt.ts"

Iteration 2:
  Run: pnpm test:unit -- --grep "01-user-auth" && pnpm typecheck
  RESULT: All green ✓

  Regression check: pnpm test:unit (full suite)
  RESULT: No regressions ✓ - block complete, proceed to Block 2

Iteration 5 exhaustion protocol: If all 5 iterations are exhausted and tests are still failing, MDD stops and presents options:

• (a) Continue debugging - deeper investigation before attempting another fix
• (b) Narrow scope - split the block into smaller, more targeted pieces
• (c) Pause and review - step back and reassess the approach with you

Phase 7a - Quality Gates

After all blocks go green, a full quality gate runs before integration verification:

pnpm typecheck          # TypeScript must compile with zero errors
pnpm test:unit          # All unit tests must pass (including the full suite)
pnpm lint               # No linter warnings

Phase 7b - Integration Verification

Quality gates prove the code compiles and unit tests pass. Integration verification proves the feature actually works in the real runtime environment. The verification method depends on the feature type:

Phase 7c - Completion Signal

Once integration verification passes, MDD updates the feature doc:

• Sets status: complete and phase: verified
• Updates last_synced to today's date
• Appends any issues discovered during implementation to known_issues
• Updates .mdd/.startup.md with the new feature status

Phase 7d - Commit & Merge Options

MDD offers three options for handling git state at the end of a build:

• Commit & merge - stages all changes, commits with a conventional message, merges the feature branch to main, and asks if you want to push.
• Commit only - stages and commits on the feature branch, offers to push to remote for a PR workflow.
• Skip - leaves git state completely untouched for manual handling.

Audit Mode

Audit mode performs a structured code review against your MDD feature docs, finding violations, drift, and security issues. It scales with file count by running 1–8 parallel agents.

/mdd audit                    # audit all features
/mdd audit 01-user-auth       # audit a single feature's source files
/mdd audit src/handlers/      # audit a specific directory

A1 - Scope Detection

Before spawning any agents, MDD reads all .mdd/docs/*.md and .mdd/ops/*.md files, resolves their source_files lists to actual disk paths, de-duplicates, and checks for an interrupted audit job in .mdd/jobs/.

A2 - Per-Agent Config Setup

Before any agent reads a single source file, MDD writes the full job infrastructure to disk:

• .mdd/jobs/audit-<date>/MANIFEST.md - the master file list with state markers
• .mdd/jobs/audit-<date>/shard-N.md - the file list for each agent
• .mdd/jobs/audit-<date>/agent-N-config.md - self-contained startup instructions
• .mdd/jobs/audit-<date>/agent-N-notes.md - empty file for each agent's findings

The Manifest System

The MANIFEST is what makes audit resumption reliable. It is written before agents start and updated throughout the audit.

## Shard 1 (Agent 1) - files 1-15
[ ] src/handlers/auth.ts
[ ] src/handlers/users.ts
[ ] src/handlers/billing.ts
[ ] src/middleware/requireAuth.ts
...

## Shard 2 (Agent 2) - files 16-30
[ ] src/services/stripe.ts
[ ] src/utils/jwt.ts
...

State transitions follow a strict path:

Per-Agent Config Format

Each agent receives a self-contained config file - not the source code, not the full manifest. Just what it needs to do its job independently:

# Agent 1 Audit Config
Shard file:  .mdd/jobs/audit-2026-05-07/shard-1.md
Notes file:  .mdd/jobs/audit-2026-05-07/agent-1-notes.md
Manifest:    .mdd/jobs/audit-2026-05-07/MANIFEST.md

Startup Sequence:
1. Read this config file
2. Read shard-1.md to know your file list
3. Read MANIFEST.md - find the first [ ] entry in Shard 1
4. Read the last 20 lines of agent-1-notes.md for continuity
5. Begin the per-file loop

Audit Criteria:
- Check against feature docs in .mdd/docs/
- Flag: raw DB connections (use StrictDB), hardcoded secrets, missing input validation
- Flag: endpoints not documented in any feature doc
- Flag: source files modified after last_synced date

Per-File Loop

Each agent follows this exact sequence for every file in its shard. The order is strict and cannot be reordered:

A3 - Parallel Execution

All agents are spawned simultaneously after A2 setup is complete. Each agent operates independently, writing to its own notes file and updating the shared MANIFEST atomically. Agents do not communicate with each other.

A4 - Convergence Check

After all agents signal completion, the main Claude instance reads the MANIFEST and checks for any remaining [ ] or [~] entries:

• [ ] entries - file was never started. Re-assign to a new agent and run.
• [~] entries - file was in-progress when an agent was interrupted. Re-process the file from scratch (mark back to [ ] first).

Convergence repeats until the MANIFEST has no [ ] or [~] entries.

A5 - Merge Agent Notes

All agent-N-notes.md files are merged in manifest order (not agent order) into a single .mdd/audits/notes-<date>.md. Manifest order ensures findings appear in the same sequence as the files were processed - easier to cross-reference.

A6 - Analyze Findings

The analysis phase reads only the merged notes file - not the source code again. This is the key efficiency: all source reads happen in A3, and the analysis works from structured notes. The output is .mdd/audits/report-<date>.md with severity-rated findings and effort estimates.

🔍 MDD Audit Complete

Findings: 20 total (3 P1 Critical, 5 P2 High, 8 P3 Medium, 4 P4 Low)
Report: .mdd/audits/report-2026-05-07.md

Top issues:
  1. Raw database connection in src/handlers/billing.ts (P1 - use StrictDB)
  2. JWT secret hardcoded in src/middleware/auth.ts (P1 - use env var)
  3. No rate limiting on /api/v1/auth/login (P2)
  4. 3 endpoints not documented in any feature doc (P2)

Estimated fix time: 6 hours (traditional) → 45 minutes (MDD)

Options:
  [A] Fix all findings
  [B] Fix P1 + P2 only
  [R] Review first - show findings list before fixing

A7 - Present and Fix

MDD presents findings grouped by severity. You choose how to proceed. Each fix follows the same Green Gate loop as Build mode - diagnose before fix, tests must pass, regressions checked.

Incremental vs Full Audit

When you audit a single feature (/mdd audit 01-user-auth), only that feature's source_files are included in scope. This is an incremental audit - it does not replace the full audit report, it appends to it.

A full /mdd audit with no arguments audits all files registered across all feature docs and ops runbooks.

Interrupted Audit Detection and Resume

Phase A1 checks .mdd/jobs/ for any directory matching audit-*. If found, MDD reads the MANIFEST to determine how far the previous audit got:

Found interrupted audit from 2026-05-07.
MANIFEST shows 23/57 files complete.
  [x] 23 files complete
  [~]  1 file in progress (will be re-processed)
  [ ] 33 files remaining

  [R] Resume - continue from where it left off
  [D] Discard - delete and start fresh

Choosing Resume re-runs A2 (updating config files to reflect remaining work), then continues from A3 with fresh agents. Previously completed notes are preserved and merged in A5.

Status, Notes, Scan & Update

These commands handle daily workflow management - checking project state, logging decisions, detecting drift, and keeping docs in sync with code.

/mdd status

Gives a complete project snapshot without reading any source files.

📊 MDD Status

Feature docs:     9 files in .mdd/docs/
Ops runbooks:     2 files in .mdd/ops/
Last audit:       2026-05-01 (20 findings, 17 fixed, 3 open)
Test coverage:    125 unit tests, 8 E2E tests
Known issues:     3 tracked across 2 features
Quality gates:    0 files over 300 lines

Initiatives:      1 total (1 active)
  Active waves:   auth-system-wave-2 [1/2 features complete]

MDD version:      v8 - all files up to date

Drift check:
  8 features in sync
  1 feature possibly drifted  ← run /mdd scan for details

After displaying the snapshot, /mdd status automatically rebuilds .mdd/.startup.md with the latest project state. This keeps Claude oriented for all future sessions without requiring a status command to be run explicitly.

/mdd note

Three subcommands for maintaining a running decision log in .mdd/.startup.md.

# Append a timestamped note
/mdd note "switched from PostgreSQL to SQLite for dev - easier local setup"

# List all notes
/mdd note list

# Clear all notes (asks for confirmation before wiping)
/mdd note clear

Notes are appended below a --- separator in .startup.md. The auto-generated section above the separator is rebuilt on each /mdd status. The notes section is append-only and preserved across rebuilds - cleared only by /mdd note clear.

## Notes
- [2026-05-07] switched from JWT lib to jose for better ESM support
- [2026-05-05] decided against Redis for session store - overkill for current scale
- [2026-05-03] deferred email verification to after MVP - tracked in 03-notifications

/mdd scan

Detects features whose source files have changed since last_synced. Uses a single Explore agent to run all git checks in parallel, then classifies each feature. Scan also checks the freshness of .mdd/connections.md — a missing file is flagged as broken, and a file whose modification timestamp is older than the most recently modified feature doc is flagged as drifted.

🔍 MDD Scan - Drift Report

  ✅ 01-project-scaffolding   - in sync (last synced: 2026-04-15)
  ✅ 02-user-auth             - in sync (last synced: 2026-05-07)
  ⚠️  04-content-builder       - DRIFTED (3 commits since 2026-04-01)
                                  Latest: "fix: markdown heading parser (a3f4c1b)"
  ❌  07-github-pages           - broken reference (docs/index.html not found)
  ❓ 08-old-feature            - untracked (no last_synced field)
  ⚠️  connections.md            - DRIFTED (older than most recent feature doc)

Recommended actions:
  /mdd update 04   - re-sync content-builder doc with code
  /mdd update 07   - fix broken file reference
  /mdd upgrade     - stamp 08-old-feature with last_synced
  /mdd connect     - rebuild connections map

/mdd update <feature-id>

Re-syncs a feature doc after its source code has changed. The update follows phases U1–U6:

# Can be called by number or full slug
/mdd update 04
/mdd update 04-content-builder

/mdd deprecate <feature-id>

Archives a feature cleanly and flags all dependents so nothing is silently broken.

1. Runs an impact check - reads all other feature docs and lists any that reference this feature in depends_on.
2. Shows a deprecation summary with the full dependent list. Requires your confirmation.
3. Moves the doc to .mdd/docs/archive/.
4. Adds a known_issues warning to each dependent doc: "Depends on deprecated feature: <id>".
5. Asks separately about deleting source files and test files - never auto-deletes. Both are optional and confirmed individually.

Lifecycle: Reverse-Engineer, Graph, Upgrade

/mdd reverse-engineer

Generates MDD documentation from existing undocumented code. Three call forms:

# Scan src/ for any files not registered in any .mdd/docs/*.md
/mdd reverse-engineer

# Generate a doc for a specific file
/mdd reverse-engineer src/handlers/billing.ts

# Regenerate an existing doc - shows before/after comparison
/mdd reverse-engineer 04-content-builder

For 4 or more files, reverse-engineer uses parallel Explore agents to read files in batches - same agent scaling as audit mode.

When called with no argument, the scan result is shown first:

Found 4 undocumented source files:
  src/handlers/billing.ts     - no feature doc references this file
  src/services/stripe.ts      - no feature doc references this file
  src/utils/currency.ts       - no feature doc references this file
  src/hooks/useBilling.ts     - no feature doc references this file

Generate docs for all 4? [Y/n]
Or specify a subset: [1,3] to generate for billing.ts and currency.ts only

/mdd graph

Renders the full cross-feature dependency map by reading all depends_on fields across .mdd/docs/*.md. Detects four classes of issues:

📊 MDD Dependency Graph

  01-project-scaffolding
  06-command-system ──────────────────► 01-project-scaffolding
  09-integrations ────────────────────► 06-command-system
  04-content-builder ─────────────────► 03-database-layer
  02-user-auth (orphan)

Issues:
  ⚠️  09-integrations depends on 06-command-system (status: in_progress) - risky
  ❌  05-testing-framework depends on 10-old-auth (deprecated) - broken dep
  ℹ️  02-user-auth - orphan (no dependents, no dependencies)

Graph saved: .mdd/audits/graph-2026-05-07.md

/mdd rebuild-tags [--force]

Scans all feature docs (.mdd/docs/*.md) and ops runbooks (.mdd/ops/*.md), generates a tags: field for any doc missing one, then rebuilds .startup.md with the new tag format. Safe to run multiple times — docs that already have tags: are skipped unless --force is passed.

Tags are 4–8 domain-concept keywords that identify what a doc is about. They appear in .startup.md next to each feature name, giving Claude a fast way to detect when a prompt relates to an already-documented feature or runbook without loading full docs into context.

/mdd rebuild-tags

🏷️  Rebuild Tags — Inventory
  01-docs-site             ❌ missing
  02-dashboards-showcase   ❌ missing
  03-install-local-flag    ✅ present

✅ 01-docs-site — tags: [github-pages, documentation, landing-page, user-guide]
✅ 02-dashboards-showcase — tags: [dashboard, tui, showcase, mdd-dashboard]

.startup.md rebuilt:
  - 01-docs-site (complete) [github-pages, documentation, landing-page, user-guide]
  - 02-dashboards-showcase (complete) [dashboard, tui, showcase, mdd-dashboard]
  - 03-install-local-flag (complete) [cli, install, local-install, flags]

/mdd upgrade

Batch-patches missing frontmatter fields across all .mdd/docs/*.md files. Safe to run multiple times - fields that are already present are never overwritten.

Inferring defaults: MDD uses these sources to infer sensible default values rather than leaving fields blank:

• last_synced - inferred from git log --follow -1 --format="%as" <source_file> for each registered source file
• status - inferred from phase field if present; defaults to draft if phase is absent
• phase - inferred from status; complete status maps to verified phase
• mdd_version - stamped with the current MDD version number
• path - inferred by reading each doc's full content and mapping it into the existing path vocabulary found across other docs. Content-aware inference: uses the Purpose and Architecture sections to place the feature in the product tree. Always shows the full plan for confirmation before writing — never assigns paths silently.

/mdd upgrade

Scanning .mdd/docs/ for missing frontmatter fields...

Upgrade plan (8 files to patch):
  04-content-builder    - add: last_synced (inferred: 2026-04-01), mdd_version
  08-old-feature        - add: last_synced (inferred: 2026-03-15), status, phase, mdd_version
  05-email-service      - add: path (inferred: Notifications/Email)
  08-old-feature        - add: path (inferred: Platform/Legacy)
  ...

Apply upgrades? [Y/n]

✓ 8 files patched. Run /mdd scan to check drift status.

/mdd import-spec

Converts one or more spec documents — the large, free-form markdown files that accumulate during brainstorming, product discovery, or requirements sessions — into properly structured MDD feature docs. Nothing from the spec is lost: every piece of information is preserved and placed into the correct section of the generated docs.

Command Syntax

# Convert a single spec file
/mdd import-spec docs/spec.md

# Convert multiple files — merged and deduplicated before processing
/mdd import-spec product-brief.md technical-notes.md customer-requirements.md

The 5 Phases

Import Spec — Dry-Run Preview

Path tree:
  Auth/
    Login              → 03-login.md (new)
    Signup             → 04-signup.md (new)
  E-commerce/
    Cart/
      Checkout         → 05-cart-checkout.md (new)
    Orders             → 06-order-history.md (new)

Feature slugs to be created:
  03-login, 04-signup, 05-cart-checkout, 06-order-history

Content mapping:
  "Login" section in spec  → 03-login.md (Purpose + Business Rules)
  "Auth flows" section     → merged into 03-login.md and 04-signup.md
  "Cart checkout" section  → 05-cart-checkout.md

Merge summary:
  2 overlapping sections merged (auth flows → login + signup)
  0 sections discarded — all content preserved

Proceed with import? [Y/n]

Auto-Detect Structure

Import Spec adapts the output structure to the size and complexity of the spec. The detection logic reads the number of distinct root-level path areas and the total feature count:

Content Preservation Rule

Nothing from the spec is discarded. Every sentence, bullet point, table, and code block from the input files ends up in at least one generated doc. If content does not fit cleanly into one of the 8 mandatory sections, it is placed in a ## Notes from Spec subsection. The dry-run preview includes a merge summary that lists every source section and where it maps to in the output.

Duplicate Handling (Multi-File)

When multiple files are passed, MDD performs a semantic merge before writing docs. This means:

• Sections that cover the same feature from different angles are combined — the output contains the union of both descriptions, not a duplicate.
• Identical or near-identical paragraphs are deduplicated. One canonical version is kept.
• Contradictions (e.g., two files specify different timeout values for the same endpoint) are flagged in the dry-run preview and left as a known_issues entry in the generated doc, rather than silently picking one.

Connections Map

.mdd/connections.md is a committed, always-current pre-computed relationship map for your entire .mdd/docs/ corpus. It gives Claude and the dashboard tools an instant, single-file view of how every feature relates to every other — without having to scan all frontmatter on every command invocation.

/mdd connect

Triggers a manual full rebuild of .mdd/connections.md. Reads every doc in .mdd/docs/*.md, re-derives all relationships, and writes the file from scratch. Run this any time you want to force a fresh map — for example, after a batch of manual edits that bypassed the normal MDD workflow.

/mdd connect

Rebuilding connections map...
  Scanned 12 feature docs
  Detected 8 dependency edges
  Found 3 source file overlaps

✓ .mdd/connections.md written

Contents of connections.md

The file has four sections, always rendered in this order:

1 — Path Tree

All feature docs grouped by their path field, sorted alphabetically within each level, and formatted with tree characters. Gives an instant product-hierarchy view of every documented feature.

## Path Tree

Auth/
  ├── Login              (02-user-auth)
  └── Signup             (11-user-registration)

E-commerce/
  ├── Cart/
  │   ├── Add Item       (06-cart-add-item)
  │   └── Checkout       (07-cart-checkout)
  └── Orders             (09-order-history)

Notifications/
  ├── Email              (05-email-service)
  └── Push               (12-push-notifications)

Platform/
  └── Setup              (01-project-scaffolding)

2 — Dependency Graph

A Mermaid diagram of all depends_on relationships across the full doc corpus. Nodes are colour-coded by status using classDef declarations so the graph is readable without opening individual docs.

## Dependency Graph

```mermaid
graph TD
  01-project-scaffolding
  02-user-auth --> 01-project-scaffolding
  07-cart-checkout --> 02-user-auth
  09-order-history --> 07-cart-checkout

  classDef complete    fill:#0d9488,color:#fff,stroke:none
  classDef in_progress fill:#d97706,color:#fff,stroke:none
  classDef draft       fill:#6b7280,color:#fff,stroke:none
  classDef deprecated  fill:#374151,color:#9ca3af,stroke:none

  class 01-project-scaffolding,02-user-auth complete
  class 07-cart-checkout in_progress
  class 09-order-history draft
```

3 — Source File Overlap

Lists every source file that is registered in the source_files field of two or more feature docs. Files that appear in multiple docs are co-change risk signals — a commit to that file likely touches multiple documented features and may require doc updates in all of them.

## Source File Overlap

Files referenced by 2 or more feature docs:

  src/middleware/requireAuth.ts
    → 02-user-auth
    → 07-cart-checkout

  src/utils/jwt.ts
    → 02-user-auth
    → 05-email-service

  src/db/client.ts
    → 01-project-scaffolding
    → 03-database-layer
    → 07-cart-checkout

4 — Warnings

Issues detected during the rebuild pass. Warnings are informational — they are written to the file and shown in the terminal but do not block the rebuild or fail the command.

## Warnings

  ⚠️  Broken depends_on: 08-old-feature references 99-missing-doc (not found)
  ⚠️  Circular dependency: 04-content-builder ↔ 06-command-system
  ⚠️  Missing path: 10-legacy-import (no path field — excluded from Path Tree)

Ironclad Sync — Automatic Regeneration

You rarely need to run /mdd connect manually. Every doc-mutating operation regenerates connections.md automatically as its final step:

Staleness Detection

Two commands actively check whether connections.md is present and current:

• /mdd status — checks for a missing or stale connections.md and includes it in the status output. A missing file is flagged as broken; a file whose modification timestamp is older than the most recently modified feature doc is flagged as drifted.
• /mdd scan — checks connections.md freshness as part of its drift detection pass. A missing file appears as a broken entry; a stale file appears as drifted. Both recommend /mdd connect to fix.

🔍 MDD Scan — Drift Report

  ✅ 01-project-scaffolding   - in sync
  ✅ 02-user-auth             - in sync
  ⚠️  04-content-builder       - DRIFTED (3 commits since last_synced)
  ❌  connections.md           - BROKEN (file missing — run /mdd connect)

Recommended actions:
  /mdd update 04   - re-sync content-builder doc with code
  /mdd connect     - rebuild connections map

Initiative & Wave Planning

For large features that span multiple weeks or deployment cycles, MDD provides a structured three-level planning system.

/mdd plan-initiative

Creates a new initiative with named waves. MDD asks a series of product-level questions before writing anything:

• What is the initiative name and goal?
• What are the named waves and their demo-states?
• Are there open product questions that must be resolved before planning can begin?

The initiative file uses hash locking - a SHA-256 hash of the frontmatter is stored in the file. If you manually edit the frontmatter, the hash will not match on the next MDD operation and you will be required to run /mdd plan-sync before continuing.

---
slug: auth-system-overhaul
title: Auth System Overhaul
goal: Replace session-based auth with JWT across all services
status: active
waves:
  - auth-system-wave-1
  - auth-system-wave-2
open_questions: []
mdd_hash: a3f4c1b...
mdd_version: 8
created: 2026-05-01
---

After creating the initiative, MDD chains directly to /mdd plan-wave for the first wave.

/mdd plan-wave <wave-slug>

Plans a wave - identifies and orders the feature docs that will be built in this wave. Three gates are enforced before planning can proceed:

1. Open questions gate - all product questions for the wave must be resolved.
2. Depends-on gate - if this wave depends on another wave, that wave must have status: complete before this one can be planned.
3. Feature ordering check - internal feature dependencies within the wave are validated. If Feature B depends on Feature A, Feature A is placed first in the execution order.

---
slug: auth-system-wave-1
initiative: auth-system-overhaul
title: Wave 1 - Foundation
demo_state: "A user can register, log in, and see their profile page"
depends_on: []
features:
  - 01-user-model        # must run first - 02 depends on it
  - 02-jwt-auth          # depends on 01
  - 03-user-profile      # depends on 02
status: planned
mdd_version: 8
---

/mdd plan-execute <wave-slug>

Runs the full MDD build flow for every feature in the wave, in dependency order.

Two execution modes:

• Automated - minimal interruptions. MDD pauses only on 5-iteration Green Gate failures or integration failures. All other gates are passed through automatically.
• Interactive - full MDD gates on every feature, full plan confirmations, and explicit "proceed?" prompts between phases. Use this when learning MDD or when features are high-risk.

Resume behavior: Features that are already status: complete are skipped. If an execution is interrupted, re-running /mdd plan-execute <wave-slug> resumes from the first feature with status: active or status: planned.

/mdd plan-execute auth-system-wave-1

Wave: auth-system-wave-1 - 3 features
  ✓ 01-user-model        - already complete, skipping
  → 02-jwt-auth          - starting build
  ○ 03-user-profile      - planned

Building 02-jwt-auth...
[Runs full Build Mode phases 0–7d for this feature]

Building 03-user-profile...
[Runs full Build Mode phases 0–7d for this feature]

Wave complete. Demo-state verified:
  "A user can register, log in, and see their profile page" ✓

/mdd plan-sync

Reconciles manual edits to initiative or wave files by comparing the stored mdd_hash against the current file content.

• If hashes match - no manual edits detected, nothing to sync.
• If hashes differ - shows a diff of what changed, asks you to confirm the changes are intentional, then updates the hash and may trigger a version bump on the initiative file.
• What triggers a version bump: adding or removing waves, changing demo_state, or reordering features within a wave. Cosmetic edits (typos in text) do not trigger a version bump.
• Stale wave flagging: if wave content changes after features in that wave are already complete, the wave is flagged as stale and you are asked to confirm the completed features still satisfy the new demo-state.

/mdd plan-remove-feature <wave> <feature>

Removes a feature from a wave without deleting the feature doc or source files. Updates the wave's feature list, re-validates ordering for remaining features, and flags any other features that depends_on the removed one.

/mdd plan-cancel-initiative <slug>

Cancels an initiative cleanly:

1. Sets initiative status: cancelled.
2. Archives all wave files to .mdd/waves/archive/.
3. Adds a known_issues note to all feature docs that were part of this initiative.
4. Does not delete any source files, test files, or feature docs.

Ops Runbooks

Ops runbooks capture deployment and infrastructure operations in a structured, reproducible format. Once written, a runbook can be executed reliably by Claude without re-asking questions.

Project vs Global Scope

When creating a runbook, MDD asks whether it should be project-scoped or global:

• Project scope - stored in .mdd/ops/<slug>.md. Committed to git. Specific to this project.
• Global scope - stored in ~/.claude/ops/<slug>.md. Available in all projects. For runbooks that apply across multiple projects (e.g., "deploy to Dokploy").

Runbook Frontmatter Format

---
slug: swarmk-dokploy
title: Deploy SwarmK to Dokploy
scope: project
services:
  - name: api
    image: ghcr.io/myorg/swarmk-api:latest
    port: 3000
    health_check: "curl -f http://localhost:3000/health"
  - name: worker
    image: ghcr.io/myorg/swarmk-worker:latest
    health_check: "curl -f http://localhost:3001/ready"
regions:
  - name: eu-west-1
    deploy_order: 1
    role: canary
  - name: us-east-1
    deploy_order: 2
    role: primary
deployment_strategy:
  type: sequential
  gate: health_check
  on_gate_failure: stop
credentials:
  - DOKPLOY_API_KEY
  - DOCKER_REGISTRY_TOKEN
mcp_servers:
  - dokploy-mcp
last_synced: 2026-05-07
mdd_version: 8
---

/mdd runop <slug>

Executes a runbook in full. The execution flow has four stages:

/mdd update-op <slug>

Re-asks all runbook creation questions with the current values pre-filled. You can accept, modify, or skip any field. Useful for updating service images, changing regions, or modifying gate behavior after a deployment strategy change.

/mdd ops list

Shows all runbooks from both global (~/.claude/ops/) and project (.mdd/ops/) scopes in a unified view, with last-run status and the timestamp of last_synced.

📋 Ops Runbooks

Global (~/.claude/ops/):
  swarmk-dokploy     Last run: 2026-05-07  Status: ✓ pass  Regions: 2/2
  vercel-deploy      Last run: 2026-04-22  Status: ✓ pass  Regions: 1/1

Project (.mdd/ops/):
  seed-staging-db    Last run: 2026-05-01  Status: ✓ pass
  reset-test-env     Last run: never

Feature Doc Reference

YAML Frontmatter - All Fields

The 8 Mandatory Body Sections

Every feature doc must contain these sections in this order. Missing sections cause Phase 3 to pause and ask for the missing information before continuing.

1. Purpose - Why this feature exists. Written for a developer who has never seen this codebase.
2. Architecture - How this feature fits into the overall system. References to other components, services, or patterns it uses.
3. Data Model - Fields, types, constraints, and relationships. If no database involvement: "No persistent storage."
4. API Endpoints - Full request/response shapes, status codes, auth requirements. If no API: "No API endpoints."
5. Business Rules - Validation rules, limits, workflow decisions, invariants. The things that are not obvious from reading the code.
6. Data Flow - Summary of the Phase 2 analysis, or a link to the full flow doc at data_flow path.
7. Dependencies - What this feature requires: other features (matching depends_on), external services, or specific library versions.
8. Known Issues - Empty on creation. Populated during audits and implementation. Matches the known_issues frontmatter field.

depends_on Rules

This field has strict rules that are enforced by /mdd graph:

• Feature docs only - never list task docs (one-off, frozen in time, no ongoing contract). Task docs are ephemeral; feature docs are permanent.
• IDs must reference existing docs - broken references are flagged by /mdd graph as broken dependencies.
• Only add, never remove without discussion - removing a dependency from depends_on breaks the assumption that downstream features have what they need. If you need to remove one, run /mdd graph first to understand the impact.

last_synced and Drift Detection

The last_synced date is the anchor for /mdd scan. MDD runs:

git log --after="<last_synced>" --oneline -- <source_file_1> <source_file_2>

If this command returns any commits, the feature is classified as drifted. The scan report shows the most recent commit message and hash, giving you context on what changed.

last_synced is updated by: /mdd (end of Phase 7), /mdd update (end of U6), and /mdd upgrade (when inferring from git log).

mdd_version Stamping

Every doc created or last updated by MDD gets the current mdd_version integer stamped in frontmatter. This integer increments with each MDD workflow release. The /mdd status command reads all docs and groups them by version, making it easy to see which docs need to be upgraded.

The path Field

The path field is a slash-delimited breadcrumb that places each feature doc in a product-level hierarchy. It exists to answer the question: where does this feature live in the product?

It is completely separate from depends_on. depends_on describes build order and runtime requirements. path describes navigation — how a human would browse to this feature in a dashboard, a doc browser, or a tree view. A feature can share a path segment with another feature it has no dependency relationship with at all.

Format Rules

How Claude Assigns path in Build Mode Phase 3

When writing a new feature doc, Claude follows this sequence to assign path:

1. Read existing paths — scans all path: fields in .mdd/docs/*.md to discover the established vocabulary (what segment names already exist).
2. Infer from product mental model — uses the feature title, purpose, and tech stack context to map the feature into the existing tree. If an obvious parent segment already exists, it is reused.
3. Ask only if ambiguous — if the feature could plausibly sit under two different parents, Claude presents the two options and asks before writing. It never silently coins a new root segment if an existing one fits.

How /mdd scan Flags Missing path

Docs without a path field appear in the scan report under a dedicated section:

🔍 MDD Scan — Path Coverage

  ✅ 01-project-scaffolding   - path: Platform/Setup
  ✅ 02-user-auth             - path: Auth/Login
  ⚠️  05-email-service         - missing path field
  ⚠️  08-old-feature           - missing path field

2 docs missing path. Run /mdd upgrade to batch-assign.

How /mdd upgrade Batch-Adds path

When /mdd upgrade detects docs missing the path field, it reads each doc's full content (not just git history) to infer an appropriate path from the feature's purpose and existing vocabulary. It then presents the full plan for confirmation before writing anything:

Path inference plan (2 docs):
  05-email-service    → Notifications/Email   (inferred from: purpose section, existing Notifications/Push)
  08-old-feature      → Platform/Legacy       (inferred from: architecture section mentions legacy API)

Apply path assignments? [Y/n]

Example Tree View from path Values

Given the following path fields across a project's feature docs, a dashboard would render this tree:

Auth/
  ├── Login           (02-user-auth)
  ├── Signup          (11-user-registration)
  └── Password Reset  (14-password-reset)

E-commerce/
  ├── Cart/
  │   ├── Add Item    (06-cart-add-item)
  │   └── Checkout    (07-cart-checkout)
  └── Orders          (09-order-history)

Notifications/
  ├── Email           (05-email-service)
  └── Push            (12-push-notifications)

Platform/
  └── Setup           (01-project-scaffolding)

This tree is rendered by mdd-dashboard and mdd-tui as a navigable hierarchy alongside the depends_on graph. The two views are complementary: the tree shows product structure; the graph shows build order.

The .mdd/ Directory

All MDD artifacts live in one place. The directory structure is created automatically on first run - you never need to create it manually.

.mdd/
├── docs/                             # Feature docs (source of truth for all features)
│   ├── 01-project-scaffolding.md     # Auto-numbered, YAML frontmatter + 8 sections
│   ├── 02-user-auth.md
│   ├── 03-database-layer.md
│   └── archive/                      # Deprecated/cancelled docs (never deleted)
│       └── 05-old-feature.md
│
├── initiatives/                      # Initiative files (/mdd plan-initiative)
│   ├── auth-system-overhaul.md
│   └── archive/                      # Cancelled initiative files
│
├── waves/                            # Wave execution files (/mdd plan-wave)
│   ├── auth-system-wave-1.md
│   ├── auth-system-wave-2.md
│   └── archive/                      # Cancelled wave files
│
├── ops/                              # Project-scoped deployment runbooks (/mdd ops)
│   ├── seed-staging-db.md
│   └── reset-test-env.md
│
├── audits/                           # ⚠️  GITIGNORED - regenerated by /mdd audit
│   ├── flow-user-auth-2026-05-07.md  # Phase 2 data flow analysis
│   ├── notes-2026-05-07.md           # Merged agent reading notes (Audit A5)
│   ├── report-2026-05-07.md          # Severity-rated findings report (Audit A6)
│   ├── scan-2026-05-07.md            # Drift detection report (/mdd scan)
│   ├── graph-2026-05-07.md           # Dependency graph (/mdd graph)
│   └── MANIFEST-2026-05-07.md        # Permanent record of which files had findings
│
├── jobs/                             # ⚠️  GITIGNORED - deleted when audit completes
│   └── audit-2026-05-07/             # Active audit job directory
│       ├── MANIFEST.md               # Live state tracking for all agents
│       ├── shard-1.md                # File list for Agent 1
│       ├── shard-2.md                # File list for Agent 2
│       ├── agent-1-config.md         # Self-contained startup instructions
│       ├── agent-1-notes.md          # Agent 1 findings (written during A3)
│       ├── agent-2-config.md
│       └── agent-2-notes.md
│
├── connections.md                    # Pre-computed relationship map (committed to git)
└── .startup.md                       # Auto-generated session context

What's Gitignored and Why

Everything else in .mdd/ is committed - feature docs, initiatives, waves, ops runbooks, and .startup.md are all part of your project's knowledge base. They should be versioned alongside your source code.

The .startup.md Format

This file is the session context that orients Claude at the start of every conversation. It is rebuilt automatically after every status, audit, or note command. The format has two parts separated by ---:

## Project Snapshot
Generated: 2026-05-07 | Branch: feat/user-auth

## Stack
Framework: Express + React | DB: PostgreSQL | Host: Dokploy

## Features Documented
- 01-project-scaffolding (complete) [typescript, express, project-setup, scaffolding]
- 02-user-auth (in_progress) [auth, jwt, login, sessions, middleware]
- 03-database-layer (complete) [postgres, drizzle, migrations, schema]
- 04-content-builder (complete) [markdown, content, cms, rendering]

## Ops Runbooks
- prod-deploy [deploy, dokploy, docker, eu-west, canary, health-check]

## Last Audit
2026-05-01 - 20 findings, 17 fixed, 3 open

## Active Initiative
auth-system-overhaul - Wave 2: 1/2 features complete

## Rules Summary
[key rules excerpted from CLAUDE.md]

---
## Notes
- [2026-05-07] switched from JWT lib to jose for better ESM support
- [2026-05-05] decided against Redis - overkill for current scale

The section above --- is fully rebuilt each time. The ## Notes section below is append-only and preserved across rebuilds - it is only cleared by /mdd note clear.

The [tags] on each feature and ops line are populated from the tags: frontmatter field in each doc. They are what allow Claude to detect prompt overlap without loading full doc content — see Claude Automatically Suggests MDD below.

Auto-Rebuild Behavior

.startup.md is rebuilt automatically at the end of these commands: /mdd status, /mdd audit, /mdd note, /mdd rebuild-tags. You never need to manually edit it - MDD keeps it current. If it becomes stale (e.g., you moved files manually), run /mdd status to force a rebuild.

Claude Automatically Suggests MDD

mdd install injects a small guidance block into ~/.claude/CLAUDE.md (global install) or the project CLAUDE.md (--install-local). This block tells Claude to evaluate every implementation, modification, or infrastructure request before responding — as long as a .mdd/ directory exists in the current project.

Claude checks four things, in order:

1. Does it already exist? Scans the tags in .startup.md for any feature doc or ops runbook that overlaps with the request.
   "This looks related to 02-user-auth. Want to use /mdd update 02 to modify it, or /mdd audit 02 to review it first?"
2. Is it ops or infrastructure? Deploy, CI/CD, Docker, commit hooks, cron jobs, webhooks, DNS, SSL, rollback, health checks.
   "This sounds like an ops procedure. Want to document it as a repeatable runbook with /mdd ops deploy to staging?"
3. Is it initiative-scale? Three or more independent features or concerns in one request.
   "This looks initiative-scale. Want to plan it with /mdd plan-initiative?"
4. Is it a single new feature?
   "Want me to use /mdd add payment processing to build this with documentation and tests first?"

Claude always asks — it never auto-invokes /mdd. If you say no, it proceeds with direct implementation as normal. Bug fixes, typo corrections, config tweaks, and one-off shell commands are never flagged.

Overlap detection is lightweight: Claude scans the [tags] in .startup.md — a compact file already injected into every conversation — rather than loading full feature docs into context. No extra tokens, no performance penalty.

The injection is idempotent: running mdd install or mdd update again never duplicates the guidance block. To populate missing tags on existing docs (so overlap detection works on older projects), run /mdd rebuild-tags.

Global Ops: ~/.claude/ops/

Runbooks stored here are available in every project that uses MDD. These are ideal for:

• Deployment procedures that apply to multiple projects (e.g., "deploy to Dokploy")
• Infrastructure operations that are not project-specific (e.g., "create new VPS")
• Personal automation that you reuse across projects

Global runbooks are shown alongside project runbooks in /mdd ops list but are stored outside the project repo and are not committed.

MDD Versioning

MDD uses an integer version number (not semver) for the workflow itself. This is distinct from the npm package version. The workflow version tracks the structure and semantics of MDD docs - phases, frontmatter fields, section names.

Current MDD workflow version: 8

The mdd_version Field

Every file created or last updated by MDD is stamped with mdd_version: N in its YAML frontmatter. This applies to feature docs, initiative files, wave files, and ops runbooks. It records which version of the workflow last touched this file.

mdd install Version Safety

Before overwriting mdd.md in ~/.claude/commands/, mdd install reads its mdd_version field and compares it against the version bundled in the npm package. Mode files in ~/.claude/mdd/ are always overwritten silently.

• If the installed version is older - overwrite is allowed. New file is written.
• If the installed version is the same - no overwrite needed. Files are identical.
• If the installed version is newer - MDD warns you and does not silently downgrade. You must explicitly confirm to overwrite.

$ mdd install

MDD v1.3.0 — Claude Code workflow installer
Install directory: ~/.claude/commands

  ✓ mdd.md

  ✓ mdd-audit.md
  ✓ mdd-build.md
  ✓ mdd-lifecycle.md
  ✓ mdd-manage.md
  ✓ mdd-ops.md
  ✓ mdd-plan.md

  7 file(s) installed/updated

/mdd status Version Breakdown

The status command reads all .mdd/docs/*.md files and groups them by their mdd_version field:

MDD version: v8 (current)
  v8: 9 files - up to date
  v7: 2 files - run /mdd upgrade to refresh these docs
  v0 (unversioned): 1 file - created before versioning was introduced

/mdd upgrade for Batch Patching

After updating MDD to a new version, run /mdd upgrade to stamp all existing docs with the current mdd_version field. Upgrade also adds any new frontmatter fields introduced in the new version (e.g., if v9 adds a risk_level field, upgrade would add it with a sensible default).

Migrating from the Starter Kit

If you were using MDD inside the Claude Code Mastery Project Starter Kit, here is what changed and what you need to do.

What Changed

Migration Steps

npm install -g @thedecipherist/mdd
mdd install

/mdd upgrade

/mdd status

What's Not Included in This Package

The standalone MDD package contains only the MDD workflow. The starter kit's other components are separate and not part of @thedecipherist/mdd:

• Hooks configuration - the starter kit's pre/post hooks for linting, testing, and context injection are not included.
• CLAUDE.md templates - the starter kit's opinionated CLAUDE.md with TypeScript rules, error handling standards, and quality gates is not included.
• StrictDB - the database wrapper is a separate npm package (strictdb), not part of MDD.
• Custom agents and skills - the starter kit includes custom Claude agents and skills beyond the MDD workflow.

If you want the full starter kit experience in a new project, clone the Claude Code Mastery Project Starter Kit - MDD is included and pre-configured. If you only want MDD in an existing project, the standalone package is all you need.

Dashboards

MDD ships with two companion dashboards for exploring your .mdd/ workspace. Both are available as standalone packages today and will soon be merged directly into the mdd package — launchable via the mdd command without a separate install.

mdd-tui — Terminal Dashboard

A live terminal UI for navigating your MDD workspace without leaving the command line. Split-pane view: scrollable file list on the left, full markdown render on the right. Shows feature doc health, drift status, audit reports, initiative and wave progress, and ops runbook content.

npm install -g mdd-tui
mdd-tui

Run from any project directory that has a .mdd/ folder.

Navigation

What it shows

• Initiatives — collapsible tree with wave progress (e.g. 2/3 features complete)
• Feature docs — drift status icons: ✓ in sync, ⚠ drifted, ✗ broken reference
• Ops runbooks — last runop date and service health at a glance
• Audit reports — findings summary with severity counts

npm: mdd-tui  —  GitHub: mdd-tui

mdd-dashboard — Browser Dashboard (in active development)

A visual, browser-based dashboard for MDD projects. Renders your feature dependency graph as an interactive D3 diagram with live reload on file changes.

npm install -g mdd-dashboard
mdd-dashboard
# MDD Dashboard running at http://localhost:7321

Or without installing:

npx mdd-dashboard --path ~/projects/my-mdd-project

Dashboard features

• Force / Tree layout toggle — switch between D3 force simulation (organic clustering) and strict hierarchy (initiative → wave → feature)
• Three-tier filter system — live search, type chips, status dropdown, 11 advanced field filters, and git-aware filters (author, modified-since, changed in last N commits)
• Live reload — SSE pushes graph updates the moment you save a .mdd/ file, no page refresh needed
• Detail panel — click any node to see the full doc body, git history, source files, and depends-on chips that navigate the graph
• Mini-map — 160×120px overlay for large graphs (100+ docs)
• Three-tier loading — frontmatter parsed at startup (<200ms), body fetched on demand, git history loaded async in background

CLI flags

npm: mdd-dashboard  —  GitHub: mdd-dashboard