Lightweight execution for small, well-defined changes. Bypasses the full CPM pipeline — accept a description, assess scope, confirm, execute, and produce a completion record. Use for changes that don't warrant discover/brief/spec/epics ceremony. Triggers on "/cpm:quick".
Execute small, well-defined changes with minimal ceremony. Accept a description, assess whether it's genuinely small, confirm the plan with the user, do the work, and write a completion record for traceability.
This is the lightweight alternative to the full pipeline (discover → brief → spec → epics → do). Use it when the change is clear, the scope is small, and the overhead of structured planning would exceed the value it provides.
Parse $ARGUMENTS to determine the change description:
$ARGUMENTS contains a description (e.g. /cpm:quick add a --verbose flag to the deploy script), use that as the change description.$ARGUMENTS is a file path, read the file and use its contents as the change description.The change description is the seed for everything that follows — scope assessment, acceptance criteria, and execution all derive from it.
State tracking: Before starting Step 1, create the progress file (see State Management below). Each step below ends with a mandatory progress file update — do not skip it. After saving the completion record, delete the file.
HARD RULE — PROGRESS FILE UPDATE: After completing EVERY step, you MUST call the Write tool on
docs/plans/.cpm-progress-{session_id}.mdBEFORE doing anything else. This is not optional. This is not deferrable. This has the same priority as saving a file after editing it. A step is NOT done until the progress file reflects it. Historically this step gets silently dropped when momentum is high — that is a bug, not an optimisation. If compaction fires and this file is stale, the user loses all session context with no recovery path.
Before Step 1, check the project library for reference documents:
docs/library/*.md. If no files found or directory doesn't exist, skip silently and proceed to Step 1.--- delimiters, typically the first ~10 lines). Read each file individually — do not use Bash loops with shell variables for this. Filter to documents whose scope array includes quick or all.Graceful degradation: If any library document has malformed or missing front-matter, fall back to using the filename as context. Never block execution due to a malformed library document.
Compaction resilience: Include library scan results (files found, scope matches) in the progress file so post-compaction continuation doesn't re-scan.
After the Library Check and before Step 1, discover the project's test runner command. This command is used during Step 4 verification to run tests against acceptance criteria.
Discovery priority:
quick (found during Library Check) for testing instructions. Look for explicit test commands, framework references, or testing conventions. If found, use the specified command.composer.json — check scripts.test (e.g. composer test, ./vendor/bin/pest, ./vendor/bin/phpunit)package.json — check scripts.test (e.g. npm test, npx jest)Makefile — check for a test target (e.g. make test)pyproject.toml or pytest.ini — check for pytest configuration (e.g. pytest)Cargo.toml — check for Rust project (e.g. cargo test)Cache the result: Store the discovered test command in the progress file as **Test command**: {command} or **Test command**: none if the user declines or no runner is found. This persists across the entire session — do not re-discover between steps.
Graceful degradation: If no test runner is discoverable and the user chooses not to provide one, set **Test command**: none. Step 4 verification will fall back to self-assessment only.
Read the change description and classify it as a fix or a change:
Tell the user which path you're taking in one line:
If the user disagrees with the classification, switch immediately. The heuristic is simple by design — the user corrects it when it's wrong.
When the input is classified as a fix, investigate the root cause before assessing scope or proposing changes. This is the step that /cpm:consult does naturally through conversation — /cpm:quick must replicate it explicitly.
**Symptom**: {what the user reported}
**Investigation**: {what was explored, what was found}
**Root cause**: {what is broken and why}
**Confidence**: {High/Medium/Low}
Options:
If the user says "partially right" or "wrong", incorporate their feedback and re-investigate. Iterate until the diagnosis is confirmed. Only then proceed to Step 1b.
Update progress file now — write the full .cpm-progress-{session_id}.md with Step 1a summary (diagnosis, confidence, user confirmation) before continuing.
Explore the codebase to understand what the change involves, then assess whether it's appropriate for quick execution. When preceded by Step 1a (fix path), the diagnosis provides the foundation — scope assessment now evaluates the fix, not the original symptom.
Explore: Use Glob, Grep, and Read tools to understand the change. Identify which files would be affected, what patterns exist, and whether there are hidden dependencies. Spend enough time to form a genuine opinion — a superficial scan isn't sufficient.
Assess scope: Based on your exploration, evaluate whether this change is a good fit for /cpm:quick. Consider:
There are no hard thresholds. A 10-file change that follows an existing pattern is fine for quick execution. A 2-file change that introduces a new architectural pattern may not be.
Report assessment: Tell the user what you found. Be transparent about scope:
Use AskUserQuestion: "This looks like it might benefit from the full planning pipeline. Want to escalate?" with options:
/cpm:discover — Start with problem discovery/cpm:spec — Jump to specification/cpm:epics — Jump to work breakdown/cpm:quick — Proceed anywayIf the user chooses to continue, honour their decision and proceed to Step 2. Do not raise the scope concern again.
Update progress file now — write the full .cpm-progress-{session_id}.md with Step 1b summary before continuing.
Present a single concise proposal block for the user to confirm or adjust before any work begins.
Format the proposal as:
**Change**: {one-sentence summary of what will change}
**Files affected**:
- {path/to/file1} — {what changes}
- {path/to/file2} — {what changes}
**Acceptance criteria**:
- {criterion 1 — observable outcome}
- {criterion 2 — observable outcome}
Keep it tight — the proposal should be scannable in 10 seconds. Acceptance criteria should describe observable outcomes, not implementation steps. "Config file includes the new key" not "Edit the config file to add a key".
Fix-specific acceptance criteria (when Step 1a diagnosed a fix): Split acceptance criteria into two categories:
**Fix criteria** (the broken behaviour is resolved):
- {criterion — what now works correctly}
**Regression criteria** (the original bug cannot recur):
- {criterion — what was broken and proof it's gone}
Fix criteria describe the correct behaviour. Regression criteria describe the absence of the bug — they verify the specific failure mode is resolved, not just that the happy path works. Example:
If the test runner is available, regression criteria should ideally map to a test case in Step 3.
Use AskUserQuestion to confirm: "Ready to execute this change?" with options:
If the user adjusts, incorporate their feedback and re-present the proposal. Iterate until confirmed.
This is mandatory — do not skip it. After the user confirms the proposal, write it to a tracked file before proceeding to Step 3. This creates a hard gate: implementation cannot begin without a written spec.
Determine the record number and slug using the same convention as the completion record:
{nn}): Assigned by the shared Numbering procedure (from the CPM Shared Skill Conventions loaded at session start).{slug}): Derive a kebab-case slug from the change description (e.g. "add verbose flag to deploy script" → add-verbose-flag-deploy-script). Keep it concise — 3-6 words.Create the docs/quick/ directory if it doesn't exist. Write the spec file using the Write tool:
# {Title}
**Date**: {today's date}
**Status**: Confirmed — awaiting execution
## Change
{one-sentence summary of what will change}
## Files Affected
- `{path/to/file1}` — {what changes}
- `{path/to/file2}` — {what changes}
## Acceptance Criteria
- {criterion 1 — observable outcome}
- {criterion 2 — observable outcome}
The spec file path is docs/quick/{nn}-quick-{slug}-spec.md. Tell the user the spec file path after saving.
Update progress file now — write the full .cpm-progress-{session_id}.md with Step 2 summary (the confirmed proposal and spec file path) before continuing.
Do the work. Create Claude Code tasks and implement the change directly.
Hard gate — read the spec file first. Before creating any tasks, read the spec file written in Step 2 (docs/quick/{nn}-quick-{slug}-spec.md) using the Read tool. If the spec file does not exist, stop and go back to Step 2 — do not proceed without a written spec. Extract the acceptance criteria from the file; these are the source of truth for what to implement.
ADR awareness: Before starting implementation, check if this change touches architectural boundaries. Glob docs/architecture/[0-9]*-adr-*.md — if ADRs exist and the change involves structural decisions, data models, integration points, or deployment concerns, read the relevant ADRs for context. Let the architectural decisions guide implementation choices. If no ADRs exist, proceed normally.
Create tasks: Break the confirmed proposal into implementation tasks. Use TaskCreate for each:
TaskCreate:
subject: "{Task title — imperative form}"
description: "{What this task covers from the acceptance criteria}"
activeForm: "{Present continuous form}"
Create as many tasks as the work needs — a single-file change gets one task, a multi-step change gets several. Don't over-decompose; don't under-decompose.
Execute tasks sequentially: For each task:
in_progress.**Test command** in the progress file is not none, run the tests after writing them to confirm they pass.completed.Keep momentum: Move through tasks efficiently. Don't over-explain between tasks. The proposal was already confirmed — now execute it.
Update progress file now — write the full .cpm-progress-{session_id}.md with Step 3 summary (tasks completed, files changed) before continuing.
After execution, verify acceptance criteria and write the completion record.
Re-read the acceptance criteria from the spec file written in Step 2. Verify each criterion against the current state of the codebase using two methods:
Run tests first: If **Test command** in the progress file is not none, run the cached test command using the Bash tool before self-assessment.
**Test command** is none: skip test execution and rely on self-assessment only.Self-assess each criterion: Inspect the relevant files using Read, Glob, or Grep to confirm each criterion is met. Test results (if available) serve as supporting evidence but do not replace criterion-by-criterion assessment.
If the user chooses "Fix now", address the gaps and re-verify. Iterate until criteria are met or the user decides to proceed.
The completion record replaces the spec file written in Step 2. Use the same path (docs/quick/{nn}-quick-{slug}-spec.md) and update it in-place using the Write tool — changing the status from "Confirmed — awaiting execution" to "Complete" and adding the execution details:
# {Title}
**Date**: {today's date}
**Status**: Complete
## Context
{1-3 sentences explaining what prompted this change and why it was done via quick execution}
## Acceptance Criteria
- {criterion 1} — {Met/Not met}
- {criterion 2} — {Met/Not met}
## Changes Made
- `{path/to/file}` — {what changed}
- `{path/to/file}` — {what changed}
## Verification
{Brief summary of how criteria were verified — what was inspected, what confirmed the change is correct}
## Retro
**{category}**: {One-sentence observation}
The Retro field is mandatory. Reflect on the change as a whole and pick the most fitting category:
If nothing went wrong, use "Smooth delivery" — that's valuable data too. This feeds into /cpm:retro for cross-session learning.
Tell the user the record path after saving.
Update progress file now — write the full .cpm-progress-{session_id}.md with Step 4 summary, then delete the progress file. The session is complete.
Spec files are written during Step 2 and promoted to completion records during Step 4. Both use the path docs/quick/{nn}-quick-{slug}-spec.md. Create the docs/quick/ directory if it doesn't exist.
Maintain docs/plans/.cpm-progress-{session_id}.md throughout the session for compaction resilience. This allows seamless continuation if context compaction fires mid-execution.
Path resolution: All paths in this skill are relative to the current Claude Code session's working directory. When calling Write, Glob, Read, or any file tool, construct the absolute path by prepending the session's primary working directory. Never write to a different project's directory or reuse paths from other sessions.
Session ID: The {session_id} in the filename comes from CPM_SESSION_ID — a unique identifier for the current Claude Code session, injected into context by the CPM hooks on startup and after compaction. Use this value verbatim when constructing the progress file path. If CPM_SESSION_ID is not present in context (e.g. hooks not installed), fall back to .cpm-progress.md (no session suffix) for backwards compatibility.
Resume adoption: When a session is resumed (--resume) or context is cleared (/clear), CPM_SESSION_ID changes to a new value while the old progress file remains on disk. The hooks inject all existing progress files into context — if one matches this skill's **Skill**: field but has a different session ID in its filename, adopt it:
docs/plans/.cpm-progress-{current_session_id}.md with the same contents.rm docs/plans/.cpm-progress-{old_session_id}.md.
Do not attempt adoption if CPM_SESSION_ID is absent from context — the fallback path handles that case.KNOWN FAILURE MODE: The progress file update is the single most skipped instruction in this skill. It gets silently dropped when task momentum is high. Every time it is skipped, it creates a window where compaction would destroy the session with no recovery. Treat the Write call for this file with the same urgency as saving user code — it is not bookkeeping, it is the only thing standing between the user and total context loss.
Create the file before starting Step 1 (ensure docs/plans/ exists). Update it after each step completes. Delete it only after the completion record has been saved and confirmed written — never before. If compaction fires between deletion and a pending write, all session state is lost.
Also delete docs/plans/.cpm-compact-summary-{session_id}.md if it exists — this companion file is written by the PostCompact hook and should be cleaned up alongside the progress file.
Use the Write tool to write the full file each time (not Edit — the file is replaced wholesale). Format:
# CPM Session State
**Skill**: cpm:quick
**Step**: {N} of 4 — {Step Name}
**Change description**: {the original change description}
**Classification**: {fix | change}
**Test command**: {discovered test command, or "none" if no runner found}
## Library Check
{Files found, scope matches, or "No library documents found"}
## Completed Steps
### Step 1a: Diagnose (fix path only)
{Symptom, investigation summary, root cause hypothesis, confidence level, user confirmation. Omit this section entirely for change-path inputs.}
### Step 1b: Scope Assessment
{Summary — what was explored, scope assessment result, escalation offered/declined}
### Step 2: Propose and Confirm
{The confirmed proposal — change summary, files affected, acceptance criteria}
### Step 3: Execute
{Tasks completed, files changed}
### Step 4: Completion Record and Verification
{Verification outcome, record path}
{...include only completed steps...}
## Next Action
{What to do next}
/cpm:quick is speed. Don't add ceremony. One confirmation, then execute.