Claude Workflow

Knowledge repository for Claude Workflow (CWF).

Overview

CWF is a plan-driven development workflow using two complementary documents that work together to guide feature implementation:

Plan Document ({feature-name}-plan.md):

• Captures architectural context and design rationale
• Documents WHY decisions were made and WHAT the solution is
• Structure defined in plan-spec.md

Tasklist Document ({feature-name}-tasklist.md):

• Provides step-by-step execution guidance
• Documents WHEN to do tasks and HOW to implement them
• Structure defined in tasklist-spec.md

Both documents follow the conformance requirements defined below.

---

Conformance and Tailoring

All CWF planning documents (plans and tasklists) use RFC 2119 keywords to define requirements.

The specifications in plan-spec.md and tasklist-spec.md use these keywords as described in RFC 2119.

• MUST / REQUIRED / SHALL - Mandatory requirements for all plans
• SHOULD / RECOMMENDED - Strongly recommended; include unless there's good reason not to
• MAY / OPTIONAL - Optional enhancements; include when they add value
• MUST NOT / SHALL NOT - Absolute prohibitions
• SHOULD NOT - Generally inadvisable; avoid unless there's good reason

---

Checkpoints

Checkpoints are end-of-phase validation operations that provide quality control for AI-driven development.

Purpose:

• Validate code quality independent of functional testing
• Ensure AI-generated code meets project standards
• Catch issues early before accumulating technical debt

Checkpoint Types:

• Self-review: Agent reviews implementation against phase deliverable
• Code quality: Linting, formatting, type checking (project-specific tools)
• Code complexity: Complexity analysis (project-specific thresholds)

Human review occurs after checkpoints complete, when "Phase X Complete" is signaled.

Where checkpoints appear:

• Plan: Checkpoint strategy explains WHY these checkpoints and WHAT tools
• Tasklist: Checkpoint checklist specifies WHEN to run and HOW to execute

Key principle: Checkpoints are validation operations performed after phase task completion but before moving to the next phase. They are distinct from functional tests, which validate feature behavior.

---

CWF Workflow

The CWF planning workflow follows this command-driven flow:

  /brainstorm (optional) [Human runs]
         ↓
  Design Summary [Agent writes]
         ↓
     /write-plan [Human runs]
         ↓
   Plan + Tasklist [Agent writes]
         ↓
   /implement-plan [Human runs]
         ↓
  Phase 1 [Agent implements] → Checkpoints [Agent runs] → Review [Human] → ✓ → /clear [Human runs]
         ↓
 Phase 2 [Agent implements] → Checkpoints [Agent runs] → Review [Human] → ✓ → /clear [Human runs]
  [Changes?] → /amend-plan [Human runs] ──┐
         ↓                                │
  Continue development [Agent] ←──────────┘
         ↓
  Feature Complete ✓ [Human confirms]

Stage Breakdown

1. /brainstorm Command (Optional)

• Human: Runs /brainstorm command (optional step for structured exploration)
• Agent:
  • Systematically extracts requirements through guided questions
  • Explores 2-3 alternative approaches with trade-offs
  • Incrementally builds design with validation checkpoints
  • Produces design summary document in docs/brainstorms/
• Outcome: Complete design context ready for /write-plan
• Note: Can be skipped in favor of informal planning discussion or written specification

2. /write-plan Command

• Human: Runs /write-plan command
• Agent: Generates two documents:
  • Plan: Architectural context and WHY/WHAT decisions
  • Tasklist: Step-by-step HOW/WHEN execution guidance
  • Validates structure and consistency between documents

3. Phase-by-Phase Implementation

The implementation follows this repeating cycle:

• Human: Runs /implement-plan command
• Agent:
  • Reads plan for architectural understanding
  • Checks tasklist to identify completed tasks and current phase
  • Works through tasks for current phase sequentially
  • Marks tasks complete as work progresses
  • Executes checkpoints (code quality, complexity checks, etc)
  • Signals phase completion for human review at phase boundary
• Human:
  • Reviews phase results when agent signals completion
  • Runs /clear to start fresh session for next phase
  • Repeats cycle: Runs /implement-plan again for next phase

Note: Conversation history is lost after /clear; only plan, tasklist checkboxes, and committed code persist across cycles.

4. /amend-plan Command (When Needed)

• Human: Discusses amendment and runs /amend-plan when requirements change during development
• Agent:
  • Adds tasks to incomplete phases
  • Creates new phases for additional work
  • Updates plan sections with new context
  • Follows amendment safety rules
• Agent: Continues development with amended plan

5. Feature Completion

• Agent: Completes all phases and signals completion
• Human: Reviews and confirms feature is complete (✓)

Quick Reference

Need to understand...	Read This Reference	Contains
Plan document specification	references/plan-spec.md	Plan structure requirements with RFC 2119 keywords
Tasklist document specification	references/tasklist-spec.md	Tasklist structure requirements with RFC 2119 keywords
Amendment rules and safety	references/amendment.md	Rules for safely modifying plans and tasklists
Argument parsing for commands	references/parsing-arguments.md	Command argument parsing logic and discovery patterns
Feature naming and file structure	references/conventions.md	Feature naming and file structure standards

---

Skill loaded. CWF planning concepts and patterns are now available.