@thedecipherist/mdd 1.7.1 → 1.8.0

package/commands/mdd-framework.md

@@ -2,24 +2,16 @@
 
 Routes to one of three sub-modes based on the command used.
 
-## Phase Logging
-
-At the **start** of every step (before any action) and the **end** of every step (after all actions), run the command below. Substitute `PHASE` with the step identifier (e.g., `Step 1`, `Step 3`) and `EVENT` with `start` or `end`:
-
-```bash
-bash -c 'D=$(date +%Y-%m-%d); T=$(date +%H:%M:%S); K=$(compressmcp --status 2>/dev/null | grep -oE "[0-9]+K/[0-9]+K" | head -1 || echo "-"); mkdir -p ~/.claude/mdd; printf "| %s | mdd-framework | PHASE | EVENT | %s | %s |\n" "$D" "$T" "$K" >> ~/.claude/mdd/log.md' 2>/dev/null || true
-```
-
-Log file: `~/.claude/mdd/log.md`
-
----
-
 ## `framework <feature>` — Add a Module to mdd-ecommerce
 
 **$ARGUMENTS** is the feature description.
 
 ### Step 1 - Run normal BUILD MODE
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "fw-Step 1" start "$FEATURE_SLUG"
+```
+
 Read `$MDD_DIR/mdd-build.md` and follow every phase (branch check, context gather, questions, doc, implementation, tests). All standard MDD rules apply.
 
 Apply these additional constraints throughout:
@@ -63,14 +55,34 @@ Use `skeleton-ready` when the module compiles but is not yet connected to real d
 
 **$ARGUMENTS** is the path to a completed proposal markdown file.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "fw-Step 1" end "$FEATURE_SLUG"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "-" "complete" "$FEATURE_SLUG"
+```
 ### Step 1 - Read the proposal
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 1" start "$FEATURE_SLUG"
+```
+
 Read the file at `$ARGUMENTS`. If `$ARGUMENTS` is empty, ask: "What is the path to the proposal file?"
 
 Stop if the file does not exist. Report the path and ask the user to check it.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 1" end "$FEATURE_SLUG"
+```
 ### Step 2 - Extract config values
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 2" start "$FEATURE_SLUG"
+```
+
 Parse the proposal for these values:
 
 | Config key | Where to find it |
@@ -87,16 +99,32 @@ Parse the proposal for these values:
 
 If any required value is missing, list the gaps and ask the user to supply them before continuing.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 2" end "$FEATURE_SLUG"
+```
 ### Step 3 - Parse the product catalog
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 3" start "$FEATURE_SLUG"
+```
+
 The proposal contains a markdown table with columns: `sku`, `mfr`, `name`, `description`, `brand`, `price`, `stock`.
 
 Extract every row. Convert `price` to integers (cents/öre - multiply by 100 and round). Build TypeScript seed data from this table.
 
 If the table is missing or empty, ask: "No products found in the catalog table. Add products to the proposal and re-run, or continue with an empty seed?"
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 3" end "$FEATURE_SLUG"
+```
 ### Step 4 - Determine module wiring
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 4" start "$FEATURE_SLUG"
+```
+
 Based on the feature flags extracted in Step 2, decide which `@thedecipherist/mdd-ecommerce-*` packages to import and wire into `site.config.ts`:
 
 - `newsletter: true` → include `@thedecipherist/mdd-ecommerce-newsletter`
@@ -105,8 +133,16 @@ Based on the feature flags extracted in Step 2, decide which `@thedecipherist/md
 
 Always include `@thedecipherist/mdd-ecommerce-core`.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 4" end "$FEATURE_SLUG"
+```
 ### Step 5 - Generate files
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 5" start "$FEATURE_SLUG"
+```
+
 Write all files to the current working directory.
 
 **`site.config.ts`:**
@@ -162,8 +198,16 @@ NEXT_PUBLIC_RYBBIT_URL=https://app.rybbit.io
 # add any other vars from the main mdd-ecommerce .env.example
 ```
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 5" end "$FEATURE_SLUG"
+```
 ### Step 6 - Report
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 6" start "$FEATURE_SLUG"
+```
+
 List every file written with its path. Then output:
 
 ```
@@ -179,24 +223,60 @@ Next steps:
 
 Run this from the root of a client project directory.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "ic-Step 6" end "$FEATURE_SLUG"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "-" "complete" "$FEATURE_SLUG"
