document-driven-development

A standalone, reusable skill repository for document-driven development planning workflows.

This repository packages a canonical skill family that helps move work through a staged planning flow:

• ddd-workflow
• ddd-competitive-analysis
• ddd-spec
• ddd-design
• ddd-roadmap
• ddd-version
• ddd-task
• ddd-execute
• ddd-sync

Optional first stage:

• ddd-competitive-analysis -> ddd-spec when the user wants competitor references before spec work

Main flow:

• ddd-spec -> ddd-design -> ddd-roadmap -> ddd-version -> ddd-task -> ddd-execute

Supporting follow-up:

• ddd-sync updates related planning artifacts after execution progress or completion

This repository uses a canonical-source-plus-adapters structure.

• Canonical agent guidance: AGENTS.md
• Runtime compatibility symlinks: CLAUDE.md, GEMINI.md, CODEX.md, OPENCODE.md, OPENCLAW.md
• Canonical authored source: skills/
• Platform metadata: .claude-plugin/, .codex-plugin/, gemini-extension.json
• Runtime adapter notes: adapters/

The root guidance file is AGENTS.md. Runtime-specific filenames such as CLAUDE.md, GEMINI.md, CODEX.md, OPENCODE.md, and OPENCLAW.md are compatibility symlinks that point to the same canonical instructions.

The canonical skill text stays host-agnostic. Runtime-specific installation and packaging guidance lives in adapter docs.

This repository is organized to support:

• Claude Code
• Codex
• Gemini
• OpenCode
• OpenClaw
• other runtimes that can consume local skill or prompt directories

Compatibility here means the repository provides a stable canonical source and adapter surface. It does not assume identical discovery rules across runtimes, so adapter-specific install details should be documented per runtime rather than embedded into the shared skill text.

Claude-facing metadata lives at:

• .claude-plugin/plugin.json

Codex metadata lives at:

• .codex-plugin/plugin.json

Gemini extension metadata lives at:

• gemini-extension.json

Example prompts for testing the skill family:

• Use ddd-workflow for this feature idea.
• Use ddd-workflow for this feature idea and start with ddd-competitive-analysis against Claude Code and Codex.
• I have competitor references for this feature. Should we do ddd-competitive-analysis before ddd-spec?
• Draft the ddd-competitive-analysis report for this planning topic.
• Should this change start as ddd-spec, or is it ready to go straight into ddd-design, ddd-roadmap, or ddd-version planning?
• Draft the ddd-spec for this idea.
• The ddd-spec is ready. What should the ddd-design stage cover before ddd-roadmap placement?
• Does this need technical design, UI design, or both?
• I need UI design for this feature. I'll provide a mockup link — what should the design doc cover?
• I need UI design for this feature, but I do not have a mockup yet. What inputs are missing before we finalize UI details?
• Where on the ddd-roadmap does this belong now that ddd-spec and ddd-design are ready?
• Which ddd-version should own this work?
• Break this feature into a ddd-task checklist.
• Use ddd-execute for this approved task checklist.
• Implement the next ddd-task item in strict TDD mode.
• We finished the checklist implementation. Should we run ddd-sync now?
• We finished this milestone. What docs should be synced now with ddd-sync?

The canonical skill content lives in skills/.

.
├── AGENTS.md
├── CLAUDE.md -> AGENTS.md
├── GEMINI.md -> AGENTS.md
├── CODEX.md -> AGENTS.md
├── OPENCODE.md -> AGENTS.md
├── OPENCLAW.md -> AGENTS.md
├── README.md
├── LICENSE
├── skills/                                      # canonical authored source
├── .claude-plugin/
│   └── plugin.json
├── .codex-plugin/
│   └── plugin.json
├── gemini-extension.json
└── adapters/                                    # runtime-specific notes and packaging guidance

The repository keeps only one canonical authored source at skills/. There is no longer any repo-local .claude/ compatibility layer in the repository itself.

Claude compatibility now comes from the root guidance files plus .claude-plugin/ metadata.

adapters/ is where runtime-specific installation notes should live. Keep verified runtime differences there instead of splitting the canonical skill text by host.

Run this check from the repository root:

test -d skills/ddd-workflow

This verifies that the canonical skill source exists.