mdd-tui

A terminal dashboard for MDD (Manual-First Development) projects created by the starter kit.

Reads your .mdd/ directory and renders a live, navigable TUI showing doc health, drift status, audit reports, and full markdown content — without leaving the terminal.

Install

npm install -g mdd-tui

Usage

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

mdd dashboard

Navigation

| Key | Action | |-----|--------| | ↑ / k | Move up in left panel / scroll up in right panel | | ↓ / j | Move down in left panel / scroll down in right panel | | → / l / Enter | Focus right panel (or expand initiative) | | ← / h / Esc | Focus left panel | | i | Jump to first initiative in the list | | Page Up | Scroll right panel up one page | | Page Down | Scroll right panel down one page | | Home | Jump to top of right panel | | End | Jump to bottom of right panel | | r | Refresh workspace | | q / Ctrl+C | Quit |

Initiative expand/collapse — pressing Enter or → on an initiative row toggles its waves open or closed. When expanded, each wave appears as an indented sub-row showing status icon and feature progress (e.g. 2/3).

What it shows

Left panel — scrollable list with three sections (shown in order):

1. INITIATIVES (shown only if .mdd/initiatives/ exists) — collapsible tree of initiatives and their waves:

   • ▸ Initiative Title active — collapsed; press Enter to expand
   • ▾ Initiative Title active — expanded; child waves shown below with progress
   • Wave rows: ● Wave Title 1/3 (active), ✓ Wave Title 3/3 (complete), ○ Wave Title 0/2 (planned)

2. FEATURE DOCS — all feature docs with drift status icons:

   | Icon | Meaning | |------|---------| | ✓ | In sync with source files | | ! | Drifted — commits since last sync | | ✗ | Broken — source files missing | | ? | Untracked — no source files defined |

3. AUDIT REPORTS (shown only if audits exist)

4. DEP GRAPH — click to view the dependency graph

Right panel — full detail view for the selected item:

• Initiative: status, overview, open product questions (unchecked ones highlighted), wave list with progress
• Wave: demo state, feature table with status and dependencies, open research items, next-action hint
• Feature doc: status chips, source files, dependencies, known issues, drift commits, full markdown body
• Audit report: full markdown content

Status bar — live counts: DOCS · IN SYNC · DRIFTED · BROKEN · UNTRACKED · ISSUES · AUDITS · INITIATIVES · WAVES (active)

What is MDD?

MDD (Manual-First Development) is a documentation-first workflow for building features with AI coding assistants. Every feature starts with a .mdd/docs/*.md file that defines architecture, API, data model, and business rules before any code is written.

mdd-tui is the companion dashboard — run it alongside your editor to track doc health across the project.

Requirements

• Node.js 18+
• A project with a .mdd/ directory

License

MIT