Plan-Driven Development plugin for Claude Code. Manage PLAN.md and NOTES.md for AI-assisted development workflows.

Install

/plugin install pdd@kzmshx

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

Contents

Discovered from source

Skills 2

/pdd:notes

Create a NOTES file capturing discoveries and decisions from the current session.

Usage

/pdd:notes [focus]

Arguments

  • focus (optional): Specific aspect to focus on (e.g., "debugging session", "design decision")

Environment Variables

  • PDD_WORKSPACE_DIR: Base directory for PLAN/NOTES (default: .claude/pdd)
  • PDD_LOCALE: Output language - en or ja (default: en)

Behavior

  1. Get current branch name via git branch --show-current
  2. Generate timestamp via date +%Y%m%d_%H%M%S
  3. Create: {PDD_WORKSPACE_DIR}/{branch}/NOTES_{timestamp}.md

Purpose

NOTES capture what was discovered during implementation that wasn't anticipated in PLAN:

  • Unexpected issues and how they were resolved
  • Technical decisions made during implementation
  • Insights that should be preserved for future sessions
  • Deviations from the original plan and why

Instructions

  1. Review the current conversation for significant discoveries
  2. Extract key findings, decisions, and solutions
  3. Write using the structured format below
  4. Focus on information that would be lost when the conversation ends

Structure

Always start with # NOTES - {brief description}. Choose and adapt sections based on the session's nature:

  • Implementation: Accomplishments, Key Files Modified, Next Steps
  • Debugging: Problem, Root Cause, Solution, Pitfalls
  • Investigation/Research: Findings, Implications, Open Questions
  • Design Decision: Context, Options Considered, Decision, Rationale

Examples

Implementation session:

# NOTES - Add user authentication flow

## Accomplishments
- Implemented JWT-based auth middleware
- Chose bcrypt over argon2 for password hashing (simpler dependency, sufficient for our scale)

## Key Files Modified
- `src/middleware/auth.ts` - JWT verification middleware
- `src/routes/login.ts` - login endpoint

## Next Steps
- [ ] Add refresh token rotation
- [ ] Rate limiting on login endpoint

Debugging session:

# NOTES - Fix intermittent timeout on /api/export

## Problem
- Export endpoint times out on datasets > 10k rows

## Root Cause
- N+1 query in `buildExportRows()` — each row triggered a separate lookup

## Solution
- Batched lookups with `WHERE id IN (...)`, reduced queries from O(n) to O(1)

## Pitfalls
- Initial fix with `Promise.all` hit connection pool limit — sequential batching was needed

Design decision session:

# NOTES - Migration strategy for auth middleware

## Context
- Current middleware stores session tokens in cookies, non-compliant with new policy

## Options Considered
1. Patch existing middleware — fast but fragile
2. Full rewrite with new token store — clean but risky during freeze
3. Adapter layer over existing code — incremental, testable

## Decision
- Option 3: adapter layer

## Rationale
- Allows incremental rollout behind feature flag during merge freeze

Sections can be omitted or combined freely. Keep each section concise and factual.

NOTES are meant to bridge sessions. They should enable resuming work without re-explaining context.

/pdd:plan

Create or continue a PLAN.md for the current branch.

Usage

/pdd:plan [description]

Environment Variables

  • PDD_WORKSPACE_DIR: Base directory for PLAN/NOTES (default: .claude/pdd)
  • PDD_LOCALE: Output language - en or ja (default: en)

Behavior

  1. Get current branch name via git branch --show-current
  2. Resolve path: {PDD_WORKSPACE_DIR}/{branch}/PLAN.md
  3. If PLAN.md exists, read and continue editing
  4. If not, create through discussion with user

Instructions

PLAN.md is created collaboratively through discussion, not by filling a fixed template.

  1. Ask what the user wants to accomplish
  2. Clarify goals, constraints, and approach through conversation
  3. Write PLAN.md reflecting the discussion
  4. Review with user before starting implementation

Structure depends on the task. Choose and adapt sections to fit the work.

