mdd-workflow

name

mdd-workflow

description

Use in any project that uses MDD (a `.mdd/` directory exists) when editing source code, building a feature, fixing a bug, requesting an audit, or editing `.mdd/docs` files. Keeps feature docs in sync the moment their controlled source files change, recommends the `/mdd` workflow for substantial tasks, and conforms to `.mdd` doc conventions. Installed globally, so it self-gates: it does nothing in projects that don't use MDD.

MDD Workflow Companion

This skill complements the /mdd command. The command owns the workflow; this skill keeps things honest between command runs. Its single most valuable job is preventing documentation drift the moment it would happen, before it accumulates.

Step 1 — Gate (do this first, every time)

Act only if this project uses MDD. Check for any of:

• a .mdd/ directory in the project root, or
• a resolvable /mdd command (.claude/mdd/, ~/.claude/mdd/, .claude/commands/mdd.md).

If none exist, stop silently. Do nothing, say nothing, never mention MDD. This skill is installed globally and will activate in projects that have never adopted MDD; in those projects it must be invisible.

Two hard rules that hold for everything below:

• Never run the workflow yourself. No branching, no .mdd/ bootstrap, no phase execution. You recommend /mdd and let the user confirm. The command performs all side effects.
• Silence is the default. When you activate but there is nothing controlled to sync and nothing substantial to recommend, produce no MDD output at all. Never narrate the gate or the check.

Step 2 — Job 1: Prevent doc drift when editing controlled code (priority)

Feature docs declare the source they own in frontmatter (source_files, plus routes and models). When that source is edited outside a /mdd run, the doc silently goes stale. Catch it at the edit, not weeks later in /mdd scan.

When you are about to edit (or have just edited) a source file in an MDD project:

1. Cheap controlled-file check. Grep .mdd/docs/*.md for the file's path in source_files (and routes/models if the change adds or alters a route or model):

   grep -rl "<relative/path/to/file>" .mdd/docs/*.md
   

   No match → the file is not controlled. Stay silent and proceed normally.

2. If a doc controls the file, name it and keep it in sync:

   • Read .mdd/docs/00-frontmatter-spec.md first so any frontmatter edit conforms to the schema.
   • Make the lightweight, factual updates inline: bump last_synced to today; add a new endpoint to routes; add a new model to models; append a genuinely new defect to known_issues (append-only — never remove entries).
   • Tell the user in one line: 📝 Edited <file>, controlled by .mdd/docs/<id>.md — synced last_synced and routes.
   • If the change is structural (behavior, business rules, contracts, or data flow changed, not just a field), don't try to re-derive the doc body yourself. Recommend the command that does a full resync: This change affects how <id> behaves. Run \/mdd update ` (or `/mdd audit`) for a full doc resync.`

3. If the user is mid-flow and declines the sync, don't block their work. Note it once so it isn't lost: Leaving .mdd/docs/<id>.md unsynced — \/mdd scan` will flag it later.`

This is real-time and pre-commit, which is precisely what /mdd status and /mdd scan cannot do (they detect drift retrospectively, from git history, only when invoked). Defer batch and historical drift detection to those commands; this skill catches the single edit as it lands.

Step 3 — Job 2: Recommend the workflow for substantial tasks (recommend, never run)

When the user asks for work MDD is built for and it would genuinely benefit, offer the matching mode once, then defer to the user.

Nudge when the task is a new feature, a real (non-trivial) bug, a meaningful refactor, or an audit — and especially when it will touch code controlled by an existing feature doc that would drift if done ad-hoc.

Do not nudge for typos, formatting, renames, config tweaks, one-liners, or plain questions. Anything too small to deserve a doc is too small to nudge.

The offer is one line, in the user's words, and waits:

You have MDD installed and this looks like a task that would benefit from it — /mdd <feature> documents it first, then builds against the doc. Want me to use it, or just proceed here?

Pick the right invocation: feature → /mdd <feature-slug>; bug → /mdd bug; audit → /mdd audit; existing-doc drift → /mdd update <id>.

One offer per task. If the user declines or says "just do it," proceed ad-hoc and don't ask again this task. Never run /mdd without an explicit yes — but Job 1 still applies, so keep any controlled doc in sync even while working ad-hoc.

Step 4 — Job 3: Keep .mdd/docs conventions correct

When editing a .mdd/docs/*.md file directly (not through /mdd), read .mdd/docs/00-frontmatter-spec.md first and conform:

• All required frontmatter fields present and correctly typed.
• satisfies_contracts entries use the from / function / when / status (pending|done) / verified_at shape — the field is verified_at, not verified.
• relates is symmetric: if doc A relates B, ensure B relates A.
• known_issues is append-only.
• Tags are domain concepts, technology names, or feature names — never file paths or generic words.

What this skill does NOT do

• It does not execute, branch, bootstrap, or run any MDD phase — /mdd does that.
• It does not re-derive doc bodies or do full resyncs — /mdd update, /mdd audit, and /mdd scan do that.
• It does not act, or mention MDD, in projects that don't use MDD.