mdd-workflow

# 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): ```bash 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 <id>\` (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.