Examples

Bug fix:

# PLAN: fix/api-timeout-on-large-export

## Problem
- `/api/export` times out when dataset exceeds 10k rows
- Users see 504 Gateway Timeout, no partial results returned

## Root Cause
- `buildExportRows()` issues one query per row (N+1)
- At 10k rows, total query time exceeds 30s gateway timeout

## Solution
- Batch lookups with `WHERE id IN (...)` — O(n) queries → O(n/500) batches
- Add streaming response so partial results are sent immediately

## Affected Files
| File | Change |
|------|--------|
| `src/export/builder.ts` | Replace per-row query with batched lookup |
| `src/routes/export.ts` | Switch to streaming response |

## Tasks
- [ ] Write failing test: export with 15k rows should complete under 10s
- [ ] Implement batched query in `buildExportRows()`
- [ ] Add streaming response handler
- [ ] Verify no regression on small datasets

## Verification
- [ ] `npm test` passes
- [ ] Manual: export 15k rows completes without timeout
- [ ] Manual: export 100 rows still works as before

Feature:

# PLAN: feat/webhook-retry

## Goal
- Add automatic retry with exponential backoff for failed webhook deliveries
- Retain current behavior for successful deliveries (no retry, no delay)

## Design
- Max 3 retries with backoff: 1min, 5min, 30min
- Store delivery attempts in `webhook_deliveries` table
- Dead letter queue after final failure — surface in admin dashboard

## Design Decisions
- Backoff in application layer, not job queue — keeps retry policy visible and testable
- No circuit breaker for v1 — complexity not justified until we see patterns in failures

## Tasks
- [ ] Add `webhook_deliveries` migration
- [ ] Implement retry logic with backoff calculator
- [ ] Add dead letter query endpoint for admin
- [ ] Integration test: simulate 3 failures then success
- [ ] Integration test: simulate 4 failures → dead letter

## Verification
- [ ] Tests pass
- [ ] Manual: disable test endpoint, trigger webhook, observe 3 retries in logs
- [ ] Manual: confirm dead letter entry appears in admin dashboard

Research / Investigation:

# PLAN: research/search-engine-comparison

## Question
- Should we replace Elasticsearch with OpenSearch or Meilisearch for product search?

## Scope
- Performance: indexing speed, query latency at 1M documents
- Operational: managed hosting options, backup/restore
- Out of scope: full-text search in non-product contexts

## Method
- [ ] Benchmark indexing 1M product documents on each engine
- [ ] Benchmark query latency (simple, filtered, faceted)
- [ ] Compare managed hosting costs at our projected scale
- [ ] Document trade-offs and recommendation

Refactor:

# PLAN: refactor/extract-auth-middleware

## Current State
- Auth logic duplicated across 12 route handlers
- Each handler parses JWT, checks permissions, handles errors slightly differently

## Target State
- Single `authMiddleware(requiredPermissions)` handles all auth concerns
- Route handlers receive verified `AuthContext`, no JWT parsing

## Approach
- Extract common auth logic into middleware
- Migrate routes one-by-one, verifying each with existing tests
- No behavior changes — pure structural refactor

## Tasks
- [ ] Create `authMiddleware` with permission checking
- [ ] Migrate `/api/users` routes (highest test coverage — safest to start)
- [ ] Migrate remaining routes
- [ ] Remove duplicated auth helpers

## Verification
- [ ] All existing tests pass without modification
- [ ] No auth-related logic remains in route handlers

Sections can be omitted, combined, or added freely. The key principle: a plan should contain enough context that a new session can pick up the work without re-investigation.

Verification Section

Always include a Verification section (except for pure research tasks). This defines "done":

  • Concrete and actionable
  • Testable by Claude during implementation
  • Clear definition of "done"

This enables Claude to self-verify and iterate until the work is truly complete.

Do not start implementation until user approves the plan.

Sponsors

Details

Marketplace
kzmshx/claude-plugins
Source
plugins/pdd
Category
Community

More from kzmshx/claude-plugins

All 2