Skip to main content

Plan to Implementation Workflow

How plans become implemented features.

Related:

  • PLANS.md - Plan structure, templates, and best practices
  • CI-CD.md - What to check before merging to main

The Flow​

Note: Claude always asks for confirmation before running git commands (add, commit, push, branch, merge).

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  1. USER: "I want to add feature X" or "Fix problem Y"              │
│                                                                     │
│  2. CLAUDE:                                                         │
│     - Creates PLAN-*.md or INVESTIGATE-*.md in backlog/             │
│     - Asks user to review the plan                                  │
│                                                                     │
│  3. USER: Reviews and edits the plan, then confirms                 │
│                                                                     │
│  4. CLAUDE:                                                         │
│     - Moves plan to active/                                         │
│     - Implements phase by phase                                     │
│     - Runs validation after each phase                              │
│     - Commits after each phase                                      │
│     - Updates plan with progress                                    │
│                                                                     │
│  5. USER: Reviews result                                            │
│                                                                     │
│  6. CLAUDE:                                                         │
│     - Moves plan to completed/                                      │
│     - Final commit                                                  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Step 1: Describe What You Want​

Tell Claude what you want to do:

"I want to add Draw.io extension support"
"Fix the Docker CLI path issue in the devcontainer"
"Add SCRIPT_VER to all install scripts"

Step 2: Claude Creates a Plan​

Claude will:

  1. Create plan file in website/docs/ai-development/ai-developer/plans/backlog/:
    • PLAN-*.md if the solution is clear
    • INVESTIGATE-*.md if research is needed first
  2. Ask you to review the plan

See PLANS.md for plan structure, templates, and what goes in each section.

Step 3: Review the Plan​

Open the plan file and review it:

  • Are the phases in the right order?
  • Are the tasks specific enough?
  • Is anything missing?
  • Are the validation steps correct?

Edit the file if needed.

When satisfied, tell Claude:

"Plan approved, start implementation"

Step 4: Claude Implements​

Claude will:

  1. Move plan to active/:

    mv website/docs/ai-development/ai-developer/plans/backlog/PLAN-xyz.md website/docs/ai-development/ai-developer/plans/active/

  2. Ask about feature branch (recommended):

    Claude will ask:

    "Do you want to work on a feature branch? (recommended)

    This keeps your changes separate from the main code until you're ready. When done, you'll create a Pull Request to merge your changes."

    If yes: Claude creates a branch like feature/update-scripts If no: Claude works directly on the current branch

    See "What is a Feature Branch?" below if you're new to this.

  3. Work phase by phase:

    • Complete tasks in order
    • Ask user to confirm each phase: "Phase 1 complete. Does this look good?"
    • Update the plan file (mark tasks complete)
    • Commit after user confirms
    • Stop if user has concerns

  4. Ask for help if blocked or unclear

Step 5: Review Result​

Check the changes:

  • Does the script work?
  • Does install/uninstall work correctly?
  • Any shellcheck warnings?

If changes needed, tell Claude what to fix.

If good, tell Claude:

"Looks good, complete it"

Step 6: Claude Completes​

Claude will:

  1. Move plan to completed/
  2. Update plan status: ## Status: Completed
  3. Push changes

If working on a feature branch, Claude will also:

  1. Create a Pull Request using gh pr create
  2. Explain next steps:

    "I've created a Pull Request. You can:

    • Review it on GitHub
    • Ask someone to review it
    • Merge it when ready"

Before merging the PR, Claude will ask:

  1. Check version bump:

    "Should we bump the version before merging?

    • Current version: 1.0.3
    • If yes, what should the new version be?"

  2. Documentation: CI auto-updates docs after merge - no manual step needed.

See CI-CD.md for details on what happens after merge.

Version Management (MANDATORY)​

CRITICAL: Before pushing to GitHub or creating a PR, Claude MUST:

  1. Ask the user: "Should we bump the version for this change?"
  2. If yes: Update version.txt with the new version number
  3. Version types:
    • PATCH (1.0.x → 1.0.y): Bug fixes, small improvements
    • MINOR (1.x.0 → 1.y.0): New features, documentation improvements
    • MAJOR (x.0.0 → y.0.0): Breaking changes

Why this matters: Users running dev-update will only see updates if the version number changes. Without a version bump, changes will never reach users.

See RELEASING.md for full release process.

Quick Reference​

Commands to give Claude:​

You sayClaude does
"I want to add X" / "Fix Y"Creates plan, asks for review
"Plan approved"Asks about feature branch, moves to active/, starts implementing
"Yes, use a feature branch"Creates branch, works there
"No, work on current branch"Works on current branch
"Looks good, complete it"Moves to completed/, creates PR if on feature branch
"Stop"Pauses and waits for instructions

Example Session​

YOU: I want to add SCRIPT_VER to all install scripts

CLAUDE: I'll create a plan for that.
        Created website/docs/ai-development/ai-developer/plans/backlog/PLAN-script-version-variable.md

        Please review the plan and let me know if it looks good
        or needs changes.

YOU: [reviews file, makes edits]
     Plan approved, start implementation

CLAUDE: Do you want to work on a feature branch? (recommended)

        This keeps your changes separate from the main code until you're ready.
        When done, you'll create a Pull Request to merge your changes.

YOU: Yes

CLAUDE: Created branch: feature/script-version-variable
        Moving plan to active/...
        Starting Phase 1...

        [works through phases, committing after each]

        Phase 2 complete. Validation passed.
        Continuing to Phase 3...

        All phases complete. Please review the changes.

YOU: Looks good, complete it

CLAUDE: Done! I've:
        - Moved plan to completed/
        - Pushed the feature branch
        - Created Pull Request #12

        Next steps:
        - Review the PR on GitHub
        - Merge it when you're ready
        - Or ask a teammate to review it first

What is a Feature Branch?​

If you're new to git branches, this section explains the concept.

The Problem​

Imagine you're writing a book with others. If everyone edits the same copy at the same time, it gets messy. Someone might overwrite your changes, or you might break something while experimenting.

The Solution: Branches​

A branch is like making a personal copy of the book to work on. You can:

  • Make changes without affecting the original
  • Experiment freely
  • Share your copy when it's ready
main (the original)
  │
  └── feature/add-chapter-5 (your copy)
        │
        └── [you work here safely]

The Workflow​

  1. Create branch - Make your personal copy
  2. Work on it - Make changes, commit as you go
  3. Create Pull Request (PR) - Ask to merge your changes back
  4. Review - Others can look at your changes before merging
  5. Merge - Your changes become part of the original
  • Safe: Your experiments don't break the main code
  • Reviewable: Others can check your work before it's merged
  • Reversible: Easy to undo if something goes wrong
  • Collaborative: Multiple people can work on different features

Commands Claude Uses​

# Create and switch to a new branch
git checkout -b feature/my-feature

# Push the branch to GitHub
git push -u origin feature/my-feature

# Create a Pull Request
gh pr create --title "Add my feature" --body "Description..."

You don't need to memorize these - Claude handles it for you.

Optional: Working with GitHub Issues​

If you're using GitHub issues to track work, tell Claude:

"Work on issue #42"

Claude will:

  1. Read the issue with gh issue view 42
  2. Create a plan based on the issue
  3. Create a branch: issue-42-short-name
  4. Close the issue when complete