| name | dev |
| description | Use for feature development and engineering changes. |
| allowed-tools | Read, Grep, Glob, Bash, Skill, AskUserQuestion, EnterPlanMode, ExitPlanMode, Agent, Workflow, TaskCreate, TaskUpdate, TaskList, TaskGet |
| hooks | {"PreToolUse":[{"matcher":"Read|Glob|Grep|Bash","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/clarify-before-recon-guard.ts --workflow dev"}]},{"matcher":"Write|Edit|MultiEdit|NotebookEdit","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/orchestrator-mutation-guard.ts --workflow dev"}]},{"matcher":"Bash","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/orchestrator-mutation-guard.ts --workflow dev"}]}],"PostToolUse":[{"matcher":"AskUserQuestion","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/episode-phase.ts --workflow dev"}]},{"matcher":"ExitPlanMode","hooks":[{"type":"command","command":"bun ${CLAUDE_PLUGIN_ROOT}/hooks/approved-artifact-persist.ts --workflow dev"}]}]} |
Announce: "I'm using dev to clarify the outcome before I inspect the codebase."
!bun ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.ts dev
!bun ${CLAUDE_SKILL_DIR}/../../scripts/ensure-plans-directory.ts ${CLAUDE_SESSION_ID}
Dev planning entry
CLARIFY → PLAN → IMPLEMENT → VERIFY → REVIEW
Write surface: main chat does not do the work
You may Write/Edit only under .planning/ and .claude/. Every other file — source, tests,
config — 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.
Beats 3–5 run as one program: workflows/work.js
Beats 3, 4 and 5 run as a single orchestrated workflow rather than 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 dev --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 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 }] },
})
It returns { workflow, planPath, planHash, overallPass, verdict, scoreTable, implemented, verified, findings, refutedFindings, reviews, tasksThatFlagged, carriedForward, domainRun }. 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 rather than 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. Each exists because the
orchestrator could do otherwise. A workflow script has no Write tool and no shell, so delegation is
structural and the beat order is the order of its statements. CLARIFY and PLAN approval stay above,
in main chat and hook-enforced, because both are conversations with a human that a subagent cannot
hold — and work.js refuses to start without planPath and a 64-hex planHash, so it cannot be
used to skip them.
1. CLARIFY
Write no sentinel. .planning/DEV_CLARIFIED.json is retired: a hook now records the clarify
phase into .planning/.state/episode.json when it OBSERVES your AskUserQuestion call. That is
direct evidence the user was asked. The sentinel was the model writing {"status":"clarified"} about
itself, which is an assertion, not a proof — and it could be written without ever asking.
Read ${CLAUDE_SKILL_DIR}/../beat-clarify/SKILL.md and follow it. The beat owns the procedure —
one AskUserQuestion call, done-ness always established, every criterion naming its own evidence,
and the ask-before-you-look Iron Law the recorded phase now proves. /dev supplies only the domain
question axes, which is exactly the split the beat defines:
outcome, exclusions, constraints, acceptance evidence, automated real-test strategy, intended
first failing test, user workflow, protocol/transport, and review surfaces.
This step is /dev's pre-reconnaissance clarification and is distinct from dev-clarify, which
runs after reconnaissance to resolve what only the codebase can surface. The two are a sequence,
not duplicates — asking everything up front cannot work, because the questions reconnaissance raises
do not exist yet, and asking everything afterwards lets existing shapes anchor the framing. That
distinction was previously implicit, which is how this pre-recon step ended up hand-rolled: the guard
enforced that it happened while nothing defined what it was.
Nothing is written after the user answers. The recorded phase IS the evidence, and it is
evidence precisely because a hook observed the tool call rather than reading the model's account of
it. Never create SPEC.md, SPEC_REVIEWED.md, EXPLORATION.md, ACTIVE_WORKFLOW.md,
STATE.md, LEARNINGS.md, BACKLOG.md, or HANDOFF.md.
Iron law: ask before reconnaissance. Code explains how the current system works, not what
the user wants. A manual-only test proposal is a blocker: resolve an automated test approach or
leave this workflow rather than silently waive TDD.
Then reconnoitre and resolve what only the codebase can surface:
- Read
${CLAUDE_SKILL_DIR}/../dev-explore/SKILL.md; return its findings directly to the user.
- Read
${CLAUDE_SKILL_DIR}/../dev-clarify/SKILL.md; resolve ambiguities exposed by reconnaissance.
Gate: the pre-reconnaissance AskUserQuestion phase is recorded in .planning/.state/episode.json,
every criterion names its own evidence, an automated test approach exists, and post-recon ambiguities
are resolved.
2. PLAN
Read ${CLAUDE_SKILL_DIR}/../beat-plan/SKILL.md, then:
- Read
${CLAUDE_SKILL_DIR}/../dev-design/SKILL.md; present alternatives and obtain the architecture choice.
- Enter native Plan mode. The generated plan returned by
ExitPlanMode is the sole plan and
exact-byte approval boundary. Do not copy, rename, or replace it.
- Read
${CLAUDE_SKILL_DIR}/../dev-plan-reviewer/SKILL.md and dispatch the independent whole-plan
review for that exact generated path. Only its hidden receipt can admit implementation.
Gate: the receipt-selected planFile and planHash are APPROVED for workflow dev by a
reviewer session distinct from the approving session.
3. IMPLEMENT
Read ${CLAUDE_SKILL_DIR}/../beat-implement/SKILL.md, then ${CLAUDE_SKILL_DIR}/../dev-implement/SKILL.md.
Gate: TaskList holds the complete current-plan task set, each implemented task records its
first failing test and the change that made it pass, and no task ran without the beat's preflight.
4. VERIFY
Read ${CLAUDE_SKILL_DIR}/../beat-verify/SKILL.md, then ${CLAUDE_SKILL_DIR}/../dev-verify/SKILL.md.
The verifier is never the implementer.
Gate: every current-plan task has a post-change independent verification round recorded in
TaskList and every acceptance criterion passes on its named evidence.
5. REVIEW
Read ${CLAUDE_SKILL_DIR}/../beat-review/SKILL.md, then ${CLAUDE_SKILL_DIR}/../dev-accept/SKILL.md.
Automated PASS is not a person's acceptance.
Gate: TaskList has no open current-plan implementation, verification, or review item; the final
review relaunch has no new annotations; and no REJECT: remains.
Resume and compatibility
A prior fixed dev plan or visible ledger is conversion-only provenance. Do not resume it. If the
user needs changed requirements, architecture, task dependencies, test contract, or evidence,
create a new native generated plan and obtain a new receipt.
