gh-tordks-claude-workflow-plugins-cwf/skills/claude-workflow/SKILL.md

name: claude-workflow description: Load for any CWF planning task including: explaining the workflow, answering planning questions, creating plans, amending plans, and implementing features. Contains conventions, phase structure, task formats, validation rules, and templates.

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.