+```
 ### Step 1 - Read package.json
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 1" start "$FEATURE_SLUG"
+```
+
 Read `package.json` in the current directory. Find all dependencies and devDependencies whose names start with `@thedecipherist/mdd-ecommerce-`. List each with its pinned version.
 
 If no such dependencies exist, report: "No mdd-ecommerce packages found in package.json. Is this the right directory?"
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 1" end "$FEATURE_SLUG"
+```
 ### Step 2 - Read site.config.ts
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 2" start "$FEATURE_SLUG"
+```
+
 Read `site.config.ts`. Extract:
 - Which slots have modules wired (non-null slot values)
 - Which feature flags are `true`
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 2" end "$FEATURE_SLUG"
+```
 ### Step 3 - Check MDD docs
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 3" start "$FEATURE_SLUG"
+```
+
 Check if `.mdd/docs/` exists. If yes, count the `.md` files inside.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 3" end "$FEATURE_SLUG"
+```
 ### Step 4 - Output status table
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 4" start "$FEATURE_SLUG"
+```
+
 ```
 mdd-ecommerce Client Status
 ============================
@@ -213,3 +293,12 @@ MDD docs:          <N> files in .mdd/docs/  (or "directory not found")
 ```
 
 If `site.config.ts` does not exist, report that and skip slots/features rows.
+
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "cs-Step 4" end "$FEATURE_SLUG"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-framework" "-" "complete" "$FEATURE_SLUG"
+```

package/commands/mdd-import-spec.md

@@ -2,22 +2,12 @@
 
 Triggered when arguments start with `import-spec`.
 
-## Phase Logging
-
-At the **start** of every phase (before any action) and the **end** of every phase (after all actions), run the command below. Substitute `PHASE` with the phase identifier (e.g., `Phase IS1`, `Phase IS3`) and `EVENT` with `start` or `end`:
+### Phase IS1 — Read Spec Files
 
 ```bash
-bash -c 'D=$(date +%Y-%m-%d); T=$(date +%H:%M:%S); K=$(compressmcp --status 2>/dev/null | grep -oE "[0-9]+K/[0-9]+K" | head -1 || echo "-"); mkdir -p ~/.claude/mdd; printf "| %s | mdd-import-spec | PHASE | EVENT | %s | %s |\n" "$D" "$T" "$K" >> ~/.claude/mdd/log.md' 2>/dev/null || true
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS1" start "$ARGUMENTS"
 ```
 
-Log file: `~/.claude/mdd/log.md`
-
-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 initiatives, waves, and feature docs. Every decision in the spec is preserved. Duplicate or overlapping topics are merged intelligently. Features are numbered and waved in **build dependency order**, not spec-reading order.
-
----
-
-### Phase IS1 — Read Spec Files
-
 **Stale job detection (runs first):** Check `.mdd/jobs/` for any existing `import-*/` folder.
 - If found: read its `MANIFEST.md` and count written vs total files. Present to user:
   ```
@@ -68,8 +58,16 @@ If multiple files are provided, merge all content into a single working document
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS1" end "$ARGUMENTS"
+```
 ### Phase IS2 — Feature Extraction, Classification + Path Grouping
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS2" start "$ARGUMENTS"
+```
+
 This phase runs in four steps. Build-order classification (IS2c) always precedes structure determination (IS2d) because the correct numbering depends on understanding what you build vs. what you reference.
 
 #### Step IS2a — Extract features + record source line ranges
@@ -237,8 +235,16 @@ These thresholds are guidelines — apply judgment.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS2" end "$ARGUMENTS"
+```
 ### Phase IS2.5 — CLAUDE.md Check
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS2.5" start "$ARGUMENTS"
+```
+
 Before showing the dry-run preview, check the project's CLAUDE.md.
 
 Run: `[ -f CLAUDE.md ] && wc -l CLAUDE.md || echo "missing"`
