claude-workflow

name

claude-workflow

description

CWF knowledge repository providing plan structure, tasklist format, checkpoint definitions, amendment rules, and validation requirements. Load this skill when: (1) executing CWF commands like /write-plan, /implement-plan, /amend-plan, (2) answering questions about CWF workflow or plan/tasklist format, (3) validating plan or tasklist documents, (4) understanding phase structure or task conventions. This is KNOWLEDGE context, not an action - do NOT confuse with the /write-plan, /implement-plan, /amend-plan, or /explore commands which are user-invoked.

Claude Workflow

Knowledge repository for Claude Workflow (CWF).

Overview

CWF is a plan-driven development workflow using complementary documents that work together to guide feature implementation. All documents are stored in .cwf/{feature-name}/.

Plan Document (.cwf/{feature-name}/{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 (.cwf/{feature-name}/{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

Mockup (.cwf/{feature-name}/{feature-name}-mockup.html) [Optional]:

• Visual reference for UI/frontend features
• Conventions defined in mockup.md

All documents follow the conformance requirements defined below.

---

Conventions

Feature Naming

Feature names MUST:

• Use kebab-case (lowercase with hyphens)
• Be 1-3 words, concise and descriptive
• Contain only lowercase letters, numbers, and hyphens
• Start with a letter

Feature names MUST NOT contain uppercase, underscores, or start/end with hyphens.

Validation pattern: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

Examples: query-command, user-auth, oauth2-flow

Directory Structure

CWF planning documents MUST be stored in .cwf/{feature-name}/:

.cwf/
└── {feature-name}/
    ├── {feature-name}-plan.md       [REQUIRED]
    ├── {feature-name}-tasklist.md   [REQUIRED]
    └── {feature-name}-mockup.html   [OPTIONAL]

The .cwf/ directory is hidden to keep project root clean. Per-feature subdirectories contain related artifacts.

---

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:

  /explore (optional) [Human runs]
         ↓
  Design Summary [In conversation]
         ↓
     /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. /explore Command (Optional)

• Human: Runs /explore command (optional step for iterative design discovery)
• Agent:
  • Explores repo context to inform targeted questions
  • Makes informed guesses based on codebase, confirms with user
  • Proposes 2-3 alternative approaches with trade-offs
  • Incrementally builds and validates design summary in conversation
  • Requires explicit user approval before transition
• Outcome: Complete design context in conversation, ready for /write-plan extraction
• 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
Mockup conventions	references/mockup.md	When and how to create HTML mockups

---

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