zhongwei/gh-tordks-claude-workflow-plugins-cwf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:02:26 +08:00
commit dc99518b87
13 changed files with 1475 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "cwf",
"description": "Plan-driven development workflow for Claude Code with phase-based implementation",
"version": "0.2.0",
"author": {
"name": "tordks",
"email": "tordks@users.noreply.github.com"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# cwf
Plan-driven development workflow for Claude Code with phase-based implementation

202
commands/amend-plan.md Normal file
View File

@@ -0,0 +1,202 @@
---
description: Update existing plan and tasklist based on conversation
---
# Amend Plan Command
Update an existing plan and tasklist based on conversation context. This command is used when amendments, changes, or extensions to an existing plan have been discussed. Your job is to understand those changes from the conversation and apply them safely.
## Arguments
**Input**: `$ARGUMENTS`
**Expected format**: `/amend-plan {feature-name} [amendment description]`
**Parsing:**
- First token: feature name (must match existing plan)
- Remaining tokens: optional description of changes
- Example: `query-command Add caching to Phase 3`
**If no feature name provided:**
1. List existing plans: `find plans/ -name "*-plan.md" -exec basename {} -plan.md \;`
2. If exactly 1 plan found: use automatically and inform user
3. If multiple plans found: use AskUserQuestion to present list and ask user to select
4. If 0 plans found: inform user and suggest running `/write-plan` first
**Feature name usage:**
`{feature-name}` is a placeholder that gets replaced with the extracted feature name throughout this command.
Example file paths:
- `plans/{feature-name}-plan.md`
- `plans/{feature-name}-tasklist.md`
## Instructions
### 1. Load and Analyze
1. If skill `read-constitution` not loaded, load it
2. If skill `claude-workflow` not loaded, load it
Read the following if not already loaded:
- `references/amendment.md`
Read existing documents:
- `plans/{feature-name}-plan.md`
- `plans/{feature-name}-tasklist.md`
If either missing: inform user and suggest running `/write-plan` or verifying feature name. STOP.
Analyze recent conversation history (last 10-20 messages before this command) to extract:
- Specific changes discussed
- New tasks/phases to add
- Plan sections to modify
- Where insertions should occur
Identify current state from tasklist:
- Which phases complete/in-progress/not-started
- Highest task number in each phase
---
### 2. Propose Amendments Interactively
**STOP and present proposal** to user:
```markdown
## Proposed Amendments to {feature-name} Plan
### Changes to Plan Document (plans/{feature-name}-plan.md)
- [List sections to add/modify with brief preview]
### Changes to Tasklist (plans/{feature-name}-tasklist.md)
- [List tasks to add with IDs and descriptions]
- [OR: New phases with goals]
### Safety Check
Assess amendment risk level:
**Safe amendments (✅):**
- Adding tasks to incomplete phases only
- Creating new phases for future work
- Adding new plan sections (no modifications)
- No changes to completed tasks
**Risky amendments (⚠️ - requires extra care):**
- Modifying incomplete tasks in current phase
- Changing phase structure or dependencies
- Removing tasks or phases
- Significant scope changes
**Blocked amendments (❌ - reject and explain):**
- Modifying or removing completed tasks
- Modifying or removing completed phases
- Changing task IDs of completed work
- Retroactive changes to finished phases
Assessment: [Safe/Risky/Blocked]
Warnings: [List any concerns]
Is this correct? Should I proceed?
```
Wait for confirmation. Use AskUserQuestion if needed to clarify.
**Proposal Refinement:**
Present the proposed amendments to the user. Then:
- IF user accepts: Proceed to Section 3
- IF user rejects: Ask what's missing/wrong/needs changing, revise the amendments, and present revised proposal (loop until accepted or aborted)
- IF user provides feedback: Incorporate the feedback and make new proposal. Ask question if the user intent is unclear (loop until accepted or aborted)
---
### 3. Apply and Validate
After confirmation, apply the accepted changes:
1. Apply each change using the Edit tool
2. Validate structural conformance:
- New sections use same markdown heading levels and structure as existing sections
- New tasks use `- [ ] [PX.Y] Description` format matching existing tasks
- Task IDs are sequential with no gaps (e.g., P3.5 → P3.6 → P3.7)
3. If validation fails: fix and re-validate
---
### 4. Confirm Completion
Present summary:
```markdown
## Amendments Applied ✅
### Updated Files
- plans/{feature-name}-plan.md - [changes]
- plans/{feature-name}-tasklist.md - [changes]
### Summary
- [What was added/modified]
- [New task IDs if applicable]
### Next Steps
- Continue amendment
- Resume implementation
```
## Requirements
- Follow safety rules from amendment.md
- ALWAYS confirm understanding before changes
- Make inline updates, no separate amendment sections
## Example Flow
```text
Loading plan: query-command
- Read plans/query-command-plan.md ✅
- Read plans/query-command-tasklist.md ✅
Analyzing conversation...
You want to: add caching to Phase 3, create Phase 4 for performance testing
Current state:
- Phase 1: ✅ Complete (3/3)
- Phase 2: ✅ Complete (4/4)
- Phase 3: ⏳ In Progress (2/5 complete)
## Proposed Amendments
**Tasklist:**
- Phase 3: Add tasks [P3.6]-[P3.8] for caching
- Phase 4: New phase with 4 tasks for performance testing
**Plan:**
- Add "Caching Strategy" subsection to Architecture section
Safety check: ✅ All amendments target incomplete phases
Proceed? [User confirms]
Applying...
✅ Updated plans/query-command-plan.md (added Caching Strategy section)
✅ Updated plans/query-command-tasklist.md (added P3.6-P3.8, new Phase 4)
Validating amendments...
✓ Plan sections match existing structure and style
✓ Tasklist tasks match existing format
✓ Phase 4 structure matches existing phases
✓ Task IDs sequential (P3.6, P3.7, P3.8, P4.1, P4.2, P4.3, P4.4)
✓ Checkboxes preserved
✓ No completed tasks modified
Done! Resume with `/implement query-command`.
```

60
commands/brainstorm.md Normal file
View File

@@ -0,0 +1,60 @@
---
description: Quick feature exploration before creating plan
---
# Brainstorm Command
Guide conversational exploration of feature requirements and design before formalizing with /write-plan.
## Context
This command is run BEFORE writing planning documents to quickly explore feature requirements and design through natural conversation. The agent first understands the repository context, then asks essential questions to uncover just enough context to create comprehensive planning documents.
## Arguments
**Input**: `$ARGUMENTS`
If arguments are provided, they contain context or initial direction for the brainstorming session. Use this context to inform your questions and exploration.
## Brainstorm workflow
1. If skill `read-constitution` not loaded, load it
2. If skill `claude-workflow` not loaded, load it
Read the following if not already loaded:
- `references/plan-spec.md`
**Gain quick repository understanding:**
- Scan project structure (directories, modules, organization)
- Identify architecture patterns (how things are currently built)
- Note key dependencies and constraints (libraries, APIs, integrations)
- Survey existing features (what's already implemented)
Ask questions one at a time to uncover context for /write-plan. Adapt based on responses. Explore relevant code when discussing components/architecture.
**Essential questions** (adapt as needed):
- What does this feature do? (core functionality)
- Why this approach? (reasoning, alternatives, apply YAGNI)
- What components involved? (create vs modify, integration)
- How should it be built? (strategy, phases, risks, priorities)
- How tested? (strategy, coverage)
- Other context? (dependencies, constraints, performance, security)
**Stop when you have:**
- Clear problem/solution
- Architecture understanding
- Key design decisions and rationale
- Implementation strategy
- Testing approach
**Transition:** When sufficient context gathered, ask: "Ready to run /write-plan?" If yes, confirm they should run `/write-plan [feature-name]`.
**Guidelines:**
- 1-3 question at a time, natural conversation
- Challenge complexity (YAGNI, DRY, orthogonality)
- Adapt to user's preferred depth

209
commands/implement-plan.md Normal file
View File

@@ -0,0 +1,209 @@
---
description: Execute plan phase-by-phase following tasklist
---
# Implement Command
Implement a feature by following the plan and tasklist documents. This command executes an existing plan phase-by-phase, reading the plan for architectural context and the tasklist for sequential execution. Your job is to execute tasks systematically and produce working code. Work proceeds one phase at a time with human review between phases.
## Arguments
**Input**: `$ARGUMENTS`
**Expected format**: `/implement-plan {feature-name} [implementation instructions]`
**Parsing:**
- First token: feature name (must match existing plan)
- Remaining tokens: optional implementation scope or behavior
- Example: `query-command implement phase 1 and 2, then stop`
**If no feature name provided:**
1. List existing plans: `find plans/ -name "*-plan.md" -exec basename {} -plan.md \;`
2. If exactly 1 plan found: use automatically and inform user
3. If multiple plans found: present list (optionally with progress status), use AskUserQuestion to ask user to select
4. If 0 plans found: inform user and suggest running `/write-plan` first
**Feature name usage:**
`{feature-name}` is a placeholder that gets replaced with the extracted feature name throughout this command.
Example file paths:
- `plans/{feature-name}-plan.md`
- `plans/{feature-name}-tasklist.md`
## Instructions
### 1. Load Context
1. If skill `read-constitution` not loaded, load it
2. If skill `claude-workflow` not loaded, load it
---
### 2. Read Planning Documents
Read the following if they are not already loaded:
- `plans/{feature-name}-plan.md` (WHY/WHAT - architectural context)
- `plans/{feature-name}-tasklist.md` (WHEN/HOW - sequential tasks)
---
### 3. Identify Next Work
Find the first incomplete task in the first incomplete phase:
- Scan tasklist for unchecked tasks: `- [ ] [PX.Y] Task description`
- Identify current phase and task number
- If all tasks complete: inform user feature is complete
---
### 4. Execute Tasks
For each task in the current phase:
1. **Read** the task description from tasklist
2. **Implement** the task following plan guidance
3. **Test** the task according to project standards
4. **Mark complete** in `plans/{feature-name}-tasklist.md`:
- Change `- [ ] [PX.Y]` to `- [x] [PX.Y]`
Repeat until all tasks in current phase are complete.
---
### 5. Run Phase Checkpoints
After all phase tasks are marked complete:
1. Execute checkpoints sequentially (defined in tasklist)
2. Mark each checkpoint complete as it passes
3. If checkpoint fails:
- Minor issues (linting, formatting, types): fix and retry until passes or stuck
- Major issues (architectural issues, complex problems): stop, describe to user and ask user for direction.
- If stuck: ask user for guidance
4. Continue until all checkpoints pass
---
### 6. Complete Phase and Stop
When all checkpoints pass:
1. Output "Phase X Complete ✅" summary
2. Summarize what was accomplished
3. Suggest commit message if appropriate
4. **STOP for human review** - do NOT proceed to next phase
**Between phases:** Human reviews work, optionally runs `/clear` and if so continues with a new call to `/implement-plan {feature-name}` to resume.
## Example Workflow
```text
# Starting fresh
Reading plans for feature: query-command
- Plan: plans/query-command-plan.md
- Tasklist: plans/query-command-tasklist.md
Progress check: No tasks completed yet. Starting from Phase 1.
# Executing tasks
Working on [P1.1]: Set up basic module structure
[implements the task]
✓ Marked [P1.1] as complete
Working on [P1.2]: Create core data models
[implements the task]
✓ Marked [P1.2] as complete
# Phase completion
All Phase 1 tasks complete. Executing checkpoints...
Checkpoint: Self-review implementation against phase deliverable
✓ Marked checkpoint complete
Checkpoint: Code quality - ruff check src/
✓ Passed. Marked checkpoint complete
Checkpoint: Code complexity - radon cc src/
✓ Passed. Marked checkpoint complete
Phase 1 Complete! ✅
Summary of changes:
✅ Created directory structure for modular architecture
✅ Implemented core data models with Pydantic validation
✅ Added type hints and proper __init__.py exports
All checkpoints passed. Foundation layer complete following constitution principles.
Suggested commit:
feat: establish foundational architecture
Enables modular development with core models, strict type validation,
and clear module boundaries.
Stopping for review. Please approve before proceeding to Phase 2.
```
If resuming mid-feature:
```text
Progress check:
✓ Phase 1: Complete (2/2 tasks)
✓ Phase 2: Complete (4/4 tasks)
→ Phase 3: In progress (1/3 tasks)
Resuming from Phase 3, Task [P3.2]...
```
## When Tasks Are Unclear
Assess task clarity using these criteria:
**Clear (✅ - proceed with implementation):**
- Task goal is explicit
- Acceptance criteria defined or obvious
- Required files/components identified
- Approach is straightforward or documented in plan
**Minor ambiguity (⚠️ - make reasonable assumption):**
- Task goal is clear but approach has 2-3 valid options
- Some details missing but not critical to core functionality
- Can infer intent from context and plan
- Document assumption in code comments
**Major ambiguity (❌ - stop and ask):**
- Task goal is vague or has multiple interpretations
- Missing critical information (which component, what data structure, etc.)
- Approach unclear and not documented in plan
- Decision affects architecture or future phases
**Process:**
1. Read task description carefully
2. Check relevant plan sections for context
3. Assess clarity level using criteria above
4. If Major ambiguity: Use AskUserQuestion with task ID, what's unclear, which plan sections checked, and recommended approach
5. If Minor ambiguity: Proceed with documented assumption
6. If Clear: Proceed with implementation
## When Issues Arise
- Document the issue clearly
- Use AskUserQuestion for multiple valid approaches or critical decisions
- Continue with reasonable assumptions if minor
- Stop and ask if significant or affects architecture
## Code Quality
- Keep codebase runnable throughout
- Run tests after implementing functionality
- Follow constitution and project principles

7
commands/read-constitution.md Normal file
View File

@@ -0,0 +1,7 @@
---
description: Load coding principles from constitution
---
1. Use the Skill tool to load: `read-constitution`
2. After loading the constitution, acknowledge that the content has been read and understood.

157
commands/write-plan.md Normal file
View File

@@ -0,0 +1,157 @@
---
description: Create plan and tasklist from planning discussion
---
# Plan Command
Formalize the planning discussion from plan mode into structured documentation. This command is run AFTER iterating with Claude in plan mode. The user has already discussed and refined the approach. Your job is to capture and formalize what was discussed.
Assume the engineer using the plan has zero context for the codebase. Document everything they need: which files to touch, code/testing/docs to check, how to test. Assume they are skilled but know little about the toolset or problem domain.
## Arguments
**Input**: `$ARGUMENTS`
**Expected format**: `/write-plan {feature-name} [planning context]`
**Parsing:**
- First token: feature name
- Remaining tokens: optional planning guidance or focus areas
- Example: `user-auth focus on OAuth2 and session management`
**Feature name requirements:**
- Format: kebab-case (lowercase with hyphens)
- Length: 1-3 words, concise and descriptive
- Characters: lowercase letters, numbers, hyphens only
- Examples: `query-command`, `user-auth`, `auth`, `export`
- Avoid: special characters, uppercase, underscores
**If no feature name provided:**
- Analyze conversation to suggest an appropriate feature name based on discussion
- Present suggestion: "Based on our discussion, I suggest the feature name: '{suggested-name}'"
- Ask user to confirm before creating files
**Feature name usage:**
`{feature-name}` is a placeholder that gets replaced with the extracted feature name throughout this command.
Example file paths:
- `plans/{feature-name}-plan.md`
- `plans/{feature-name}-tasklist.md`
## Instructions
### 1. Extract Planning Context
1. If skill `read-constitution` not loaded, load it
2. If skill `claude-workflow` not loaded, load it
Read the following if not already loaded:
- `references/plan-spec.md`
- `references/tasklist-spec.md`
**Context Extraction:**
Analyze the conversation to extract:
- Requirements and scope (IN/OUT)
- Design decisions with rationale (WHY)
- Alternatives considered and rejected
- Technical constraints and dependencies
- File and component structure
Review as much of the conversation as necessary to capture all planning context. Focus particularly on recent messages and any structured outputs (e.g., /brainstorm results, design summaries, input arguments to this command).
**Complexity Assessment:**
Assess feature complexity (Simple/Medium/Complex) using these criteria:
**Simple:**
- 1-2 files affected
- Single component or module
- <5 tasks total
- Minimal external dependencies
- Focus on MUST requirements from specs
**Medium:**
- 3-5 files affected
- 2-3 components involved
- 5-15 tasks total
- Some cross-component integration
- Include MUST + SHOULD requirements
**Complex:**
- 6+ files affected
- 4+ components involved
- 15+ tasks total
- Significant architectural changes or cross-system integration
- Include MUST + SHOULD + MAY requirements
---
### 2. Create Planning Documents
Create `plans/{feature-name}-plan.md`:
- Follow plan-spec.md structure, tailoring depth to feature complexity
- Use extracted context from Section 1
Create `plans/{feature-name}-tasklist.md`:
- Follow tasklist-spec.md structure, tailoring depth to feature complexity
- Break into phases aligned with plan's Implementation Strategy
- Include checkpoints per SKILL.md guidance
- Stay faithful to discussion, use clear language
---
### 3. Validate Documents
**Validate plan**:
- [ ] Plan validated against all MUST/SHOULD requirements in plan-spec.md
- [ ] If validation fails: revise plan and re-validate until all requirements pass
**Validate tasklist**:
- [ ] Tasklist validated against all MUST/SHOULD requirements in tasklist-spec.md
- [ ] If validation fails: revise tasklist and re-validate until all requirements pass
**Validate coherence** between documents:
- [ ] Tasklist execution follows plan's Implementation Strategy pattern
- [ ] Tasklist execution follows plan's Testing approach
- [ ] Files marked [CREATE]/[MODIFY] in plan appear as tasks in tasklist
- [ ] Consistent terminology between documentsss
- [ ] Tasks reference only files/components defined in plan
- [ ] If coherence fails: revise either document and re-validate until all checks pass
---
### 4. Finalization
Confirm both files exist and are valid, then present summary:
```text
Planning documents created successfully! ✅
Created:
- plans/{feature-name}-plan.md
- plans/{feature-name}-tasklist.md
Implementation Structure:
- {N} phases defined
- {M} total tasks
Next Steps:
Run `/implement-plan {feature-name}` to begin phase-by-phase implementation.
```
Done. Wait for user to run `/implement-plan {feature-name}`.

81
plugin.lock.json Normal file
View File

@@ -0,0 +1,81 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:tordks/claude-workflow:plugins/cwf",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "da5099e66c7d5aa1bb9c4c923698e1183d962461",
"treeHash": "3bf522a086e49bd6978b349115b4179778ae23d05b155eff65adc30675593d3f",
"generatedAt": "2025-11-28T10:28:43.201430Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "cwf",
"description": "Plan-driven development workflow for Claude Code with phase-based implementation",
"version": "0.2.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "d7d98acc779809cf728d6fa9724c761aee365cc8e36754b374b7f888aec54b0b"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "cd3343fafb4ae9891cf135822cd9d6d8c73229936ec740555c6d55b5032e47af"
},
{
"path": "commands/implement-plan.md",
"sha256": "d245cdd34736d698cba2dd6512d9812c22457d63a60af1701ad1aeee3be047b3"
},
{
"path": "commands/read-constitution.md",
"sha256": "2488be37a6b794912bf9f460db8877c3cd1db4cf7d5712de24439d4314818cdc"
},
{
"path": "commands/write-plan.md",
"sha256": "c784f4c4a8f9d9fc3779e27b704990599b9712ab707541dec1d7c0ca7e513739"
},
{
"path": "commands/amend-plan.md",
"sha256": "f1b4cbd42d94bf7f51578acb5859c763bab25c84af1c62e4c676aa1ea0ccba2e"
},
{
"path": "commands/brainstorm.md",
"sha256": "4430b4b2525f6d6e6091631b26389b74e263a638916923bf8e98e1cde841a886"
},
{
"path": "skills/read-constitution/SKILL.md",
"sha256": "241bdb15784c7c195acb6b1ae6826bddad59665e11d08d93b0e3ed6a067da64d"
},
{
"path": "skills/claude-workflow/SKILL.md",
"sha256": "29b4babf208ee8bb36bdd5f37599d249b85a681fb75f299cd5aa9fbefc32d083"
},
{
"path": "skills/claude-workflow/references/plan-spec.md",
"sha256": "bd2bba502dcca652895fdd642671cd133ab5169d4cfb4e68feb091f9897814f6"
},
{
"path": "skills/claude-workflow/references/tasklist-spec.md",
"sha256": "f5979187d1e35c8dfca55f619581387633c3816386567ba2f44f0651948c0daf"
},
{
"path": "skills/claude-workflow/references/amendment.md",
"sha256": "9a63ced186482cbea665aa1f69c3e6191af1bc6c4079fc125e71b1402b8c6ae3"
}
],
"dirSha256": "3bf522a086e49bd6978b349115b4179778ae23d05b155eff65adc30675593d3f"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

