
doc-driven-development
Documentation-driven development workflow for planning and implementing code changes based on markdown documentation
- GitHub stars
- 6
Install
/plugin install doc-driven-development@cbrakeRun it inside Claude Code after adding the marketplace with /plugin marketplace add cbrake/claude-plugins.
Contents
Discovered from sourceCommands 9
Run the complete TDD implementation cycle for the IN PROGRESS plan.
This command chains together the full development workflow:
- Implement tests first (TDD)
- Implement the code to pass the tests
- Update documentation to reflect changes
- Perform comprehensive code review
Phase 1: Verify Active Plan
- Read
plans/plans.mdto find the plan marked IN PROGRESS. - If no plan is in progress, inform the user and suggest running
/planfirst. - Read the plan file to understand the scope of work.
Phase 2: Implement Tests
Implement tests for the IN PROGRESS plan, creating logical git commits for each unit of work.
Step 2.1: Plan Test Units
Analyze the plan and break the implementation into logical units. Each unit should be:
- A single function, method, or component
- A cohesive set of related changes
- Small enough to understand in one commit
Create or edit a commit table in the IN PROGRESS plan file that tracks these logical units, what has or has not been implemented, and the hash if it has been implemented, so that you can see what needs to be done.
Step 2.2: Implement and Commit Each Test Unit
For each test unit:
- Write the tests for that unit.
- Stage the changes with
git add. - Create a commit using conventional commit format:
test:for new teststest: fixfor fixing broken tests- Commits should be done in the developer's name, never Claude's.
- Capture the commit hash using
git rev-parse --short HEAD. - Add the commit to the plan file's
## Commitssection.
The ## Commits section in the plan file uses this format:
## Commits
| Hash | Description | Status |
|------|-------------|--------|
| abc1234 | test: user authentication module | Implemented |
| def5678 | test: login form component | Not Implemented |
Step 2.3: Finalize Tests
Update the plan file with any test implementation details. Keep the plan status as IN PROGRESS (tests alone don't complete a plan).
Phase 3: Implement Code
Implement code changes for the IN PROGRESS plan, creating logical git commits for each unit of work.
Step 3.1: Plan Implementation Units
Analyze the plan and break the implementation into logical units. Each unit should be:
- A single function, method, or component
- A cohesive set of related changes
- Small enough to understand in one commit
Update the commit table in the IN PROGRESS plan file to track implementation units.
Step 3.2: Implement and Commit Each Unit
For each implementation unit:
- Make the code changes for that unit.
- Stage the changes with
git add. - Create a commit using conventional commit format:
feat:for new featuresfix:for bug fixesrefactor:for code restructuringdocs:for documentation changes- Commits should be done in the developer's name, never Claude's.
- Capture the commit hash using
git rev-parse --short HEAD. - Add the commit to the plan file's
## Commitssection.
Step 3.3: Finalize Implementation
- Update the plan file with any implementation details or deviations.
- Change the status in the plan file to
Implemented.
Phase 4: Update Documentation
Update any relevant documentation to accurately reflect the code changes since
the starting hash for this plan recorded in the plans/plans.md file.
Documentation Guidelines
- Be concise. AI tends to generate very verbose/wordy documentation. Don't do that.
- Don't add trivial examples that users can easily figure out.
- Avoid duplicated information when possible.
- The first word in a list item should always be capitalized.
- Sentences (or close to it) in a list should always end with a period.
Step 4.1: Update Project Documentation
- Update
CLAUDE.mdwith any architectural or technical details. - Update
README.mdif user-facing behavior changed.
Step 4.2: Update Changelog
Update the CHANGELOG.md to describe changes as benefits to the user. It should
not include technical details of the change - that is what git log is for.
Step 4.3: Update Plan File
Review all changes since the starting hash for this plan and make sure the plan accurately reflects these changes. The plan should document:
- What was implemented.
- Technical decisions and their rationale.
- Any deviations from the original plan.
Do not add excessive examples to the plan file.
Phase 5: Code Review
Perform a comprehensive code review on changes using specialized review agents.
Step 5.1: Gather Context
First, verify the current directory is a git repository. If not, inform the user and exit.
Check plans/plans.md to find the IN PROGRESS file, and get its starting
commit hash. Run git diff on this hash to see what has changed. Also check
whether a FORMAT.md file exists in the repository root.
Step 5.2: Launch Review Agents
Use the Task tool to spawn the following review agents in parallel. Each agent analyzes the git diff output and provides findings.
Agent 1: Formatting Review
Focus: Code formatting consistency
Instructions:
- Check if
FORMAT.mdexists in the repository root. - If missing, analyze the codebase to identify formatting patterns
(indentation, naming conventions, bracket styles, line lengths). Before
creating
FORMAT.md, check again that it doesn't exist to avoid race conditions with concurrent reviews. - Review all changed code against the formatting standards.
- Report any formatting inconsistencies.
Output format:
## Formatting Review
- [List of formatting issues found, or "No issues found"]
- [If FORMAT.md was created, note this]
Agent 2: Architectural Consistency Review
Focus: Adherence to documented architecture
Instructions:
- Read README.md and any architecture documentation (ARCHITECTURE.md, DESIGN.md, CLAUDE.md).
- Identify documented architectural decisions (module boundaries, patterns, conventions).
- Review changed code for violations of these patterns.
- Report any architectural inconsistencies.
Output format:
## Architectural Consistency Review
- [List of architectural concerns, or "Code follows documented architecture"]
Agent 3: Documentation Accuracy Review
Focus: Ensuring documentation matches code
Instructions:
- Compare code changes to README.md, CHANGELOG.md, and the IN PROGRESS plan file.
- Identify any code functionality not reflected in documentation.
- Identify any documentation claims not supported by the code.
- Identify any features marked as implemented that are not implemented.
- Identify any inconsistent, contradictory, or outdated documentation.
Output format:
## Documentation Accuracy Review
- [List of documentation gaps or inconsistencies, or "Documentation is accurate"]
Agent 4: Potential Bugs Review
Focus: Identifying potential bugs and edge cases
Instructions:
- Analyze changed code for common bug patterns.
- Look for: null/undefined handling, boundary conditions, race conditions, resource leaks, error handling gaps.
- Consider edge cases that may not be handled.
- Note any security concerns.
Output format:
## Potential Bugs Review
- [List of potential bugs with severity and location]
- [Each bug should include: description, location, suggested fix]
Agent 5: Code Clarity Review
Focus: Code clarity and design decisions
Instructions:
- For each significant code change, first justify why the code is structured this way. Significant changes include: new functions/methods, modified logic flow, new classes/modules, or changes exceeding 10 lines. Exclude trivial changes like import reordering, whitespace, or simple renames.
- Then critically evaluate: validate the reasoning or suggest improvements with rationale.
- Alternate between advocate and critic perspectives until all significant code is reviewed.
Output format:
## Code Clarity Review
### [File/Function Name]
**Advocate**: [Justification for code design]
**Critic**: [Validation or improvement suggestion]
Agent 6: Comments Review
Focus: Quality and usefulness of code comments
Instructions:
- Review all comments in changed code (function docs, inline comments).
- Assess whether comments add value beyond what code already expresses.
- Identify missing comments where complexity warrants explanation.
- Flag redundant or misleading comments.
Output format:
## Comments Review
- [List of comment improvements needed, or "Comments are appropriate"]
Step 5.3: Consolidate Results
After all agents complete, append all review output to the IN PROGRESS plan
file under a ## Review (<current-date>) heading. Include:
- A summary of issues found per category.
- All agent outputs in full.
- Highlight any critical issues requiring immediate attention.
- Note if FORMAT.md was auto-generated.
Step 5.4: Commit Decision
Create a commit and auto-commit with a message summarizing what was implemented and key review findings.
Step 5.5: Completion Decision
After handling the commit decision:
- Display a summary of what was implemented vs what remains in the plan.
- Ask the user if the plan should be:
- Completed - Mark the plan as Completed in
plans/plans.md(implementation is done) - Continue - Keep the plan as IN PROGRESS for further iteration
- Completed - Mark the plan as Completed in
If Completed is selected, update plans/plans.md to change the plan status from
IN PROGRESS to Completed.
Notes
- Each phase builds on the previous; if any phase fails, stop and address the issue.
- Commits are created incrementally throughout the process.
- The plan file tracks all commits and serves as the source of truth.
- Documentation drives code changes in this workflow, not the other way around.
- Commits should be done in the developer's name, never Claude's.
Find and execute inline instructions or pseudo code marked with special tags in code or documentation.
First, use git diff to identify recently changed files that may contain instruction markers.
Look for instruction markers in the following formats:
@CLAUDE: <instruction or pseudo code>- Single line instruction@CLAUDE-START/@CLAUDE-END- Multi-line instruction or pseudo code blocks- In code comments:
// @CLAUDE:,# @CLAUDE:,/* @CLAUDE: */,<!-- @CLAUDE: --> - In markdown: Lines starting with
> @CLAUDE:or within code blocks labeled with@CLAUDE
The markers can contain:
- Direct instructions (e.g., "Add error handling here", "Refactor this to use async/await")
- Pseudo code describing what should be implemented
- Implementation notes or TODO-like directives
When you find instruction markers:
- Extract the complete instruction or pseudo code text
- Execute/implement the instruction or pseudo code as described
- After successfully completing the work, remove the marker tags completely
- If a plan file exists in
plans/that is uncommitted (check withgit status), update it to reflect what was done
The instruction markers are meant for surgical, targeted changes. Focus on:
- The specific instruction or pseudo code provided
- The immediate context around the marker
- Keeping changes minimal and focused
If "$ARGUMENTS" are provided, use them to filter which markers to execute (e.g., file path, keyword). If no arguments provided, process all instruction markers found in uncommitted changes.
After completing all instructions, provide a summary of what was executed and what was changed.
Implement tests for the IN PROGRESS plan, creating logical git commits for each unit of work.
Step 1: Find the Active Plan
- Read
plans/plans.mdto find the plan marked IN PROGRESS. - If no plan is in progress, inform the user and suggest running
/planfirst. - Read the plan file to understand what tests are needed.
Step 2: Plan Implementation Units
Analyze the plan and break the implementation into logical units. Each unit should be:
- A single function, method, or component
- A cohesive set of related changes
- Small enough to understand in one commit
Create or edit a commit table in the IN PROGRESS plan file that tracks these logical units, what has or has not been implemented, and the hash if it has been implemented, so that you can see what needs to be done.
Step 3: Implement and Commit Each Unit
For each test unit:
- Write the tests for that unit.
- Stage the changes with
git add. - Create a commit using conventional commit format:
test:for new teststest: fixfor fixing broken tests- Commits should be done in the developer's name, never Claude's.
- Capture the commit hash using
git rev-parse --short HEAD. - Add the commit to the plan file's
## Commitssection.
The ## Commits section in the plan file uses this format:
## Commits
| Hash | Description | Status |
|------|-------------|--------|
| abc1234 | test: user authentication module | Implemented|
| def5678 | test: login form component |Not Implemented|
Commits should be done in the developer's name, never Claude's.
Step 4: Finalize
Update the plan file with any test implementation details. Keep the plan status as IN PROGRESS (tests alone don't complete a plan).
Note: Documentation drives test code changes in this workflow, not the other way around.
Implement code changes for the IN PROGRESS plan, creating logical git commits for each unit of work.
Step 1: Find the Active Plan
- Read
plans/plans.mdto find the plan marked IN PROGRESS. - If no plan is in progress, inform the user and suggest running
/planfirst. - Read the plan file to understand what needs to be implemented.
Step 2: Plan Implementation Units
Analyze the plan and break the implementation into logical units. Each unit should be:
- A single function, method, or component
- A cohesive set of related changes
- Small enough to understand in one commit
Create a table in the IN PROGRESS plan file that tracks these logical units, what has or has not been implemented, and the hash if it has been implemented, so that you can see what needs to be done.
Step 3: Implement and Commit Each Unit
For each implementation unit:
- Make the code changes for that unit.
- Stage the changes with
git add. - Create a commit using conventional commit format:
feat:for new featuresfix:for bug fixesrefactor:for code restructuringdocs:for documentation changes- Commits should be done in the developer's name, never Claude's.
- Capture the commit hash using
git rev-parse --short HEAD. - Add the commit to the plan file's
## Commitssection.
The ## Commits section in the plan file uses this format:
## Commits
| Hash | Description | Status |
|------|-------------|--------|
| abc1234 | feat: add user authentication module | Implemented|
| def5678 | feat: add login form component |Not Implemented|
Commits should be done in the developer's name, never Claude's.
Step 4: Finalize
- Update the plan file with any implementation details or deviations.
- Change the status in the plan file to
Implemented.
Note: Documentation drives code changes in this workflow, not the other way around.
Create a plan file named plans/<current date>-"$ARGUMENTS".md. Replace spaces
with '-' in the filename.
If a plan exists in plans/plans.md that is marked IN PROGRESS then ask the user if they would like to update that plan or start a new one.
Then switch to plan mode and create a plan for coding the current changes and
untracked files (start with git diff and git status) described in the
README.md and other documentation files. Note, in this phase, we are using
documentation to drive the code, not the other way around. When the plan is
complete, write it to the plan file.
The documentation may be written in past tense as if the feature already exists. Assume any changes that have not been committed have not been implemented yet, even though they are described as already implemented. This is a side effect of documentation driven development.
Plan Tracking
After the plan is finalized, update plans/plans.md:
- Capture the current commit hash using
git rev-parse --short HEAD. - If
plans/plans.mddoes not exist, create it with a table header. - Change any existing IN PROGRESS plan to Paused.
- Add the new plan marked as IN PROGRESS with the commit hash in the "Started At" column.
- Commit the plan to git
The plans/plans.md file uses this format:
# Plans
| Plan | Status | Branched From |
|------|--------|------------|
| 2026-01-17-new-feature.md | **IN PROGRESS** | abc1234 |
| 2026-01-16-paused-feature.md | **Paused** | def5678 |
| 2026-01-15-old-feature.md | Completed | 9012345 |
The "Branched From" column records the commit hash from git rev-parse --short HEAD
when the plan was created. This provides a reference point for reviewing all
changes made during implementation.
Automate the release process by updating the changelog, manifest files, and creating a git tag.
Steps:
-
Read @CLAUDE.md to find the list of manifest files under the "Release Management" section. These files contain version numbers that need to be updated.
-
Read the CHANGELOG.md file to find:
- The latest version number (look for
## [X.Y.Z]format) - Any
## [Unreleased]section that needs to be converted
- The latest version number (look for
-
Determine the release version:
- If "$ARGUMENTS" are provided, use that as the version number (e.g.,
/release 2.0.0) - If an
## [Unreleased]section exists, calculate the next version by incrementing the patch version (e.g., 1.0.6 → 1.0.7) - If no
## [Unreleased]section exists, use the latest version found in the changelog
- If "$ARGUMENTS" are provided, use that as the version number (e.g.,
-
Update CHANGELOG.md:
- Replace
## [Unreleased]with## [X.Y.Z] - <current date in YYYY-MM-DD format> - Keep all content under that section unchanged
- Add a
## [Unreleased]section at the top for new changes.
- Replace
-
Update version in all manifest files listed in CLAUDE.md:
- Search for version fields in each manifest file (patterns like
"version":,version =,version:, etc.) - Update the version value to match the release version
- Preserve all other fields and formatting
- Search for version fields in each manifest file (patterns like
-
Create a git tag for the version:
- Format:
v<version>(e.g.,v1.0.7) - Use
git tag v<version>to create the tag
- Format:
-
Provide a summary showing:
- The version that was released
- The date applied to the changelog
- Which manifest files were updated
- The git tag created
- Remind the user to commit the changes and push with
git push --tags
Important: Do not push tags or commit changes automatically. Let the user review and push when ready.
Perform a comprehensive code review on uncommitted changes using specialized review agents.
Step 1: Gather Context
First, verify the current directory is a git repository. If not, inform the user and exit.
Check plans/plans.md to find the IN PROGRESS file, and get it starting commit hash. Run git diff on this hash to see what has changed since this hash. Also check whether a FORMAT.md file exists in the repository root.
If no IN PROGRESS plan exists in plans/plans.md, inform the user and suggest running /doc-driven-development:plan first to create one.
Step 2: Launch Review Agents
Use the Task tool to spawn the following review agents in parallel. Each agent analyzes the git diff output and provides findings.
Agent 1: Formatting Review
Focus: Code formatting consistency
Instructions:
- Check if
FORMAT.mdexists in the repository root. - If missing, analyze the codebase to identify formatting patterns (indentation, naming conventions, bracket styles, line lengths). Before creating
FORMAT.md, check again that it doesn't exist to avoid race conditions with concurrent reviews. - Review all changed code against the formatting standards.
- Report any formatting inconsistencies.
Output format:
## Formatting Review
- [List of formatting issues found, or "No issues found"]
- [If FORMAT.md was created, note this]
Agent 2: Architectural Consistency Review
Focus: Adherence to documented architecture
Instructions:
- Read README.md and any architecture documentation (ARCHITECTURE.md, DESIGN.md, CLAUDE.md).
- Identify documented architectural decisions (module boundaries, patterns, conventions).
- Review changed code for violations of these patterns.
- Report any architectural inconsistencies.
Output format:
## Architectural Consistency Review
- [List of architectural concerns, or "Code follows documented architecture"]
Agent 3: Documentation Accuracy Review
Focus: Ensuring documentation matches code
Instructions:
- Compare code changes to README.md, CHANGELOG.md, and the IN PROGRESS plan file.
- Identify any code functionality not reflected in documentation.
- Identify any documentation claims not supported by the code.
- Identify any features marked as implemented that are not implemented.
- Identify any inconsistent, contradictory, or outdated documentation
Output format:
## Documentation Accuracy Review
- [List of documentation gaps or inconsistencies, or "Documentation is accurate"]
Agent 4: Potential Bugs Review
Focus: Identifying potential bugs and edge cases
Instructions:
- Analyze changed code for common bug patterns.
- Look for: null/undefined handling, boundary conditions, race conditions, resource leaks, error handling gaps.
- Consider edge cases that may not be handled.
- Note any security concerns.
Output format:
## Potential Bugs Review
- [List of potential bugs with severity and location]
- [Each bug should include: description, location, suggested fix]
Agent 5: Code Clarity Review
Focus: Code clarity and design decisions
Instructions:
- For each significant code change, first justify why the code is structured this way. Significant changes include: new functions/methods, modified logic flow, new classes/modules, or changes exceeding 10 lines. Exclude trivial changes like import reordering, whitespace, or simple renames.
- Then critically evaluate: validate the reasoning or suggest improvements with rationale.
- Alternate between advocate and critic perspectives until all significant code is reviewed.
Output format:
## Code Clarity Review
### [File/Function Name]
**Advocate**: [Justification for code design]
**Critic**: [Validation or improvement suggestion]
Agent 6: Comments Review
Focus: Quality and usefulness of code comments
Instructions:
- Review all comments in changed code (function docs, inline comments).
- Assess whether comments add value beyond what code already expresses.
- Identify missing comments where complexity warrants explanation.
- Flag redundant or misleading comments.
Output format:
## Comments Review
- [List of comment improvements needed, or "Comments are appropriate"]
Step 3: Consolidate Results
After all agents complete, append all review output to the IN PROGRESS plan file under a ## Review (<current-date>) heading. Include:
- A summary of issues found per category
- All agent outputs in full
- Highlight any critical issues requiring immediate attention
- Note if FORMAT.md was auto-generated
Step 4: Commit Decision
Create a commit and auto-commit with a message summarizing what was implemented and key review findings.
Step 5: Completion Decision
After handling the commit decision:
- Display a summary of what was implemented vs what remains in the plan
- Ask the user if the plan should be:
- Completed - Mark the plan as Completed in
plans/plans.md(implementation is done) - Continue - Keep the plan as IN PROGRESS for further iteration
- Completed - Mark the plan as Completed in
If Completed is selected, update plans/plans.md to change the plan status from IN PROGRESS to Completed.
Skip this edit/command and continue what you were doing.
Update any relevant documentation to accurately reflect the code changes since the starting hash for this plan recorded in the plans/plans.md file. Some guidelines:
- Be concise. AI tends to generate very verbose/wordy documentation. Don't do that.
- Don't add trivial examples that users can easily figure out.
- Avoid duplicated information when possible.
- The first word in a list item should always be capitalized.
- Sentences (or close to it) in a list should always end with a period.
Update CLAUDE.md with any architectural or technical details.
Also, update the CHANGELOG.md to describe changes as benefits to the user. It
should not include technical details of the change - that is what git log is
for.
Plan File Updates
Review all changes since the starting hash for this plan recorded in the plans/plans.md file and make sure the plan accurately reflects these changes.
The plan should document:
- What was implemented.
- Technical decisions and their rationale.
- Any deviations from the original plan.
Do not add excessive examples to the plan file.
Sponsors
Details
- Marketplace
- cbrake/claude-plugins
- Source
- doc-driven-development
- Author
- Cliff Brake
- Category
- Community