@@ -294,8 +300,16 @@ This project uses MDD (Manual-Driven Development). The `.mdd/` directory contain
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS2.5" end "$ARGUMENTS"
+```
 ### Phase IS3 — Dry-Run Preview (mandatory gate)
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS3" start "$ARGUMENTS"
+```
+
 Before writing any files, display the complete proposed structure and wait for explicit user approval.
 
 ```
@@ -368,8 +382,16 @@ List every file that will be written in the order it will be written. Nothing pr
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS3" end "$ARGUMENTS"
+```
 ### Phase IS4 — Write Files
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS4" start "$ARGUMENTS"
+```
+
 **First — ensure the MDD directory structure exists.** Run these before writing any file:
 
 ```bash
@@ -585,8 +607,16 @@ Writing files...
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS4" end "$ARGUMENTS"
+```
 ### Phase IS5 — Rebuild .startup.md + Connections
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS5" start "$ARGUMENTS"
+```
+
 Rebuild `.mdd/.startup.md`:
 - Rebuild the auto-generated zone (Project Snapshot, Features Documented list with IDs, status, and tags; Ops Runbooks)
 - Add initiative and wave summary to the Features section: show initiative title, each wave with status, feature count
@@ -630,3 +660,12 @@ Next steps:
   /mdd audit                        — run a full audit across all imported docs
   /mdd <NN>                         — jump directly to any feature doc
 ```
+
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "Phase IS5" end "$ARGUMENTS"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-import-spec" "-" "complete" "$ARGUMENTS"
+```

package/commands/mdd-lifecycle.md

