Implementation Plans

How we plan, track, and implement features and fixes.

Related: WORKFLOW.md - End-to-end flow from idea to implementation

Folder Structure

website/docs/ai-development/ai-developer/plans/
├── backlog/      # Approved plans waiting for implementation
├── active/       # Currently being worked on (max 1-2 at a time)
└── completed/    # Done - kept for reference

Flow

Idea/Problem → PLAN file in backlog/ → active/ → completed/
                       ↓
              (or INVESTIGATE file first if unclear)

File Types

PLAN-*.md

For work that is ready to implement. The scope is clear, the approach is known.

When to create:

Bug fix with known solution
Feature request with clear requirements
Refactoring with defined scope

Naming Conventions:

Format	Use Case	Example
`PLAN-<short-name>.md`	Standalone plan, no specific order	`PLAN-docker-path-fix.md`
`PLAN-<nnn>-<short-name>.md`	Ordered sequence, indicates execution order	`PLAN-001-configurable-urls.md`

Ordered Plans (PLAN-nnn-*)

When an investigation produces multiple related plans that should be executed in a specific order, use three-digit numbering to indicate the sequence:

PLAN-001-configurable-urls.md      # Must be done first (critical foundation)
PLAN-002-quick-enhancements.md     # Can start after 001
PLAN-003-extended-metadata.md      # Depends on 002
PLAN-004-enhanced-tool-pages.md    # Depends on 003
PLAN-005-interactive-homepage.md   # Depends on 003, 004

Benefits of ordered numbering:

Clear execution sequence at a glance
Dependencies are implicit in the number order
Easy to track progress through a large initiative
Files sort naturally in file explorers

When to use ordered numbering:

Investigation produces 3+ related plans
Plans have sequential dependencies
Work is part of a larger initiative (e.g., website redesign)

When NOT to use ordered numbering:

Standalone bug fix or small feature
Plans can be executed in any order
Single plan from an investigation

Examples:

PLAN-docker-path-fix.md - standalone fix
PLAN-001-configurable-urls.md - first in a sequence
PLAN-005-interactive-homepage.md - fifth in a sequence

INVESTIGATE-*.md

For work that needs research first. The problem exists but the solution is unclear.

When to create:

Complex refactoring where options need evaluation
Bug with unknown root cause
Feature requiring design decisions

Naming: INVESTIGATE-<topic>.md

Examples:

INVESTIGATE-prerequisite-enforcement.md
INVESTIGATE-monitoring-architecture.md

After investigation: Create one or more PLAN files with the chosen approach.

Plan Structure

Every plan has these sections:

1. Header (Required)

# Plan Title

> **IMPLEMENTATION RULES:** Before implementing this plan, read and follow:
> - [WORKFLOW.md](../../WORKFLOW.md) - The implementation process
> - [PLANS.md](../../PLANS.md) - Plan structure and best practices

## Status: Backlog | Active | Blocked | Completed

**Goal**: One sentence describing what this achieves.

**Last Updated**: 2026-01-14

**GitHub Issue**: #42 (optional - if tracking with issues)

The IMPLEMENTATION RULES blockquote ensures Claude Code reads the workflow and plan guidelines before starting work.

2. Dependencies (If applicable)

**Prerequisites**: PLAN-001 must be complete first
**Blocks**: PLAN-003 cannot start until this is done
**Priority**: High | Medium | Low

For ordered plans (PLAN-nnn-*), dependencies are often implicit in the number order. Only add explicit dependency notes when the relationship is non-obvious.

3. Problem Summary (Required)

What's wrong or what's needed. Be specific.

4. Phases with Tasks (Required)

Break work into phases. Each phase has:

Numbered tasks
A validation step at the end (usually user confirmation)

## Phase 1: Setup

### Tasks

- [ ] 1.1 Create the config file
- [ ] 1.2 Add validation rules
- [ ] 1.3 Test with sample data

### Validation

User confirms phase is complete.

---

## Phase 2: Implementation

### Tasks

- [ ] 2.1 Update the install script
- [ ] 2.2 Add to enabled-tools.conf
- [ ] 2.3 Test install/uninstall

### Validation

User confirms install/uninstall works correctly.

5. Acceptance Criteria (Required)

## Acceptance Criteria

- [ ] Feature works in devcontainer
- [ ] Install script runs without errors
- [ ] Uninstall script cleans up properly
- [ ] No shellcheck warnings

6. Implementation Notes (Optional)

Technical details, gotchas, code patterns to follow.

7. Files to Modify (Optional but helpful)

## Files to Modify

- `.devcontainer/additions/install-xyz.sh`
- `.devcontainer.extend/enabled-tools.conf`

Status Values

Status	Meaning	Location
`Backlog`	Approved, waiting to start	`backlog/`
`Active`	Currently being worked on	`active/`
`Blocked`	Waiting on something else	`backlog/` or `active/`
`Completed`	Done	`completed/`

Updating Plans During Implementation

Critical: Plans are living documents. Update them as you work.

When starting a phase:

## Phase 2: Implementation — IN PROGRESS

