@thedecipherist/mdd 1.0.0

package/README.md

@@ -0,0 +1,227 @@
+<p align="center">
+  <img src="docs/mdd_hero.webp" alt="MDD — Manual-Driven Development for Claude Code" width="100%" />
+</p>
+
+# MDD — Manual-Driven Development for Claude Code
+
+> **One command. Twenty-one modes. Complete feature lifecycle from documentation to verified deployment.**
+
+MDD turns Claude Code from a code generator into a structured development partner. Every feature starts with documentation. Every fix starts with an audit. No exceptions.
+
+```bash
+npm install -g @thedecipherist/mdd
+mdd install
+```
+
+Then in Claude Code:
+```
+/mdd add user authentication with JWT tokens
+```
+
+---
+
+## Why MDD?
+
+Most people prompt Claude Code like this: *"fix the bug in my auth system."* Claude reads 40 files, burns through context trying to understand your architecture, and produces something that technically compiles but misses the bigger picture.
+
+MDD flips this. You write structured documentation first, then Claude reads **one doc** instead of 40 files. It gets the full picture in 200 tokens instead of 20,000.
+
+**The workflow: Document → Audit → Fix → Verify**
+
+| Phase | What happens |
+|-------|-------------|
+| 📋 Document | Write feature docs with YAML frontmatter in `.mdd/docs/` |
+| 🔍 Audit | Read source code, write incremental notes to disk (survives compaction) |
+| 📊 Analyze | Read notes only → produce severity-rated findings report |
+| 🔧 Fix | Execute pre-planned fixes with tests |
+| ✅ Verify | Tests pass, types check, documentation updated |
+
+---
+
+## Installation
+
+```bash
+npm install -g @thedecipherist/mdd
+mdd install          # copies Claude commands to ~/.claude/commands/
+```
+
+```bash
+mdd update           # update to latest version
+mdd install --dir /custom/path   # install to a custom directory
+```
+
+After running `mdd install`, the `/mdd` command is available in every Claude Code session globally — no per-project setup needed.
+
+---
+
+## Usage
+
+### Build a new feature
+
+```bash
+/mdd add user authentication with JWT tokens
+/mdd build payment integration with Stripe
+/mdd create admin dashboard for user management
+```
+
+Claude interviews you about requirements, writes structured documentation, generates test skeletons (red gate), presents a block-by-block build plan, implements with a 5-iteration green gate loop, then verifies against the real runtime environment.
+
+### Audit existing code
+
+```bash
+/mdd audit                    # full codebase audit
+/mdd audit database           # audit a specific section
+/mdd audit authentication     # audit just auth-related code
+```
+
+Scales across parallel agents (1–8 depending on file count). Notes written to disk every file so findings survive context compaction. Produces a severity-rated report (P1 Critical → P4 Low) with effort estimates.
+
+### Day-to-day operations
+
+```bash
+/mdd status                   # overview: docs, tests, audit state, drift
+/mdd scan                     # detect features whose source files changed since last session
+/mdd update 04                # re-sync a feature doc after code changes
+/mdd note "switched to PostgreSQL"   # append a timestamped note to session context
+/mdd commands                 # show this reference table in Claude
+```
+
+### Feature lifecycle
+
+```bash
+/mdd reverse-engineer src/handlers/payments.ts   # generate docs from undocumented code
+/mdd graph                    # dependency map with broken/risky dep warnings
+/mdd deprecate 03             # retire a feature cleanly, flag dependents
+/mdd upgrade                  # batch-patch missing frontmatter across all docs
+```
+
+### Initiative & wave planning
+
+```bash
+/mdd plan-initiative "auth system"           # create a multi-wave initiative
+/mdd plan-wave auth-system "Auth Foundation" # plan a wave with a demo state
+/mdd plan-execute auth-system-wave-1         # implement all features in a wave
+/mdd plan-sync auth-system                   # re-stamp waves after initiative changes
+/mdd plan-remove-feature auth-system-wave-1 auth-signup
+/mdd plan-cancel-initiative auth-system
+```
+
+### Ops runbooks
+
+```bash
+/mdd ops deploy swarmk to dokploy     # create a deployment runbook
+/mdd ops list                         # list all runbooks (global + project)
+/mdd runop swarmk-dokploy             # execute: pre-flight → canary → primary → post-flight
+/mdd update-op swarmk-dokploy         # edit an existing runbook
+```
+
+---
+
+## What Gets Installed
+
+`mdd install` copies 7 files to `~/.claude/commands/`:
+
+| File | Contents | Lines |
+|------|----------|-------|
+| `mdd.md` | Router — Steps 0/0a/0b, mode dispatch, auto-branch | ~120 |
+| `mdd-build.md` | BUILD MODE — Phases 0–7d (branch check, understand, data flow, docs, test skeletons, red gate, plan, implement, verify, commit) | ~680 |
+| `mdd-audit.md` | AUDIT MODE — Phases A1–A7 (scope, agent config, parallel execution, convergence, merge, analyze, fix) | ~240 |
+| `mdd-manage.md` | STATUS + NOTE + SCAN + UPDATE + DEPRECATE modes | ~340 |
+| `mdd-lifecycle.md` | REVERSE-ENGINEER + GRAPH + UPGRADE modes | ~350 |
+| `mdd-plan.md` | PLAN-INITIATIVE + PLAN-WAVE + PLAN-EXECUTE + PLAN-SYNC + PLAN-REMOVE-FEATURE + PLAN-CANCEL-INITIATIVE modes | ~350 |
+| `mdd-ops.md` | OPS DOCUMENT + OPS EXECUTE + OPS UPDATE + OPS LIST + COMMANDS modes | ~380 |
+
+The router loads only the mode file needed for each invocation — a `/mdd status` loads ~460 tokens instead of the full ~28,000. The full set is available but never loaded unnecessarily.
+
+---
+
+## The `.mdd/` Directory
+
+All MDD artifacts live in a single dotfile directory:
+
+```
+.mdd/
+├── docs/                         # Feature documentation (one .md per feature)
+│   ├── 01-<feature-name>.md      # auto-numbered, YAML frontmatter
+│   └── archive/                  # Deprecated feature docs
+├── initiatives/                  # Initiative files (/mdd plan-initiative)
+├── waves/                        # Wave files (/mdd plan-wave)
+├── ops/                          # Ops runbooks (/mdd ops)
+├── audits/                       # Audit artifacts (gitignored)
+│   ├── flow-<feature>-<date>.md  # Data flow analysis (Phase 2)
+│   ├── notes-<date>.md           # Raw reading notes (Audit Phase A2)
+│   ├── report-<date>.md          # Severity-rated findings (Audit Phase A3)
+│   ├── scan-<date>.md            # Drift report (/mdd scan)
+│   └── graph-<date>.md           # Dependency graph (/mdd graph)
+├── jobs/                         # Active audit jobs (gitignored, auto-deleted)
+└── .startup.md                   # Auto-generated session context
+```
+
+`.mdd/audits/` and `.mdd/jobs/` are automatically added to `.gitignore` on first run.
+
+---
+
+## Build Mode in Detail
+
+Build mode runs 7 phases with 3 mandatory gates:
+
+**Pipeline:** Understand → Analyze → Document → Test Skeletons → **Red Gate** → Plan → Implement → **Green Gate** → Verify → **Integration Gate**
+
+- **Phase 1** gathers context using 3 parallel Explore agents (rules, existing features, codebase structure)
+- **Phase 2** is a mandatory Data Flow & Impact Analysis gate — traces every data value end-to-end before writing a line of docs; automatically skipped on greenfield projects
+- **Red Gate** runs every test skeleton to confirm it actually fails before implementation begins
+- Build plan uses commit-worthy blocks with runnable end-states, verification commands, and handoff contracts; independent blocks annotated for parallel execution
+- **Green Gate** implements each block with a 5-iteration diagnosis-first loop — states root cause before each fix; stops at 5 and escalates rather than continuing blindly
+- **Integration Gate** verifies real behavior (real HTTP calls, real DB, real browser) before marking complete
+
+---
+
+## Audit Mode in Detail
+
+Audit mode scales with file count (1–8 parallel agents):
+
+| Files in scope | Agents |
+|---|---|
+| < 10 | 1 (single-agent mode) |
+| 10–25 | 2 |
+| 26–50 | 3 |
+| 51–100 | 5 |
+| 100+ | 8 |
+
+Each agent gets a shard of files and a config file. Agents clear context between every file — every file gets a full context window with maximum analysis budget. Notes are written to disk so findings survive compaction. The manifest tracks `[ ] pending → [~] in progress → [x] complete → [!] findings → [e] error` for every file.
+
+---
+
+## MDD Versioning
+
+Every feature doc, wave, and initiative created by MDD is stamped with `mdd_version: N` in its frontmatter. `/mdd status` shows a breakdown of which docs are on which version. `mdd install` compares `mdd_version` between the installed and available versions before overwriting — no silent overwrites.
+
+The current MDD version is `8` (bumped with each release to this package).
+
+---
+
+## Real Results: Self-Audit
+
+The [Claude Code Mastery Starter Kit](https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit) used MDD to audit itself:
+
+| Audit Step | Time | Output |
+|------------|------|--------|
+| Create Docs (pre-audit) | ~25 min | 9 feature docs in `.mdd/docs/` |
+| A2: Read + Notes | 9 min 51s | 57+ files read, 837 lines of notes |
+| A3: Analyze | 2 min 39s | 298-line report, 20 findings |
+| A5: Fix All | 10 min 53s | 17/20 fixed, 125 tests written |
+| **Total** | **~48 min** | **20 findings, 125 tests from zero** |
+
+---
+
+## Companion Tools
+
+- **[mdd-tui](https://github.com/TheDecipherist/mdd-tui)** — Terminal dashboard for browsing your `.mdd/` workspace (docs, audits, graph, ops runbooks) in a live TUI. Install: `npm install -g @thedecipherist/mdd-tui`
+- **[Claude Code Mastery Starter Kit](https://github.com/TheDecipherist/claude-code-mastery-project-starter-kit)** — Full project scaffolding with hooks, rules, skills, and agents. MDD is one component of the kit.
+- **[strictdb](https://www.npmjs.com/package/strictdb)** — Database wrapper with guardrails used across starter kit projects
+
+---
+
+## License
+
+MIT — [TheDecipherist](https://github.com/TheDecipherist)

package/commands/mdd-audit.md

@@ -0,0 +1,237 @@
+## AUDIT MODE — `/mdd audit [section]`
+
+Triggered when arguments start with `audit`.
+
+### Phase A1 — Scope
+
+**Stale job detection (runs first):** Check `.mdd/jobs/` for any existing `audit-*/` folder.
+- If found: check whether a corresponding `audits/report-<date>.md` exists.
+  - If yes: job completed but cleanup failed — delete the stale jobs folder and proceed normally.
+  - If no: job was interrupted — read `MANIFEST.md` from the jobs folder and count complete vs total entries. Present to user:
+    ```
+    Found interrupted audit from <date>.
+    MANIFEST shows <done>/<total> files complete.
+
+      [R] Resume — continue from where it left off
+      [D] Discard — delete and start fresh
+    ```
+  - Resume: reuse the existing job folder, existing agent notes, pick up from the first `[ ]` in the manifest. Files already marked `[x]`, `[!]`, or `[e]` are never re-processed. Skip to Phase A3.
+  - Discard: delete the jobs folder, proceed normally.
+
+**Scope resolution:**
+1. **Read all `.mdd/docs/*.md` files** — build the feature map. Also read all `.mdd/ops/*.md` files — check for: missing mandatory sections, literal credential values (critical violation), stale `last_synced`, services with no `health_check` defined.
+2. **If no `.mdd/` directory exists:** Create it with `docs/`, `audits/`, `ops/`, and `jobs/` subdirectories. Then tell the user: "No MDD documentation found. Run `/mdd` for each feature to create docs first, or I can scan the codebase and create them now. Which do you prefer?"
+   - If "scan": read all source files and generate documentation files (Phase 0)
+   - If "manual": exit and let the user create docs per feature
+3. Resolve every source file referenced across all feature docs. Deduplicate (same file may appear in multiple feature docs).
+
+**Incremental vs full (only when a previous completed audit exists):**
+```
+A completed audit exists from <date>.
+
+  [F] Full audit — regenerate manifest from all source files
+      Use when: significant new code added, want a clean baseline, or last audit was >2 weeks ago
+  [I] Incremental — manifest contains only files modified since <date>
+      Use when: applied fixes and want to verify them, or auditing only a new feature
+```
+
+**Agent scaling:**
+
+| Files in scope | Agents |
+|---|---|
+| < 10 | 1 (Single-Feature Audit Mode — see below) |
+| 10–25 | 2 |
+| 26–50 | 3 |
+| 51–100 | 5 |
+| 100+ | 8 (default ceiling) |
+
+Default ceiling is 8. Overridable via `MDD_MAX_AGENTS` environment variable. Values below 1 fall back to 1. The scale table still determines count within the ceiling — `MDD_MAX_AGENTS` only raises or lowers the cap.
+
+**Shard sizing:** Balanced by estimated token load (file size), not raw file count. Main inspects file sizes before assigning and redistributes to keep shards roughly equal in estimated read cost.
+
+**Create the job folder and write MANIFEST.md (nothing else proceeds until the manifest exists on disk):**
+
+Create `.mdd/jobs/audit-<date>/` and write `MANIFEST.md`:
+
+```markdown
+# Audit Manifest
+# Job: audit-<date>
+# Generated: <ISO timestamp>
+# Total files: <N>
+# Agents: <N>
+# Status: IN PROGRESS
+#
+# States: [ ] pending  [~] in progress  [x] complete  [!] findings  [e] error
+
+## Shard 1 (Agent 1) — files 1-<N>
+[ ] src/handlers/auth.ts
+[ ] src/handlers/users.ts
+...
+
+## Shard 2 (Agent 2) — files <N+1>-<M>
+[ ] src/handlers/billing.ts
+...
+```
+
+---
+
+### Phase A2 — Per-Agent Config Setup
+
+Main writes a shard file and config file for each agent into the job folder **before spawning anything**.
+
+**`shard-N.md`** — flat list of files assigned to this agent, extracted from the manifest. The agent uses this to know its scope without parsing the full manifest.
+
+**`agent-N-config.md`** format:
+
+```markdown
+# Agent <N> Audit Config
+
+## Identity
+You are Audit Agent <N> of <total>.
+Job: audit-<date>
+
+## Paths (relative to project root)
+Shard file:  .mdd/jobs/audit-<date>/shard-<N>.md
+Notes file:  .mdd/jobs/audit-<date>/agent-<N>-notes.md
+Manifest:    .mdd/jobs/audit-<date>/MANIFEST.md
+
+## Rules
+- Write findings to your notes file ONLY. Never touch another agent's file.
+- Mark each file in MANIFEST before clearing context.
+- Clear context after every single file — no exceptions.
+- On every startup (including post-clear): follow STARTUP SEQUENCE below.
+
+## Startup Sequence
+1. Read this config file
+2. Read shard-<N>.md to know your file list
+3. Read MANIFEST.md — find the first [ ] entry in Shard <N>
+4. Read the last 20 lines of agent-<N>-notes.md for continuity
+5. Begin the per-file loop at that first [ ] entry
+```
+
+This config file contains no source code or findings — only paths and instructions. It is the only thing an agent needs to resume correctly after a context clear.
+
+---
+
+### Phase A3 — Parallel Agent Execution
+
+Main spawns all agents simultaneously. Each agent receives only the path to its config file.
+
+**Per-file loop (each agent follows exactly):**
+
+```
+STARTUP (run on every fresh start and after every context clear):
+  1. Read agent-N-config.md
+  2. Read shard-N.md
+  3. Read MANIFEST.md — find first [ ] in own shard
+  4. Read last 20 lines of agent-N-notes.md for continuity
+  5. Begin per-file loop
+
+PER-FILE LOOP:
+  1. Mark file as [~] in MANIFEST.md        ← write to disk first
+  2. Read the source file fully
+  3. Analyze against audit criteria
+  4. Append to agent-N-notes.md:
+       ## src/handlers/auth.ts
+       <findings, or "No issues found">
+  5. Mark file as [x] or [!] in MANIFEST.md ← [!] = has findings
+  6. Clear context                           ← every file, no exceptions
+  7. On restart: run STARTUP above
+```
+
+**Hard rules:**
+- Write to own notes file ONLY — never another agent's file
+- Checkpoint order: mark `[~]` → read → analyze → write notes → mark `[x]`/`[!]` → clear. Never clear before the final mark.
+- If a file cannot be read (missing, binary, too large): mark `[e]` in manifest, append one-line error to notes, proceed to next file
+- Skip any file already marked `[x]`, `[!]`, or `[e]` — never re-process
+
+**Why clear after every file:** Every file gets a full, fresh context window with maximum analysis budget. The notes file and manifest are the memory — the analysis does not need to survive the clear.
+
+**Why mark `[~]` before reading:** A stuck `[~]` is re-processed at convergence. Duplicate analysis is better than missing analysis.
+
+---
+
+### Phase A4 — Convergence Check
+
+After all agents signal completion, main reads `MANIFEST.md` and checks for any `[ ]` or `[~]` entries.
+
+- **`[ ]` entries:** agent never reached this file — re-run that agent's shard for remaining files
+- **`[~]` entries:** agent cleared between `[~]` mark and final mark — re-process that file
+- **`[e]` entries:** main attempts to read the file itself; if still unreadable, it remains `[e]` and is flagged in the final report as unaudited with the reason
+
+Audit does not advance to Phase A5 until every file is `[x]`, `[!]`, or `[e]`.
+
+---
+
+### Phase A5 — Merge
+
+Main merges all agent notes into the canonical output file:
+
+1. Read `MANIFEST.md` to get canonical file order
+2. For each file in manifest order, locate its `## <filepath>` section in the correct agent notes file
+3. Append to `audits/notes-<date>.md` in that order
+4. Verify entry count in `audits/notes-<date>.md` matches manifest file count
+
+Merge is in manifest order, not agent completion order. The job folder is not touched during or after merge — all temp files remain until the report is confirmed in Phase A6.
+
+---
+
+### Phase A6 — Analyze
+
+Read ONLY `audits/notes-<date>.md` (NOT source code again). Produce `audits/report-<date>.md` — include `mdd_version: <current from mdd.md frontmatter>` as the first line of frontmatter:
+
+1. Executive summary
+2. Feature completeness matrix
+3. Findings by severity (P1 Critical / P2 High / P3 Medium / P4 Low)
+4. Test coverage summary
+5. Fix plan with effort estimates and affected files per finding
+
+**Once `audits/report-<date>.md` is confirmed written and non-empty:**
+1. Copy `jobs/audit-<date>/MANIFEST.md` → `audits/MANIFEST-<date>.md`
+2. Delete entire `jobs/audit-<date>/` folder
+
+The manifest is kept permanently in `audits/` — `[x]` vs `[!]` per file shows what had findings without parsing the full notes file.
+
+---
+
+### Phase A7 — Present Findings + Fix
+
+Show the user:
+```
+🔍 MDD Audit Complete
+
+Findings: <N> total (<N> P1 Critical, <N> P2 High, <N> P3 Medium, <N> P4 Low)
+Report: .mdd/audits/report-<date>.md
+MANIFEST: .mdd/audits/MANIFEST-<date>.md (<N> files with findings / <total> audited)
+
+Top issues:
+  1. <most critical finding>
+  2. <second most critical>
+  3. <third most critical>
+
+Estimated fix time: <N> hours (traditional) → <N> minutes (MDD)
+
+Fix all now? (yes / review report first / fix only P1+P2)
+```
+
+**After the report is written**, trigger the `.mdd/.startup.md` rebuild (same logic as in Status Mode — rebuild auto-generated zone, preserve Notes zone) so the Last Audit block reflects the new findings regardless of whether the user proceeds with fixes.
+
+If user says yes (or selects a subset):
+
+**Fix loop:** Read the findings report. For each finding to fix:
+1. Read the specific source files
+2. Apply the fix
+3. Write or update tests
+4. Run tests after each fix group
+
+Report progress per finding. Update documentation `known_issues` to remove fixed items. Update `mdd_version` to current on every `.mdd/docs/*.md` file that is edited during fixes.
+
+**After fixes are complete and results are written to `.mdd/audits/results-<date>.md`**, trigger the `.mdd/.startup.md` rebuild so the Last Audit block reflects the new numbers.
+
+---
+
+### Single-Feature Audit Mode
+
+When running `/mdd audit <section>` with fewer than 10 resolved files, skip the shard/config/agent system. Main conversation runs the per-file loop directly — context clear between each file, writing to a single `agent-1-notes.md` in the job folder. The job folder structure and completion sequence are otherwise identical.
+
+---