@@ -1,21 +1,13 @@
-## Phase Logging
-
-At the **start** of every phase (before any action) and the **end** of every phase (after all actions), run the command below. Substitute `PHASE` with the phase identifier (e.g., `Phase R1`, `Phase G2`, `Phase UP3`) and `EVENT` with `start` or `end`:
-
-```bash
-bash -c 'D=$(date +%Y-%m-%d); T=$(date +%H:%M:%S); K=$(compressmcp --status 2>/dev/null | grep -oE "[0-9]+K/[0-9]+K" | head -1 || echo "-"); mkdir -p ~/.claude/mdd; printf "| %s | mdd-lifecycle | PHASE | EVENT | %s | %s |\n" "$D" "$T" "$K" >> ~/.claude/mdd/log.md' 2>/dev/null || true
-```
-
-Log file: `~/.claude/mdd/log.md`
-
----
-
 ## REVERSE-ENGINEER MODE — `/mdd reverse-engineer [path or feature-id]`
 
 Triggered when arguments start with `reverse-engineer` or `reverse`. Generates or regenerates MDD documentation from existing source code.
 
 ### Phase R1 — Determine scope
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R1" start "$ARGUMENTS"
+```
+
 **If a path or feature-id is given:**
 - If it matches an existing `.mdd/docs/*.md` — load that doc as the "existing doc" for comparison (regenerate mode).
 - If it's a file path — read that file as the only source (new doc mode).
@@ -25,8 +17,16 @@ Triggered when arguments start with `reverse-engineer` or `reverse`. Generates o
 - Cross-reference against `source_files` fields in all `.mdd/docs/*.md`.
 - List files not registered in any doc. Ask the user which ones to document.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R1" end "$ARGUMENTS"
+```
 ### Phase R2 — Read source files (parallelized for multi-file scope)
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R2" start "$ARGUMENTS"
+```
+
 **Threshold rule:**
 - ≤ 3 source files: read directly in the main conversation — no agent overhead
 - 4+ source files: batch into parallel Explore agents (max 3), each reading a subset
@@ -67,8 +67,16 @@ After all agents return, synthesize their output into Phase R3 (draft the doc).
 
 **Fallback:** If any agent fails, read that batch of files directly in the main conversation.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R2" end "$ARGUMENTS"
+```
 ### Phase R3 — Draft the doc
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R3" start "$ARGUMENTS"
+```
+
 Draft a complete feature doc following the Phase 3 template. Set:
 - `last_synced: <today>`
 - `status: draft` (since business intent may be incomplete)
@@ -92,8 +100,16 @@ Ask: "Merge new draft into existing doc? (yes / keep existing / show full diff)"
 
 **In new doc mode:** Show the full draft and ask: "Does this accurately describe the feature? Anything to add or change?"
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R3" end "$ARGUMENTS"
+```
 ### Phase R4 — Save and optionally generate test skeletons
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R4" start "$ARGUMENTS"
+```
+
 After user confirmation, write the doc. Then ask:
 "Generate test skeletons from the inferred endpoints and business rules? (yes / no)"
 
@@ -109,20 +125,40 @@ If yes, follow Phase 4 logic using the newly written doc.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase R4" end "$ARGUMENTS"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "-" "complete" "$ARGUMENTS"
+```
 ## GRAPH MODE — `/mdd graph`
 
 Triggered when arguments start with `graph`. Shows the cross-feature dependency map, plus initiative/wave structure if present.
 
 ### Phase G1 — Build dependency graph
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase G1" start "$ARGUMENTS"
+```
+
 Read all `.mdd/docs/*.md` (including `archive/`). For each doc, extract `id`, `title`, `status`, and `depends_on`.
 
 Build a directed graph: edge A → B means "A depends on B" (B must exist for A to work).
 
 **Initiative/wave graph** (only shown if `.mdd/initiatives/` exists): Also read all initiative and wave files. Build a second graph showing the initiative → wave → feature doc hierarchy.
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase G1" end "$ARGUMENTS"
+```
 ### Phase G2 — Detect issues
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase G2" start "$ARGUMENTS"
+```
+
 **Broken dependency:** A doc lists a deprecated or archived feature in `depends_on`.
 
 **Risky dependency:** A `status: complete` feature depends on a `status: in_progress` or `status: draft` feature.
@@ -136,8 +172,16 @@ Build a directed graph: edge A → B means "A depends on B" (B must exist for A
 - A wave references a `dependsOn` wave that is not in the same initiative → invalid (cross-initiative deps not supported)
 - A feature doc whose slug appears in a wave but has no `docPath` set and status is `complete` → doc missing for completed feature
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase G2" end "$ARGUMENTS"
+```
 ### Phase G3 — Render
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase G3" start "$ARGUMENTS"
+```
+
 ```
 📊 MDD Dependency Graph
 
@@ -189,6 +233,14 @@ Save the graph to `.mdd/audits/graph-<date>.md`.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase G3" end "$ARGUMENTS"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "-" "complete" "$ARGUMENTS"
+```
 ## UPGRADE MODE — `/mdd upgrade`
 
 Triggered when arguments start with `upgrade`.
@@ -201,6 +253,10 @@ Batch-patches missing frontmatter fields (`last_synced`, `status`, `phase`, `tag
 
 ### Phase UP1 — Inventory
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP1" start "$ARGUMENTS"
+```
+
 1. Glob `.mdd/docs/*.md` (and `.mdd/docs/archive/*.md` if it exists). Collect all paths.
 2. For each doc, read its frontmatter only (up to the closing `---` line).
 3. Build an inventory table:
@@ -228,8 +284,16 @@ Fields to add:
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP1" end "$ARGUMENTS"
+```
 ### Phase UP2 — Infer Defaults (per doc)
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP2" start "$ARGUMENTS"
+```
+
 For each doc that needs patching, infer sensible defaults. **Do NOT ask the user for each doc** — infer silently, then show the plan for confirmation.
 
 **`last_synced` inference:**
@@ -273,8 +337,16 @@ For each doc missing `path`:
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP2" end "$ARGUMENTS"
+```
 ### Phase UP3 — Show Plan + Confirm
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP3" start "$ARGUMENTS"
+```
+
 Present the inferred patches to the user before writing anything:
 
 ```
@@ -308,8 +380,16 @@ If the user says **"yes"**: proceed to Phase UP4 with all inferred values.
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP3" end "$ARGUMENTS"
+```
 ### Phase UP4 — Patch Docs
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP4" start "$ARGUMENTS"
+```
+
 For each doc in the plan, patch the frontmatter block **non-destructively**:
 
 **Rules:**
@@ -354,8 +434,16 @@ Patching...
 
 ---
 
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP4" end "$ARGUMENTS"
+```
 ### Phase UP5 — Verify + Rebuild Startup
 
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP5" start "$ARGUMENTS"
+```
+
 After all patches are applied:
 
 1. Re-scan `.mdd/docs/*.md` — confirm 0 docs have missing `last_synced` or `path`
@@ -386,3 +474,12 @@ Run `/mdd scan` to see current drift status across all docs.
 ---
 
 ---
+
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "Phase UP5" end "$ARGUMENTS"
+```
+
+```bash
+bash ~/.claude/hooks/mdd-log-phase.sh "mdd-lifecycle" "-" "complete" "$ARGUMENTS"
+```