When completing a task:

- [x] 2.1 Update the template ✓
- [ ] 2.2 Fix the CSS

When a phase is done:

## Phase 2: Implementation — ✅ DONE

When blocked:

## Status: Blocked

**Blocked by**: Waiting for decision on approach

When complete:

Update status: ## Status: Completed
Add completion date: **Completed**: 2026-01-14
Move file: mv website/docs/ai-development/ai-developer/plans/active/PLAN-xyz.md website/docs/ai-development/ai-developer/plans/completed/
(Optional) Close GitHub issue if using issue tracking

Validation

Every phase ends with validation. The simplest form is asking the user to confirm.

Default: User Confirmation

Claude asks: "Phase 1 complete. Does this look good to continue?"

In the plan, this can be written as:

### Validation

User confirms phase is complete.

Optional: Automated Check

When a command can verify the work, include it:

### Validation

```bash
bash .devcontainer/additions/install-xyz.sh --help
# Should show version and usage

User confirms output is correct.

### Key Point

Don't force automated validation when it's impractical. User confirmation is valid and often the best approach.

---

## Plan Templates

### Simple Bug Fix

```markdown
# Fix: [Bug Description]

> **IMPLEMENTATION RULES:** Before implementing this plan, read and follow:
> - [WORKFLOW.md](../../WORKFLOW.md) - The implementation process
> - [PLANS.md](../../PLANS.md) - Plan structure and best practices

## Status: Backlog

**Goal**: [One sentence]

**GitHub Issue**: #XX (optional)

**Last Updated**: YYYY-MM-DD

---

## Problem

[What's broken]

## Solution

[How to fix it]

---

## Phase 1: Fix

### Tasks

- [ ] 1.1 [Specific change]
- [ ] 1.2 [Another change]

### Validation

User confirms fix is correct.

---

## Acceptance Criteria

- [ ] Bug is fixed
- [ ] No regressions
- [ ] Scripts pass shellcheck

Feature Implementation

# Feature: [Feature Name]

> **IMPLEMENTATION RULES:** Before implementing this plan, read and follow:
> - [WORKFLOW.md](../../WORKFLOW.md) - The implementation process
> - [PLANS.md](../../PLANS.md) - Plan structure and best practices

## Status: Backlog

**Goal**: [One sentence]

**GitHub Issue**: #XX (optional)

**Last Updated**: YYYY-MM-DD

---

## Overview

[What this feature does and why]

---

## Phase 1: [Setup/Preparation]

### Tasks

- [ ] 1.1 [Task]
- [ ] 1.2 [Task]

### Validation

User confirms phase is complete.

---

## Phase 2: [Core Implementation]

### Tasks

- [ ] 2.1 [Task]
- [ ] 2.2 [Task]

### Validation

User confirms phase is complete.

---

## Acceptance Criteria

- [ ] [Criterion]
- [ ] Install works
- [ ] Uninstall works
- [ ] Scripts pass shellcheck

---

## Files to Modify

- `.devcontainer/additions/install-xyz.sh`

Investigation

# Investigate: [Topic]

> **IMPLEMENTATION RULES:** Before implementing this plan, read and follow:
> - [WORKFLOW.md](../../WORKFLOW.md) - The implementation process
> - [PLANS.md](../../PLANS.md) - Plan structure and best practices

## Status: Backlog

**Goal**: Determine the best approach for [topic]

**Last Updated**: YYYY-MM-DD

---

## Questions to Answer

1. [Question 1]
2. [Question 2]

---

## Current State

[What exists now]

---

## Options

### Option A: [Name]

**Pros:**
-

**Cons:**
-

### Option B: [Name]

**Pros:**
-

**Cons:**
-

---

## Recommendation

[After investigation, what do we do?]

---

## Next Steps

- [ ] Create PLAN-xyz.md with chosen approach
  - For multiple related plans, use ordered naming: PLAN-001-*, PLAN-002-*, etc.

Working with Claude Code

See WORKFLOW.md for the complete flow from idea to implementation.

Best Practices

One active plan at a time - finish before starting another
Small phases - easier to validate and recover from errors
Specific tasks - "Update line 42 in file.sh" not "Fix the thing"
Runnable validation - commands, not descriptions
Update as you go - the plan is the source of truth
Keep completed plans - they're documentation

Folder Structure​

Flow​

File Types​

PLAN-*.md​

Ordered Plans (PLAN-nnn-*)​

INVESTIGATE-*.md​

Plan Structure​

1. Header (Required)​

2. Dependencies (If applicable)​

3. Problem Summary (Required)​

4. Phases with Tasks (Required)​

5. Acceptance Criteria (Required)​

6. Implementation Notes (Optional)​

7. Files to Modify (Optional but helpful)​

Status Values​

Updating Plans During Implementation​

When starting a phase:​

When completing a task:​

When a phase is done:​

When blocked:​

When complete:​

Validation​

Default: User Confirmation​

Optional: Automated Check​

Feature Implementation​

Investigation​

Working with Claude Code​

Best Practices​