cbrake avatar

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@cbrake

Run it inside Claude Code after adding the marketplace with /plugin marketplace add cbrake/claude-plugins.

Contents

Discovered from source

Commands 9

Run the complete TDD implementation cycle for the IN PROGRESS plan.

This command chains together the full development workflow:

  1. Implement tests first (TDD)
  2. Implement the code to pass the tests
  3. Update documentation to reflect changes
  4. Perform comprehensive code review

Phase 1: Verify Active Plan

  1. Read plans/plans.md to find the plan marked IN PROGRESS.
  2. If no plan is in progress, inform the user and suggest running /plan first.
  3. 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:

  1. Write the tests for that unit.
  2. Stage the changes with git add.
  3. Create a commit using conventional commit format:
    • test: for new tests
    • test: fix for fixing broken tests
    • Commits should be done in the developer's name, never Claude's.
  4. Capture the commit hash using git rev-parse --short HEAD.
  5. Add the commit to the plan file's ## Commits section.

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:

  1. Make the code changes for that unit.
  2. Stage the changes with git add.
  3. Create a commit using conventional commit format:
    • feat: for new features
    • fix: for bug fixes
    • refactor: for code restructuring
    • docs: for documentation changes
    • Commits should be done in the developer's name, never Claude's.
  4. Capture the commit hash using git rev-parse --short HEAD.
  5. Add the commit to the plan file's ## Commits section.

Step 3.3: Finalize Implementation

  1. Update the plan file with any implementation details or deviations.
  2. 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.md with any architectural or technical details.
  • Update README.md if 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:

  1. Check if FORMAT.md exists in the repository root.
  2. 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.
  3. Review all changed code against the formatting standards.
  4. 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:

  1. Read README.md and any architecture documentation (ARCHITECTURE.md, DESIGN.md, CLAUDE.md).
  2. Identify documented architectural decisions (module boundaries, patterns, conventions).
  3. Review changed code for violations of these patterns.
  4. 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:

  1. Compare code changes to README.md, CHANGELOG.md, and the IN PROGRESS plan file.
  2. Identify any code functionality not reflected in documentation.
  3. Identify any documentation claims not supported by the code.
  4. Identify any features marked as implemented that are not implemented.
  5. 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:

  1. Analyze changed code for common bug patterns.
  2. Look for: null/undefined handling, boundary conditions, race conditions, resource leaks, error handling gaps.
  3. Consider edge cases that may not be handled.
  4. 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:

  1. 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.
  2. Then critically evaluate: validate the reasoning or suggest improvements with rationale.
  3. 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:

  1. Review all comments in changed code (function docs, inline comments).
  2. Assess whether comments add value beyond what code already expresses.
  3. Identify missing comments where complexity warrants explanation.
  4. 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:

  1. A summary of issues found per category.
  2. All agent outputs in full.
  3. Highlight any critical issues requiring immediate attention.
  4. 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:

  1. Display a summary of what was implemented vs what remains in the plan.
  2. 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

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:

  1. Extract the complete instruction or pseudo code text
  2. Execute/implement the instruction or pseudo code as described
  3. After successfully completing the work, remove the marker tags completely
  4. If a plan file exists in plans/ that is uncommitted (check with git 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

  1. Read plans/plans.md to find the plan marked IN PROGRESS.
  2. If no plan is in progress, inform the user and suggest running /plan first.
  3. 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:

  1. Write the tests for that unit.
  2. Stage the changes with git add.
  3. Create a commit using conventional commit format:
    • test: for new tests
    • test: fix for fixing broken tests
    • Commits should be done in the developer's name, never Claude's.
  4. Capture the commit hash using git rev-parse --short HEAD.
  5. Add the commit to the plan file's ## Commits section.

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

  1. Read plans/plans.md to find the plan marked IN PROGRESS.
  2. If no plan is in progress, inform the user and suggest running /plan first.
  3. 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:

  1. Make the code changes for that unit.
  2. Stage the changes with git add.
  3. Create a commit using conventional commit format:
    • feat: for new features
    • fix: for bug fixes
    • refactor: for code restructuring
    • docs: for documentation changes
    • Commits should be done in the developer's name, never Claude's.
  4. Capture the commit hash using git rev-parse --short HEAD.
  5. Add the commit to the plan file's ## Commits section.

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

  1. Update the plan file with any implementation details or deviations.
  2. 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:

  1. Capture the current commit hash using git rev-parse --short HEAD.
  2. If plans/plans.md does not exist, create it with a table header.
  3. Change any existing IN PROGRESS plan to Paused.
  4. Add the new plan marked as IN PROGRESS with the commit hash in the "Started At" column.
  5. 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:

  1. 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.

  2. 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
  3. 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
  4. 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.
  5. 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
  6. Create a git tag for the version:

    • Format: v<version> (e.g., v1.0.7)
    • Use git tag v<version> to create the tag
  7. 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:

  1. Check if FORMAT.md exists in the repository root.
  2. 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.
  3. Review all changed code against the formatting standards.
  4. 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:

  1. Read README.md and any architecture documentation (ARCHITECTURE.md, DESIGN.md, CLAUDE.md).
  2. Identify documented architectural decisions (module boundaries, patterns, conventions).
  3. Review changed code for violations of these patterns.
  4. 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:

  1. Compare code changes to README.md, CHANGELOG.md, and the IN PROGRESS plan file.
  2. Identify any code functionality not reflected in documentation.
  3. Identify any documentation claims not supported by the code.
  4. Identify any features marked as implemented that are not implemented.
  5. 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:

  1. Analyze changed code for common bug patterns.
  2. Look for: null/undefined handling, boundary conditions, race conditions, resource leaks, error handling gaps.
  3. Consider edge cases that may not be handled.
  4. 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:

  1. 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.
  2. Then critically evaluate: validate the reasoning or suggest improvements with rationale.
  3. 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:

  1. Review all comments in changed code (function docs, inline comments).
  2. Assess whether comments add value beyond what code already expresses.
  3. Identify missing comments where complexity warrants explanation.
  4. 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:

  1. A summary of issues found per category
  2. All agent outputs in full
  3. Highlight any critical issues requiring immediate attention
  4. 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:

  1. Display a summary of what was implemented vs what remains in the plan
  2. 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

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