163
skills/claude-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,163 @@
---
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:
```text
/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.

78
skills/claude-workflow/references/amendment.md Normal file
View File

@@ -0,0 +1,78 @@
# Amendment Reference
Safety rules for modifying CWF plans and tasklists during implementation.
## Core Principle
**Completed work is immutable.** Tasks marked `[x]` represent implemented code and form a trusted implementation history. Changing completed work breaks trust in the plan as source of truth and creates confusion about what was actually built. This immutability enables reliable progress tracking, troubleshooting, and context preservation across sessions.
## Amendment Operations
| Operation | Allowed? | Rules | Example |
|-----------|----------|-------|---------|
| **Add tasks to incomplete phase** | ✅ Yes | Phase must have at least one `[ ]` task. Use next sequential ID. | Add `[P2.3]`, `[P2.4]` to Phase 2 (has incomplete tasks) |
| **Add new phase** | ✅ Yes | Use next phase number. Include Goal, Deliverable, Tasks, Checkpoint. All tasks start `[ ]`. | Create Phase 4 after Phase 3 |
| **Modify incomplete task description** | ✅ Yes | Only `[ ]` tasks. Preserve ID and checkbox, update description only. | Change `[ ] [P3.2] Add tests` → `[ ] [P3.2] Add unit tests with 90% coverage` |
| **Update plan sections** | ✅ Yes | Add subsections, clarify decisions, document new constraints. | Add "Caching Strategy" subsection to Technical Approach |
| **Modify completed task** | ❌ No | Code already built. Changing description misrepresents implementation. | Use new task/phase to modify implementation instead |
| **Add task to completed phase** | ❌ No | All tasks `[x]` means phase done. Adding creates inconsistency. | Create new phase for additional work |
| **Change task ID** | ❌ No | IDs are stable references in commits/discussions. Changing breaks references. | Never renumber task IDs |
## Allowed Operation Patterns
### Add Tasks to Incomplete Phase
```markdown
## Phase 2: Ranking (IN PROGRESS)
- [x] [P2.1] Implement TF-IDF scoring
- [x] [P2.2] Add document ranking
- [ ] [P2.3] Add caching layer ← NEW (sequential ID)
- [ ] [P2.4] Write caching tests ← NEW
```
### Add New Phase
```markdown
## Phase 4: Caching Optimization
**Goal:** Improve query performance with caching
**Deliverable:** LRU cache with 1000 entry limit
**Tasks:**
- [ ] [P4.1] Create cache.py
- [ ] [P4.2] Integrate with QueryRanker
- [ ] [P4.3] Add cache tests
**Phase 4 Checkpoint:** Cache operational, performance improved
```
### Modify Incomplete Task
```markdown
- [ ] [P2.3] Write tests
- [ ] [P2.3] Write unit tests in test_ranker.py ← Description updated, ID preserved
```
### Update Plan Section
```markdown
## Technical Approach
### Caching Strategy ← NEW SUBSECTION
- LRU cache, 1000 entry limit
- Cache key: query hash
- Invalidate on index update
```
## Before Amending
**Verify:**
- [ ] Task/phase to modify is incomplete (has `[ ]` tasks)
- [ ] Not changing any task IDs
- [ ] Not modifying completed tasks `[x]`
- [ ] New tasks use sequential IDs
**When to amend:** Requirements change, new constraints discovered, additional work needed in incomplete phases.
**When NOT to amend:** Never modify completed work—create new phases instead.

321
skills/claude-workflow/references/plan-spec.md Normal file
View File

@@ -0,0 +1,321 @@
# Plan Document Specification
Specification for creating conformant plan documents in the CWF workflow.
---
## What is a Plan Document?
Plan documents capture **architectural context and design rationale**. They preserve WHY decisions were made and WHAT the solution is, enabling implementation across sessions after context has been cleared.
**Plan = WHY/WHAT** | Tasklist = WHEN/HOW
---
## Conformance
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
> **Note:** See `SKILL.md` for conformance levels (1-3) tailoring documentation depth.
---
## Core Plan Sections
Plan documents MUST include three core sections: Overview, Solution Design, and Implementation Strategy.
### Section 1: Overview
Provides high-level summary of problem and solution.
**MUST include:**
- Problem statement (current pain point or gap)
- Feature purpose (solution being built)
- Scope (What is IN/OUT of scope)
**SHOULD include:**
- Success criteria (quantifiable completion validation)
**Example (Informative):**
```markdown
## Overview
### Problem
Users currently search documentation by manually scanning files or using basic text search. This is slow (10+ minutes per search) and misses relevant documents that use different terminology. Support tickets show 40% of questions are about "how to find X in the docs."
### Purpose
Add keyword-based document search with relevance ranking. Users enter search terms and receive ranked results within 1 second, improving discoverability and reducing support load.
### Scope
**IN scope:**
- Keyword search with boolean AND/OR operators
- TF-IDF relevance ranking
- Result filtering by document type
- Search result caching
**OUT of scope:**
- Natural language queries ("find me information about...")
- Semantic/embedding-based search
- Advanced operators (NEAR, wildcards, regex)
### Success Criteria
- Users can search by keywords and receive ranked results
- Search completes in <100ms for 10,000 documents
- Results include documents even with terminology variations
- Test coverage >80% for core search logic
- Zero regressions in existing functionality
```
---
### Section 2: Solution Design
Documents the complete solution architecture and technical approach.
#### 2.1 System Architecture
**MUST include:**
- Component overview (logical pieces and their responsibilities)
- Project structure (file tree with operation markers)
**SHOULD include:**
- Component relationships (dependencies and communication patterns)
- Relationship to existing codebase (where feature fits, what it extends/uses)
**File Tree Format:**
File trees MUST use operation markers:
- `[CREATE]` for new files
- `[MODIFY]` for modified files
- `[REMOVE]` for removed files
- No marker for existing unchanged files
**Example (Informative):**
````markdown
### System Architecture
**Core Components:**
- **QueryParser:** Parses user search strings into structured queries (operators, quoted phrases)
- **DocumentIndexer:** Builds and maintains TF-IDF index from document corpus
- **QueryRanker:** Ranks documents against query using cosine similarity
- **SearchCache:** LRU cache for frequent queries
- **SearchAPI:** HTTP endpoint exposing search functionality
**Project Structure:**
```
src/
├── search/
│ ├── __init__.py [CREATE]
│ ├── parser.py [CREATE]
│ ├── indexer.py [CREATE]
│ ├── ranker.py [CREATE]
│ └── cache.py [CREATE]
├── api/
│ └── search.py [CREATE]
├── models/
│ └── document.py [MODIFY]
└── tests/
└── search/
├── test_parser.py [CREATE]
└── test_ranker.py [CREATE]
```
**Component Relationships:**
- SearchAPI depends on QueryParser, SearchCache
- QueryRanker depends on DocumentIndexer
- SearchCache depends on QueryRanker
- All components use shared Document model
**Relationship to Existing Codebase:**
- Architectural layer: Service layer (alongside existing `src/api/` endpoints)
- Domain: Search functionality (new domain area)
- Extends: `BaseAPIHandler` pattern used throughout repository
- Uses: Existing `AuthMiddleware` for authentication
- Uses: Application `CacheManager` for result caching
- Follows: Repository's service-oriented architecture and dependency injection patterns
````
---
#### 2.2 Design Rationale
Documents reasoning behind structural and technical choices.
**MUST include:**
- Rationale for key design choices
**SHOULD include:**
- Alternatives considered and why not chosen
- Trade-offs accepted
**MAY include:**
- Constraints influencing decisions
- Principles or patterns applied
**Tip (Informative):** Format flexibly - inline rationale, comparison tables, or structured decision records all work. Focus on capturing WHY, not following a template.
**Example (Informative):**
```markdown
### Design Rationale
**Use TF-IDF with cosine similarity for ranking**
Well-understood algorithm with predictable behavior. No training data or ML infrastructure required.
Alternatives considered:
- BM25: Marginal improvement for our corpus size, added complexity not justified
- Neural/embedding-based: Requires GPU, training data, model management - overkill for current needs
Trade-offs accepted:
- Pro: Fast to implement, predictable results, no infrastructure dependencies
- Con: Doesn't understand semantic similarity, sensitive to exact keyword matches
```
---
#### 2.3 Technical Specification
Describes runtime behavior and operational requirements.
**MUST include:**
- Dependencies (libraries, external systems)
- Runtime behavior (algorithms, execution flow, state management)
**MAY include:**
- Error handling (failure detection and recovery)
- Configuration needs (runtime or deployment settings)
**Example (Informative):**
````markdown
### Technical Specification
**Dependencies:**
Required libraries (new):
- scikit-learn 1.3+ (TF-IDF vectorization, cosine similarity)
- nltk 3.8+ (text preprocessing, stopword removal)
Required systems:
- PostgreSQL (stores `documents` table)
- Redis (event stream for `document_updated` events)
- InfluxDB (search metrics and monitoring)
Existing (from project):
- FastAPI 0.100+ (API framework)
- SQLAlchemy 2.0+ (database ORM)
- pytest 7.4+ (testing framework)
**Runtime Behavior:**
1. Parse query → structured query (operators, phrases)
2. Check cache (LRU, 1000 entries)
3. On cache miss: vectorize query, compute cosine similarity, rank results
4. Return paginated results (25 per page)
**Error Handling:**
Invalid Input:
- Empty query → 400 "Query cannot be empty"
- Invalid operators → 400 "Invalid syntax: [specific error]"
- Query too long (>500 chars) → 400 "Query exceeds maximum length"
Runtime Errors:
- Index not ready → 503 "Search index is building, retry in [X] seconds"
- Timeout (>5s) → 408 "Query timeout, try simplifying search terms"
- No results found → 200 with empty list (not an error)
System Errors:
- Database unavailable → 500, log error, alert on-call
- Index corruption → Rebuild from database, log incident
**Configuration:**
```python
SEARCH_INDEX_PATH = "/data/search-index.pkl"
SEARCH_CACHE_SIZE = 1000
SEARCH_TIMEOUT_MS = 5000
```
````
---
### Section 3: Implementation Strategy
Describes high-level approach guiding phase and task structure.
**MUST include:**
- Development approach (incremental, outside-in, vertical slice, bottom-up, etc.)
**SHOULD include:**
- Testing approach (test-driven, integration-focused, comprehensive, etc.)
- Risk mitigation strategy (tackle unknowns first, safe increments, prototype early, etc.)
- Checkpoint strategy (quality and validation operations at phase boundaries)
The strategy SHOULD explain WHY the tasklist is structured as it is.
**MUST NOT include:**
- Step-by-step execution instructions or task checklists
**Example (Informative):**
```markdown
## Implementation Strategy
### Development Approach
**Incremental with Safe Checkpoints**
Build bottom-up with validation at each layer:
1. **Foundation First:** Core search components (indexer, ranker) before API
2. **Runnable Increments:** Each phase produces working, testable code
3. **Early Validation:** Algorithm performance validated early before building around it
### Testing Approach
Integration-focused with targeted unit tests:
- Unit tests for complex logic (parsing, scoring)
- Integration tests for component interactions
- E2E tests for critical user flows
### Checkpoint Strategy
Each phase ends with mandatory validation before proceeding:
- Self-review: Agent reviews implementation against phase deliverable
- Code quality: Linting and formatting with ruff
- Code complexity: Complexity check with Radon
These checkpoints ensure AI-generated code meets project standards before continuing to next phase.
```
**Note (Informative):** Checkpoint types are project-specific. Use only tools your project already has. If the project doesn't use linting or complexity analysis, omit those checkpoints.
---
## Context Independence
Plans MUST be self-contained. Implementation may occur in fresh sessions after context has been cleared. All architectural decisions and rationale must be in the plan document.
---
## Validation
Plans are conformant when they:
- Include all three core sections with required content
- Contain all three Solution Design subsections
- Use file tree markers correctly
- Document WHY for design decisions
- Are self-contained (no assumed conversation context)
- Contain no step-by-step execution instructions

162
skills/claude-workflow/references/tasklist-spec.md Normal file
View File

@@ -0,0 +1,162 @@
# Tasklist Document Specification
Specification for creating conformant tasklist documents in CWF.
---
## What is a Tasklist Document?
Tasklist documents provide **step-by-step execution guidance**. They break features into phases and concrete, actionable tasks that implementers execute sequentially.
Plan = WHY/WHAT | **Tasklist = WHEN/HOW**
---
## Conformance
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
> **Note:** See `SKILL.md` for conformance levels (1-3) tailoring documentation depth.
---
## Task Syntax
Every task in the tasklist MUST follow this markdown format:
```markdown
- [ ] [PX.Y] Task description with file/component specifics
```
**Task ID Format:** `[PX.Y]` where P = "Phase", X = phase number, Y = task number within phase
**Requirements:**
- Tasks MUST use checkboxes: `- [ ]` for incomplete, `- [x]` for completed
- Task numbering MUST start at 1 within each phase
- Numbering MUST be sequential within phases (no gaps)
- Task IDs MUST NOT be reused or skipped
- Tasks MUST NOT use markdown headings (`###`)
- Descriptions MUST specify the file or component being modified
- Tasks MAY provide task-critical information in bulletpoints
**Example (Informative):**
```markdown
- [x] [P1.1] Create query/ directory and __init__.py
- [x] [P1.2] Create QueryModel class with Pydantic in models.py
- [ ] [P1.3] Add validation to QueryModel (required fields, type checks)
- [ ] [P1.4] Write unit tests for QueryModel validation in test_models.py
```
---
## Phase Structure
Every phase MUST follow this standard structure:
```markdown
## Phase X: Descriptive Name
**Goal:** One-sentence description of what this phase accomplishes
**Deliverable:** Concrete outcome (e.g., "Working data models with validation passing tests")
**Tasks:**
- [ ] [PX.1] Specific atomic action - file/component detail
- [ ] [PX.2] Another specific action with clear scope
- [ ] [PX.3] Write tests for implemented functionality
- [ ] [PX.4] Run tests: pytest tests/module/
**Checkpoints:**
- [ ] Code quality: Run `ruff check src/`
- [ ] Code complexity: Run `ruff check src/ --select C901`
- [ ] Review: Self review implementation and verify phase deliverable achieved
**Phase X Complete:** Brief description of system state after phase completion
```
---
## Checkpoint Requirements
Checkpoints are end-of-phase validation operations performed after all tasks in a phase are complete.
**Requirements:**
- Checkpoints MUST use checkbox format: `- [ ] Checkpoint description`
- Additional checkpoints SHOULD be project-specific validation or quality operations
- Checkpoints MUST NOT duplicate functional test tasks (tests belong in Tasks section)
- Checkpoint commands SHOULD be concrete and executable (e.g., `ruff check src/`)
**Common Checkpoint Types:**
- **Self-review:** Agent reviews implementation against deliverable
- **Code quality:** Linting, formatting, type checking (e.g., ruff, black, mypy)
- **Code complexity:** Complexity analysis (e.g., radon cc)
**Note (Informative):** Use only tools your project already has. Checkpoints provide quality control for AI-driven development.
---
## Task Granularity Guidelines
Tasks SHOULD meet these quality criteria:
- **Time:** 5-20 minutes to complete
- **Atomic:** Completable in one go without interruption (single logical change)
- **Testable:** Clear done criteria (observable output or verifiable behavior)
- **File-specific:** Reference concrete files or components
**Example (Informative):**
```markdown
- [P1.1] Create query/ directory and __init__.py
- [P1.2] Create QueryModel class with Pydantic in models.py
- [P1.3] Add field validation to QueryModel (required fields, type checks)
- [P1.4] Write unit tests for QueryModel validation in test_models.py
```
---
## Task Ordering Principles
Tasks that depend on others MUST be ordered after their dependencies.
**Example (Informative):**
```markdown
- [ ] [P2.1] Create ranker.py with RankerClass stub
- [ ] [P2.2] Implement TF-IDF scoring in RankerClass.score()
- [ ] [P2.3] Add document ranking in RankerClass.rank()
- [ ] [P2.4] Write unit tests for TF-IDF scoring in test_ranker.py
- [ ] [P2.5] Write unit tests for document ranking in test_ranker.py
- [ ] [P2.6] Verify all tests pass: pytest tests/query/test_ranker.py
```
---
## Phase Complete Statement
Every phase MUST end with a "Phase X Complete" statement describing system state after phase completion.
The statement SHOULD be 1-3 sentences describing what capabilities now exist, what's ready for the next phase, and what validation has been completed.
**Example (Informative):**
- "Core data models validated, ready for parser implementation"
- "Query parser complete with DSL support, validated against test cases"
- "End-to-end query flow working with TF-IDF ranking, ready for optimization"
---
## Validation
Tasklists are conformant when they:
- Include required elements in every phase (Goal, Deliverable, Tasks, Checkpoints, Phase Complete)
- Use correct task ID format `[PX.Y]` with checkboxes
- Specify concrete files/components in task descriptions
- Order tasks after their dependencies
- Use checkpoints for quality/validation (not functional tests)
- Contain no architectural rationale or design alternatives (belongs in plan)

17
skills/read-constitution/SKILL.md Normal file
View File

@@ -0,0 +1,17 @@
---
name: read-constitution
description: This skill should be used to load the constitution files located in .constitution
---
## Instructions
Read each file in the `.constitution` directory using the Read tool:
1. Use Glob tool to find all constitution files:
```yaml
pattern: "**/.constitution/**/*"
```
2a. If no files are found, then we don't need to read any files.
2b. If a .constitution folder exists and there are any files in it, use the Read tool to read each constitution file found.