| name | work |
| description | Use when the user asks to 'run a work workflow', 'do this properly', 'clarify, plan, and verify this', 'small structured task', or 'don't just wing it' for a bounded task too small for a specialized workflow. |
| hooks | {"PostToolUse":[{"matcher":"AskUserQuestion","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/episode-phase.ts --workflow work"}]},{"matcher":"ExitPlanMode","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/approved-artifact-persist.ts --workflow work"}]}],"PreToolUse":[{"matcher":"Read|Glob|Grep|Bash","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/clarify-before-recon-guard.ts --workflow work"}]},{"matcher":"Write|Edit|MultiEdit|NotebookEdit","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/orchestrator-mutation-guard.ts --workflow work"}]},{"matcher":"Bash","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/orchestrator-mutation-guard.ts --workflow work"}]}]} |
Announce: "Using work โ clarify, plan, goal, verify, review."
!bun ${CLAUDE_SKILL_DIR}/../../scripts/ensure-plans-directory.ts ${CLAUDE_SESSION_ID}
Work
The lightweight, domain-agnostic workflow for a bounded task that deserves explicit intent,
evidence, independent verification, and human review without becoming a full domain workflow.
Write surface: main chat does not do the work
You may Write/Edit only under .planning/ and .claude/. Every other file the task touches is
written by a dispatched agent. orchestrator-mutation-guard is registered in this skill's
frontmatter, so the attempt is REFUSED, not corrected: a write you try anyway costs a turn and
produces nothing. Reach for Agent first, not after a denial.
Two narrow exceptions: the generated plan while you are IN Plan mode, and .claude-workflows.json
when adopting governance.
โโโโโ OUTER LOOP: REJECT: โ criteria were wrong โ CLARIFY โโโโโโโโโโโโโโโโโโโโ
โ โ
โผ โ
CLARIFY โโโบ PLAN โโโบ IMPLEMENT โโโบ VERIFY โโPASSโโโบ REVIEW โโโฌโ clean โ done โ
โฒ โ โ โ
โโโ fix โโโโFAIL โโ REJECT: โโโโโโโ
This diagram is the specification. Tactical failures repair work against the approved criteria.
REJECT: replaces the interpretation through a freshly approved plan.
Selection boundary
| Shape | Route |
|---|
| One-line answer, lookup, or tiny edit | Do it directly |
| Bounded cross-domain task needing clarify โ verify โ review | /work |
| Feature needing a real spec, TDD, or substantial architecture | /dev |
| Bug with an unknown cause | /dev-debug |
| Research-quality dataset analysis | /ds |
| Wrong analysis results or notebook failure | /ds-fix |
| Paper, article, or other long-form prose | /writing |
| Workshop presentation | /workshop |
| Existing artifact improved against a score | /audit-fix-loop |
Work's floor is โI would otherwise start typing and hope.โ Its ceiling is โthis now needs its own
specialized specification.โ Escalate by task shape rather than stretching this workflow.
Canonical state
NO WORK IMPLEMENTATION WITHOUT THE EXACT GENERATED PLAN AUTHENTICATED AND INDEPENDENTLY APPROVED BY .planning/.state/review.json.
For a modern work episode:
- The safe generated
.planning/<native-name>.md selected by review.json is the sole substantive
planning specification.
- The receipt binds its exact
plan_file, plan_hash, workflow identity, native approval session/time,
and independent review session/time. Use the exposed planFile and planHash unchanged.
- TaskList owns phase, task status, dependencies, attempts, verification rounds, review findings,
rejection disposition, and completion.
- Project auto-memory receives only reusable facts; normal project directories hold deliverables.
Do not create or treat any visible review, work, active-workflow, phase-summary, copied-plan, or mutable
status document as authority. Copying the generated plan into another specification creates competing
authority and is prohibited.
Startup and compatibility
Classify before resuming:
- Canonical:
review.json selects and authenticates one generated plan path/hash. If its review is
pending, resume at independent whole-plan review. If it is approved, reconcile and resume only
current-hash TaskList work.
- Legacy-only: retired planning or lifecycle files exist without an authenticated generated plan.
Explain the conversion, preserve them unchanged as provenance, reconstruct the required native plan
schema, and require fresh approval and independent review before implementation. Legacy files never
authorize implementation.
- Canonical with legacy provenance: the receipt-selected generated plan and TaskList remain the only
authority. Retired files may be read only to explain history; never merge them into the live
specification.
- Conflicting authority: a legacy approval layout competes with the generated receipt for current
authority. Stop, identify both layouts, and require explicit resolution; never merge automatically.
- On the same authenticated plan hash, reconcile TaskList and continue without duplicate tasks. A new
plan hash supersedes old open authority according to the deterministic rollover rules in IMPLEMENT.
1. CLARIFY
Read ${CLAUDE_SKILL_DIR}/../beat-clarify/SKILL.md and follow it before task reconnaissance. Supply
these generic axes: desired outcome, exclusions, material constraints, observable completion evidence,
and required human review surfaces. Keep clarification in the conversation until it is incorporated
into the native plan.
Gate: intent, exclusions, evidence-bearing success criteria, and review surfaces are explicit enough
to enter native Plan mode without guessing.
2. PLAN
Read ${CLAUDE_SKILL_DIR}/../beat-plan/SKILL.md, then ${CLAUDE_SKILL_DIR}/beats/plan.md for work's
required plan schema and proportionality ceiling. Use native Plan mode and obtain approval. The
PostToolUse persistence hook binds the exact generated plan bytes in the receipt and invalidates stale
review state. Then obtain one independent whole-plan review bound to the same hash.
Gate: the receipt-selected planFile and planHash form an approved artifact for workflow work.
Beats 3โ5 run as one program: workflows/work.js
Beats 3, 4 and 5 run as a single orchestrated workflow rather than as three stretches of main-chat
discipline. Two steps, in this order.
Step 1 โ get the authenticated args. One call, and it is not optional.
bun ${CLAUDE_SKILL_DIR}/../../scripts/beat/work-args.ts <abs project> --workflow work --session ${CLAUDE_SESSION_ID}
It prints {projectDir, workflow, planPath, planHash} read from .planning/.state/review.json and
re-hashed against the plan's current bytes, or it refuses and names the reason โ missing-artifact
(you have not been through PLAN), review-pending, stale-receipt (the plan was edited after
approval), or a receipt identity disagreement. Do not hand-copy planPath/planHash instead.
That is the step where a hash gets typed from memory and an unapproved plan gets implemented anyway.
Step 2 โ run the beats, merging in the task list.
Workflow({
scriptPath: "${CLAUDE_SKILL_DIR}/../../workflows/work.js",
args: {
...<the JSON from step 1, verbatim>,
tasks: [{ id, name, work, writablePaths: [], acceptance }], // from TaskList / the approved plan
},
})
tasks is the one field step 1 will not produce: TaskList belongs to Claude Code and no script can
read it, and deriving tasks from the plan's prose here would be exactly the LLM-discovery fallback
every other authority path in this repo refuses. work.js refuses an empty list.
It returns { workflow, planPath, planHash, overallPass, verdict, scoreTable, implemented, verified, findings, refutedFindings, reviews, tasksThatFlagged, carriedForward }. Render the gate, drive the
fix loop from findings, and re-invoke with onlyChecks: tasksThatFlagged plus priorReviews to
re-judge only what flagged.
Why a program and not three beats of instruction. The beat machinery restrains a free agent:
guards deny reconnaissance, the mutation guard denies main-chat writes, an order gate refuses an
out-of-order wave, a Stop hook refuses a turn end while review is owed. Every one of those exists
because the orchestrator could do otherwise. A workflow script has no Write tool and no shell, so
delegation is structural rather than enforced, and the beat order is the order of its statements.
What stays in main chat, and why the hooks do not all retire. CLARIFY needs AskUserQuestion
and PLAN approval needs ExitPlanMode โ both are conversations with a human, which a workflow
subagent cannot hold. Those two beats remain above, and remain hook-enforced. work.js refuses to
start without planPath and a 64-hex planHash, so it cannot be used to skip them.
3. IMPLEMENT
Dispatched by workflows/work.js above; this section is the adapter detail it enacts.
Read ${CLAUDE_SKILL_DIR}/../beat-implement/SKILL.md for its implementation/verification doctrine,
then read ${CLAUDE_SKILL_DIR}/beats/goal-work.md for this adapter's reconciliation and dispatch.
Gate: exactly one /goal is confirmed active, names the authenticated generated plan identity,
restates transcript-visible evidence requirements, and has a turn budget. TaskList contains the complete
current plan task set before ${CLAUDE_SKILL_DIR}/../beat-implement/SKILL.md receives a ready wave.
4. VERIFY
Read ${CLAUDE_SKILL_DIR}/../beat-verify/SKILL.md, then ${CLAUDE_SKILL_DIR}/beats/verify.md for the
dispatch payload and where each outcome goes. The verifier is never the doer.
Gate: every current-plan task has a post-change independent verification round recorded in TaskList,
all criteria pass, and the implementation /goal is cleared before human review.
5. REVIEW
Read ${CLAUDE_SKILL_DIR}/../beat-review/SKILL.md, then
${CLAUDE_SKILL_DIR}/beats/review-surface.md. The shared primitive owns feedback capture and disposition;
the adapter supplies the receipt-selected target and rendered surface.
Gate: TaskList has no open current-plan implementation, verification, or review item; the final
review relaunch has no new annotations; required rendered artifacts are fresh; and no REJECT: remains.
Escalation and rejection cap
- Same treatment over independent pinned items may use an explicitly approved closed fan-out stage;
/work keeps /goal, verification, and human review.
- At least five substantial files or eight implementation steps: dispatch scoped implementation tasks
through the shared authenticated runner. Mutations remain sequential without filesystem isolation.
- Round two and later resumes the original verifier.
- More than roughly ten plan steps or real sub-phases: move to the appropriate specialized workflow.
- On
REJECT:, clear the goal, preserve findings in TaskList, replace intent and criteria through a new
native plan, and increment the TaskList rejection count. If the rejection count is already 1, stop and
escalate or descope; two rejected interpretations require a real spec, not a third guess.
- If the turn budget expires without PASS, report failing criteria, evidence, and attempted fixes; offer
a new approach, criterion revision, or specialized workflow.
Red flags โ STOP
| About to | Do instead |
|---|
| Read or grep a task file before CLARIFY | Ask first; procedure files are the only exemption |
Run /work for a trivial edit | Do it directly |
| Let the plan acquire real sub-phases | Escalate to the specialized workflow |
| Treat implementer output as verification | Dispatch an independent verifier |
| Spawn a replacement verifier after a failure | Resume the same verifier |
| Mutate the receipt-selected generated plan after approval | Replace it through native Plan mode and fresh review |
| Treat legacy state as implementation authority | Convert explicitly and require fresh approval |
| Start a third interpretation after two rejections | Escalate or descope |
