@thedecipherist/mdd 1.3.9 → 1.4.0

package/README.md

@@ -4,7 +4,7 @@
 
 # MDD - Manual-Driven Development for Claude Code
 
-> **One command. Twenty-one modes. Complete feature lifecycle from documentation to verified deployment.**
+> **One command. Twenty-three modes. Complete feature lifecycle from documentation to verified deployment.**
 
 <p align="center">
   <a href="https://thedecipherist.github.io/mdd">
@@ -249,6 +249,7 @@ Every feature doc and ops runbook has a `tags:` field (4–8 domain-concept keyw
 /mdd note list                             Print the Notes section
 /mdd note clear                            Wipe all notes (asks for confirmation)
 /mdd deprecate <feature-id>                Archive a feature and flag all dependents
+/mdd import-spec <file> [file...]           Convert a spec doc into MDD feature docs
 /mdd reverse-engineer [path|feature-id]   Generate MDD docs from existing source code
 /mdd graph                                 Render the full cross-feature dependency map
 /mdd upgrade                               Batch-patch missing frontmatter across all docs
@@ -624,6 +625,39 @@ Re-syncs a feature doc after its code has changed:
 
 ---
 
+## Import Spec Mode
+
+### `/mdd import-spec <file> [file...]`
+
+Converts one or more large spec or prompt documents — the kind produced by extended brainstorming sessions — into properly structured MDD feature docs. Nothing from the original spec is lost.
+
+```bash
+/mdd import-spec ~/specs/my-app-prompt.md
+/mdd import-spec spec-v1.md spec-v2.md spec-notes.md
+```
+
+**How it works:**
+
+1. **Read** — loads all spec files, merges content if multiple are provided
+2. **Extract + Group** — identifies distinct features and assigns each a `path` value (e.g. `Auth/Login`, `E-commerce/Cart`) before anything else
+3. **Auto-detect structure** — decides whether to create initiatives + waves + docs, waves + docs, or flat feature docs, based on path diversity and feature count:
+
+| Signal | Output |
+|--------|--------|
+| 3+ distinct root path areas AND 8+ features | Initiative → Waves → Feature docs |
+| 4–7 features in a coherent domain | Waves → Feature docs |
+| 1–3 focused features | Flat feature docs only |
+
+4. **Dry-run preview** — shows the complete proposed tree (paths, slugs, titles, content mapping, merge summary) before writing a single file. You can adjust or abort.
+5. **Write docs** — creates all feature docs with full frontmatter, populated sections, tags, and `path` fields
+6. **Rebuild** — updates `.mdd/.startup.md` to reflect the new docs
+
+**Content preservation:** Every decision, constraint, and edge case in the spec maps somewhere in the output. If something doesn't fit cleanly into a standard section, it goes into Business Rules or a Known Constraints note.
+
+**Duplicate handling:** Specs often revisit the same topic multiple times. Import-spec detects overlapping sections semantically, merges them into the best doc, and shows you exactly what was merged and why in the dry-run summary.
+
+---
+
 ## Feature Lifecycle
 
 ### `/mdd deprecate <feature-id>`
@@ -677,9 +711,9 @@ Saved to `.mdd/audits/graph-<date>.md`.
 
 ### `/mdd upgrade`
 
-Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`) across all `.mdd/docs/*.md` files. Safe to run multiple times - already-present fields are never overwritten.
+Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`, `tags`, `path`) across all `.mdd/docs/*.md` files. Safe to run multiple times — already-present fields are never overwritten.
 
-Infers sensible defaults from git history, existing field values, and archive status. Shows a plan before writing anything.
+Infers sensible defaults from git history, existing field values, and archive status. For the `path` field, Claude reads each doc's title and purpose to propose a value — always shows a plan for confirmation before writing. After upgrade, run `/mdd rebuild-tags` to populate any empty `tags` fields.
 
 ---
 
@@ -793,6 +827,7 @@ Every `.mdd/docs/<NN>-<feature-name>.md` file uses this YAML frontmatter:
 | `phase` | Last completed phase name |
 | `mdd_version` | Version of MDD that created/last updated this doc |
 | `tags` | 4–8 domain-concept keywords surfaced in `.startup.md` so Claude can detect when a prompt relates to this feature (e.g. `[auth, jwt, login, sessions]`) |
+| `path` | Slash-delimited breadcrumb showing where this feature lives in the product (e.g. `Auth/Login`, `E-commerce/Cart/Checkout`). Used by dashboards and listing tools to group docs into a human-readable tree. Distinct from `depends_on` — this is for navigation, not build order. |
 | `known_issues` | Issues discovered during audits or implementation |
 
 **`depends_on` rules:**
@@ -800,6 +835,14 @@ Every `.mdd/docs/<NN>-<feature-name>.md` file uses this YAML frontmatter:
 - IDs must reference existing docs - `/mdd graph` detects broken references
 - Only add, never remove without discussion - removing breaks the dependency chain
 
+**`path` rules:**
+- Format: `Area/Section` or `Area/Section/Detail` — Title Case, slash-separated, 1–3 levels
+- Use product vocabulary, not code paths: `Auth/Login` not `src/handlers/auth`
+- Siblings must use identical parent spelling: if `Auth/Login` exists, new auth docs use `Auth` not `Authentication`
+- Set automatically by Claude in Build Mode Phase 3 (inferred from context, confirmed by user if ambiguous)
+- Missing `path` fields are detected by `/mdd scan` and batch-fixed by `/mdd upgrade`
+- Dashboards and listing tools use `path` to group docs into a human-readable tree view
+
 ---
 
 ## The `.mdd/` Directory

package/commands/mdd-build.md

@@ -192,6 +192,7 @@ status: draft
 phase: <last completed phase name, or "all" when fully built>
 mdd_version: <read from mdd.md frontmatter mdd_version field>
 tags: [<4-8 domain-concept keywords — systems touched, technology, feature names. NOT file paths>]
+path: <Area/Section>
 known_issues: []
 ---
 
@@ -234,6 +235,8 @@ known_issues: []
 
 **Always set `last_synced` to today's date** when writing or updating a feature doc. This is what SCAN MODE uses to detect drift. Set `status: draft` for new docs; update to `in_progress` when implementation begins, `complete` when Phase 7 is done.
 
+**Determine the `path` field** before writing the doc. Read the `path` values of all existing docs in `.mdd/docs/` to understand established product vocabulary and category names. Then ask: "What would a user navigate to in order to reach this feature?" — answer in their mental model of the product, not the code structure. Use 1–3 segments, Title Case, product vocabulary (e.g. `Auth/Login`, `E-commerce/Cart`, `Dashboard/Analytics`). Siblings must use identical parent spelling — if `Auth/Login` exists, use `Auth` not `Authentication`. If you can infer the path from context with confidence, set it and show the user. If genuinely ambiguous (feature could belong in 2+ places), ask: "Where does this feature live in the product? (e.g. `Auth/Login` or `Dashboard/Reports`)"
+
 **After writing the feature doc**, trigger the `.mdd/.startup.md` rebuild (same logic as in Status Mode — rebuild auto-generated zone, preserve Notes zone) so the Features list stays current.
 
 Show the completed doc to the user and ask: **"Does this accurately describe what you want to build? Anything to add or change?"**

package/commands/mdd-import-spec.md

@@ -0,0 +1,205 @@
+## IMPORT SPEC MODE — `/mdd import-spec`
+
+Triggered when arguments start with `import-spec`.
+
+Reads one or more large spec or prompt documents — the kind produced by extended brainstorming sessions with Claude — and converts them into properly structured MDD feature docs. Every decision in the spec is preserved. Duplicate or overlapping topics are merged intelligently. Path grouping determines whether to create initiative/waves or flat docs.
+
+---
+
+### Phase IS1 — Read Spec Files
+
+Parse file path(s) from the arguments following `import-spec`. Multiple files may be space-separated or specified as a glob.
+
+For each file path:
+1. Verify the file exists. If a path does not exist, stop and report clearly: "File not found: `<path>`"
+2. Read the full content.
+
+If multiple files are provided, merge all content into a single working document. Tag each section internally with its source filename (e.g. `<!-- source: rawpg-prompt-driver.md -->`) for traceability — these tags are used in the merge summary and content mapping display but are never written to output docs.
+
+---
+
+### Phase IS2 — Feature Extraction + Path Grouping
+
+This phase runs in two steps. Path grouping always runs before complexity determination because the number of distinct top-level path areas is the primary signal for initiative-scale scope.
+
+#### Step IS2a — Extract features
+
+Read the entire merged spec. Identify every distinct feature, system, subsystem, or bounded capability described. A "feature" is any topic that could become a standalone MDD doc — something with a purpose, decisions, constraints, and a clear scope.
+
+For each identified feature:
+- Name / title
+- Core purpose (1–2 sentences distilled from the spec)
+- All key decisions, constraints, business rules, and edge cases mentioned in the spec
+- Dependencies on other features identified in the same spec
+
+Track which spec sections contribute to each feature. When multiple spec sections cover the same concept (same feature re-discussed with refinements), **merge them** — do not create duplicate docs. When versions of the same decision conflict, keep the most specific or most recent version and note the discarded variant.
+
+#### Step IS2b — Assign paths
+
+Read all existing `.mdd/docs/*.md` `path` fields (if any exist) to learn the project's established vocabulary and casing conventions.
+
+For each identified feature, determine its `path` value:
+- Use the user's product vocabulary, not code module names
+- Title Case, 1–3 levels, `/`-separated
+- Siblings must use identical parent spelling (if `Auth/Login` exists, new auth docs use `Auth`, not `Authentication`)
+
+#### Step IS2c — Determine output structure
+
+Count distinct root-level path segments (top-level areas):
+
+| Signal | Structure |
+|--------|-----------|
+| 3+ distinct root areas AND 8+ features | Initiative + Waves + Feature docs |
+| 1–2 root areas AND 4–7 features | Waves + Feature docs (no initiative wrapper) |
+| Any root area count AND 1–3 features | Flat feature docs only |
+
+These thresholds are guidelines — apply judgment. A 3-feature spec spanning radically different domains can still warrant waves.
+
+---
+
+### Phase IS3 — Dry-Run Preview (mandatory gate)
+
+Before writing any files, display the complete proposed structure and wait for explicit user approval.
+
+```
+📋 Import Spec — Dry Run
+
+Source: <filename(s)>
+Features identified: <N>   Merged: <N> duplicate/overlapping topics
+
+Proposed structure: <Flat docs | Waves | Initiative: "<name>" → Waves>
+
+Path Tree:
+  <Root Area 1>
+    ├── <Section>              → <NN>-<slug>    (draft)
+    └── <Section>
+         └── <Sub-section>    → <NN>-<slug>    (draft)
+  <Root Area 2>
+    └── <Section>              → <NN>-<slug>    (draft)
+
+IDs assigned: <NN>–<NN> (continuing from existing <prev>)
+
+Merge summary:
+  "<path>" ← merged from: §<Spec Section A>, §<Spec Section B>
+  (one line per merged feature — omit if no merges)
+
+Content mapping:
+  <NN>-<slug>:   §<Spec Section> + §<Spec Section>
+  <NN>-<slug>:   §<Spec Section>
+
+Adjust paths, titles, or grouping? (approve / adjust / abort)
+```
+
+**If the user says "adjust":** accept their description of changes, re-run IS2 with that feedback applied, then show the preview again. Repeat until the user approves.
+
+**If the user says "abort":** stop. Write nothing.
+
+**Do not proceed to IS4 until the user explicitly approves.**
+
+---
+
+### Phase IS4 — Write Files
+
+**If initiative-scale was detected:** Create `.mdd/initiative.md` with:
+- `id`, `title`, `status: planning`, `created: <today>`
+- A brief initiative description derived from the spec's overall theme
+- Wave breakdown: one wave per major root path area or logical phase, each listing its feature doc slugs
+
+**For each feature doc in the approved plan:**
+
+1. Auto-number continuing from the highest existing doc number in `.mdd/docs/`
+2. Write a complete MDD feature doc at `.mdd/docs/<NN>-<slug>.md` using the canonical frontmatter structure:
+
+```markdown
+---
+id: <NN>-<slug>
+title: <Feature Title>
+edition: <project name or "Both">
+depends_on: [<IDs of other imported features this one depends on>]
+source_files: []
+routes: []
+models: []
+test_files: []
+data_flow: greenfield
+last_synced: <today YYYY-MM-DD>
+status: draft
+phase: documentation
+mdd_version: <read from mdd.md frontmatter>
+tags: [<4–8 domain-concept keywords>]
+path: <Area/Section>
+known_issues: []
+---
+
+# <NN> — <Feature Title>
+
+## Purpose
+
+<2–3 sentences from the merged spec content>
+
+## Architecture
+
+<How this feature fits into the system, derived from spec decisions>
+
+## Data Model
+
+<If the spec describes data structures — omit section if truly not applicable>
+
+## API Endpoints
+
+<If the spec describes endpoints — omit section if truly not applicable>
+
+## Business Rules
+
+<All decisions, constraints, validation rules, edge cases from the spec>
+
+## Dependencies
+
+<Other features this one requires, by doc ID>
+
+## Known Issues
+
+(none — imported from spec)
+```
+
+3. Tags: 4–8 domain-concept keywords. NOT file paths or spec section names.
+4. `depends_on`: if feature A was described in the spec as depending on feature B (also imported), use the IDs assigned in this run.
+
+**Progress report as you write:**
+```
+Writing docs...
+  ✅ <NN>-<slug>.md   (<path>)
+  ✅ <NN>-<slug>.md   (<path>)
+  ...
+```
+
+---
+
+### Phase IS5 — Rebuild .startup.md
+
+Trigger the `.mdd/.startup.md` rebuild:
+- Rebuild the auto-generated zone (Project Snapshot, Features Documented list with IDs, status, and tags)
+- Preserve the Notes zone exactly as-is
+- Update the generated date and current branch
+
+Then report:
+
+```
+✅ Import Spec Complete
+
+Source:    <filename(s)>
+Created:   <N> feature docs
+Structure: <Flat | Waves | Initiative + Waves>
+
+Docs created:
+  <NN>-<slug>   <path>   draft
+  <NN>-<slug>   <path>   draft
+  ...
+
+Startup:   .mdd/.startup.md rebuilt
+
+Next steps:
+  /mdd <NN>         — start building any imported feature
+  /mdd audit        — run a full audit across all imported docs
+  /mdd upgrade      — add path fields to any pre-existing docs that are missing them
+  /mdd rebuild-tags — regenerate tags if any look thin
+```

package/commands/mdd-lifecycle.md

@@ -181,7 +181,7 @@ Save the graph to `.mdd/audits/graph-<date>.md`.
 
 Triggered when arguments start with `upgrade`.
 
-Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`) across ALL `.mdd/docs/*.md` files without touching doc content. Safe to run multiple times — already-present fields are never overwritten.
+Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`, `tags`, `path`) across ALL `.mdd/docs/*.md` files without touching doc content. Safe to run multiple times — already-present fields are never overwritten.
 
 **Use case:** projects that used MDD before these fields were introduced, or after importing docs from another project. Running `/mdd upgrade` converts all UNTRACKED docs to IN SYNC in one pass.
 
@@ -196,11 +196,11 @@ Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`) acro
 ```
 📋 Upgrade Inventory
 
-Doc                              | last_synced | status | phase | tags
-─────────────────────────────────|─────────────|────────|───────|──────
-01-project-scaffolding           | ❌ missing  | ❌     | ❌    | ❌
-02-profile-system                | ❌ missing  | ✅     | ❌    | ✅
-03-database-layer                | ✅ present  | ✅     | ✅    | ❌
+Doc                              | last_synced | status | phase | tags | path
+─────────────────────────────────|─────────────|────────|───────|──────|──────
+01-project-scaffolding           | ❌ missing  | ❌     | ❌    | ❌   | ❌
+02-profile-system                | ❌ missing  | ✅     | ❌    | ✅   | ❌
+03-database-layer                | ✅ present  | ✅     | ✅    | ❌   | ✅
 ...
 
 Docs needing upgrade: <N> of <total>
@@ -209,6 +209,7 @@ Fields to add:
   status      — <N> docs
   phase       — <N> docs
   tags        — <N> docs (run /mdd rebuild-tags after upgrade to populate)
+  path        — <N> docs (Claude reads each doc's title + purpose to infer the value)
 ```
 
 4. If 0 docs need upgrade → report "All docs are up to date. Nothing to patch." and stop.
@@ -247,6 +248,17 @@ The goal is the date the doc was last meaningfully worked on. Try in order:
 3. If `status` resolved to `draft` → `documentation`
 4. If `status` resolved to `deprecated` → `deprecated`
 
+**`path` inference:**
+
+Unlike other fields, `path` cannot be inferred from git history or status — it requires reading the doc's content.
+
+For each doc missing `path`:
+1. Read its `title` frontmatter field and `## Purpose` section body
+2. Read all other docs' existing `path` fields to understand the project's established vocabulary and casing conventions
+3. Propose a `path` value (`Area/Section`, Title Case, 1–3 levels) that reflects where this feature lives in the product — use product terminology, not code module names
+
+**Do not silently write `path` values** — always include the proposed values in the Phase UP3 plan for user review. The user may adjust any proposed path before writing.
+
 ---
 
 ### Phase UP3 — Show Plan + Confirm
@@ -271,6 +283,7 @@ Present the inferred patches to the user before writing anything:
     + last_synced: 2026-01-17   (from git: last commit on this doc)
     + status: complete
     + phase: all
+    + path: Auth/Login           (inferred from purpose: "handles user login flow")
 
   ... (<N> more)
 
@@ -311,11 +324,12 @@ status: <new>         ← insert here if missing
 phase: <new>          ← insert here if missing
 mdd_version: <new>    ← insert here if missing
 tags: <new>           ← insert here if missing (do not generate tags in upgrade — run /mdd rebuild-tags after)
+path: <new>           ← insert here if missing (value inferred from doc content in UP2, confirmed by user in UP3)
 known_issues: []
 ---
 ```
 
-Insert new fields **before** `known_issues` to keep the canonical order. **Do not attempt to generate tag values during upgrade** — tags require reading doc content to produce meaningful keywords. After running upgrade, run `/mdd rebuild-tags` to populate tags on any docs that need them.
+Insert new fields **before** `known_issues` to keep the canonical order. **Do not attempt to generate tag values during upgrade** — tags require reading doc content to produce meaningful keywords; after running upgrade, run `/mdd rebuild-tags` to populate them. **For `path` values**: these ARE inferred by reading doc content during UP2 and confirmed in UP3 — write the user-confirmed values directly.
 
 Report progress as you go:
 ```
@@ -332,7 +346,7 @@ Patching...
 
 After all patches are applied:
 
-1. Re-scan `.mdd/docs/*.md` — confirm 0 docs have missing `last_synced`
+1. Re-scan `.mdd/docs/*.md` — confirm 0 docs have missing `last_synced` or `path`
 2. Trigger the `.mdd/.startup.md` rebuild (same logic as Status Mode)
 3. Report:
 

package/commands/mdd-manage.md

@@ -153,6 +153,7 @@ A classification table — one row per feature:
 
 **Classifications:**
 - **untracked** — `last_synced` missing from frontmatter
+- **no-path** — `path` field missing from frontmatter (run `/mdd upgrade` to add)
 - **broken** — one or more `source_files` not found on disk
 - **drifted** — `last_synced` exists, files exist, commits found after `last_synced`
 - **in_sync** — `last_synced` exists, all files exist, no commits after `last_synced`
@@ -176,11 +177,13 @@ Generated: <YYYY-MM-DD>
   ❓  09-integrations           — untracked (no last_synced field)
 
 Summary: 1 in sync · 1 drifted · 1 broken · 1 untracked
+Missing path: <N> docs — run /mdd upgrade to populate  ← omit this line when N = 0
 
 Recommended actions:
   /mdd update 04   — re-sync content-builder doc with code
   /mdd update 07   — fix broken file reference
   /mdd update 09   — add last_synced by running update mode
+  /mdd upgrade     — add path field to <N> docs missing it  ← omit this line when there are no docs missing path
 ```
 
 **Initiative/wave drift check** (only shown if `.mdd/initiatives/` exists):
@@ -266,6 +269,7 @@ After rewriting, update frontmatter:
 - `last_synced: <today's date>`
 - `status:` — ask the user if they want to update the status (e.g., draft → complete)
 - `phase:` — update to reflect current state
+- `path:` — if the doc is missing a `path` field, offer to add it: "This doc is missing a `path` field. Where does this feature live in the product? (e.g. `Auth/Login`)" — if the user provides a value, write it between `tags` and `known_issues` in the frontmatter.
 
 ### Phase U6 — Regenerate test skeletons for new behaviors
 

package/commands/mdd.md

@@ -118,6 +118,9 @@ Use whichever path contains `mdd-audit.md`. Store it as `$MDD_DIR` and use it fo
 - If arguments start with `status`, `note`, `scan`, `update`, `deprecate`, or `rebuild-tags` →
   **Read `$MDD_DIR/mdd-manage.md` then follow the relevant mode instructions.**
 
+- If arguments start with `import-spec` →
+  **Read `$MDD_DIR/mdd-import-spec.md` then follow its IMPORT SPEC MODE instructions.**
+
 - If arguments start with `reverse-engineer`, `reverse`, `graph`, or `upgrade` →
   **Read `$MDD_DIR/mdd-lifecycle.md` then follow the relevant mode instructions.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thedecipherist/mdd",
-  "version": "1.3.9",
+  "version": "1.4.0",
   "description": "MDD — Manual-Driven Development workflow for Claude Code",
   "type": "module",
   "bin": {