0 Help

---
name: ddd:0-help
version: 1.0.0
description: DDD workflow guide and help
triggers:
  - "Need help with DDD"
  - "How does document-driven development work"
  - "DDD workflow overview"
invokes:
  - type: workflow
    path: .claude/workflow/DDD_WORKFLOW.md
---

# Document-Driven Development (DDD) - Complete Guide

Loading DDD context for comprehensive help...

@docs/document_driven_development/overview.md
@docs/document_driven_development/reference/tips_for_success.md
@docs/document_driven_development/reference/common_pitfalls.md
@docs/document_driven_development/reference/faq.md
@~/.amplihack/.claude/context/PHILOSOPHY.md
@~/.amplihack/.claude/context/PHILOSOPHY.md

---

## What is Document-Driven Development?

**Core Principle**: Documentation IS the specification. Code implements what documentation describes.

**Why it works**:

- Prevents context poisoning (inconsistent docs)
- Clear contracts before complexity
- Reviewable design before expensive implementation
- AI-optimized workflow
- Docs and code never drift

**Philosophy Foundation**:

- Ruthless Simplicity (IMPLEMENTATION_PHILOSOPHY)
- Modular Design / Bricks & Studs (MODULAR_DESIGN_PHILOSOPHY)

---

## Complete Workflow (5 Phases + Utilities)

### Main Workflow Commands (Run in Order)

**1. `/ddd:1-plan`** - Planning & Design

- Design feature before touching files
- Create comprehensive plan
- Get shared understanding
- **Output**: `ai_working/ddd/plan.md`

**2. `/ddd:2-docs`** - Update All Non-Code Files

- Update docs, configs, READMEs
- Apply retcon writing (as if already exists)
- Iterate until approved
- **Requires**: User must commit when satisfied

**3. `/ddd:3-code-plan`** - Plan Code Changes

- Assess current code vs new docs
- Plan all implementation changes
- Break into chunks
- **Requires**: User approval to proceed

**4. `/ddd:4-code`** - Implement & Verify

- Write code matching docs exactly
- Test as user would
- Iterate until working
- **Requires**: User authorization for each commit

**5. `/ddd:5-finish`** - Wrap-Up & Cleanup

- Clean temporary files
- Final verification
- Push/PR with explicit authorization
- **Requires**: User approval for all git operations

### Utility Commands

**`/ddd:prime`** - Load all DDD context

- Loads complete methodology documentation
- Use at session start for full context

**`/ddd:status`** - Check current progress

- Shows current phase
- Lists artifacts created
- Recommends next command

---

## State Management (Artifacts)

All phases use `ai_working/ddd/` directory:

ai_working/ddd/ ├── plan.md (Created by 1-plan, used by all) ├── docs_index.txt (Working file for 2-docs) ├── docs_status.md (Status from 2-docs) ├── code_plan.md (Created by 3-code-plan) ├── impl_status.md (Tracking for 4-code) └── test_report.md (Output from 4-code)

**Each command reads previous artifacts**, so you can run subsequent commands without arguments if you want to continue from where you left off.

---

## Example Usage

### Starting a New Feature

```bash
# Load context (optional but recommended)
/ddd:prime

# Phase 1: Plan the feature
/ddd:1-plan Add user authentication with JWT tokens

# Phase 2: Update all docs
/ddd:2-docs

# Review the changes, iterate if needed
# When satisfied, commit the docs yourself

# Phase 3: Plan code implementation
/ddd:3-code-plan

# Review the code plan, approve to continue

# Phase 4: Implement and test
/ddd:4-code

# Test, provide feedback, iterate until working

# Phase 5: Finalize
/ddd:5-finish

# Cleanup, push, PR (with your explicit approval at each step)

Checking Progress Mid-Stream

# See where you are in the workflow
/ddd:status

# It will tell you:
# - Current phase
# - Artifacts created
# - Next recommended command

Resuming After Break

# Check status
/ddd:status

# Run next phase (artifacts are preserved)
/ddd:3-code-plan

---

Key Design Decisions

No Auto-Commits

Every git operation requires explicit user authorization:

• You review changes before committing
• You control commit messages
• You decide when to push
• You approve PR creation

Iteration Support

Phases 2 and 4 are designed for back-and-forth:

• Provide feedback at any time
• Commands stay active until you're satisfied
• Easy to iterate without restarting

Artifact-Driven

Each phase creates artifacts for next phase:

• Can run without arguments (uses artifacts)
• Can override with arguments if needed
• State preserved across sessions

Agent Orchestration

Each phase suggests specialized agents:

• philosophy-guardian for design philosophy validation
• modular-builder for implementation
• bug-hunter for debugging
• test-coverage for tests
• cleanup (amplihack/specialized) for cleanup

---

Authorization Checkpoints

Phase 2 (Docs)

• ⚠️ YOU must commit docs after review
• Command stages changes but does NOT commit
• Review diff, iterate if needed, then commit when satisfied

Phase 4 (Code)

• ⚠️ Each code chunk requires explicit commit authorization
• Command asks before each commit
• You control commit messages and timing

Phase 5 (Finish)

• ⚠️ Explicit authorization for: commit remaining, push, create PR
• Clear prompts at each decision point
• You control what happens to your code

---

Common Workflows

Feature Development

1-plan → 2-docs → 3-code-plan → 4-code → 5-finish

Bug Fix with Docs

1-plan → 2-docs → 3-code-plan → 4-code → 5-finish

Documentation-Only Change

1-plan → 2-docs → 5-finish (skip code phases)

Refactoring

1-plan → 2-docs → 3-code-plan → 4-code → 5-finish

---

Troubleshooting

"I'm lost, where am I?"

/ddd:status

"I made a mistake in planning"

Edit ai_working/ddd/plan.md or re-run /ddd:1-plan with corrections

"Docs aren't right"

Stay in phase 2, provide feedback, command will iterate

"Code isn't working"

Stay in phase 4, provide feedback, iterate ```