mdd

MDD — Manual-First Development Workflow

$ARGUMENTS

MDD is the core development workflow. Every feature starts with documentation, every fix starts with an audit. No exceptions.

Step 0 — Detect Mode

Parse $ARGUMENTS to determine the mode:

• If arguments start with audit → Audit Mode (jump to Phase A)
• If arguments start with status → Status Mode (jump to Phase S)
• If arguments are empty → ask the user what they want to do
• Otherwise → Build Mode (the default — jump to Phase 1)

---

BUILD MODE — New Feature Development

Phase 1 — Understand the Feature

Read the user's description: $ARGUMENTS

Before writing anything, gather context:

1. Read CLAUDE.md — understand project rules
2. Read docs/PROJECT_CONTEXT.md if present — use as primary feature map and quick reference
3. Read docs/ARCHITECTURE_SUMMARY.md if present — architecture brief
4. Read only the specific feature doc(s) relevant to this request — do not scan all docs by default
5. Read docs/ARCHITECTURE.md only if the task changes or crosses architectural boundaries
6. Read subtree CLAUDE.md files for the areas being touched (e.g., server/CLAUDE.md, client/CLAUDE.md) if present
7. Scan src/ — only the relevant area for the requested feature

Then ask the user targeted questions using AskUserQuestion. Ask ALL relevant questions upfront in a single interaction — don't spread them across multiple turns:

Always ask:

• "Does this feature need database storage? If so, what data does it store?"
• "Does this feature have API endpoints? What operations (create, read, update, delete)?"
• "Does this feature depend on any existing features?" (list the relevant ones from docs/PROJECT_CONTEXT.md or docs/*.md)
• "Are there any edge cases or error scenarios you already know about?"

Ask if relevant:

• "Does this need authentication/authorization?"
• "Does this need real-time updates (WebSocket)?"
• "Does this need background processing (queues, cron)?"
• "Does this integrate with any external services?"