Codex compatibility note:
- Invoke
$skill-name: load the registered.agents/skills/<name>/SKILL.mdand execute it with Codex tools; no separateSkilltool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author.claude/**; mirrors are generated.- Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
- Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
- Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required
spawn_agentsubagent(s) for that task.- Preserve protocol order unless the user approves a deviation. Workflows use
$start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.
Workflow Calls and Todo Bootstrap
Read the registry → workflows.workflow-implement-spec together with this skill. Call $start-workflow workflow-implement-spec to resolve the selected mode, pre-actions and fingerprint.
Todo FIRST: before triage, analysis or step execution, create one todo per phase of the selected mode, in order, listing every occurrence of that phase as a line, including conditional/optional ones (a mode that declares no phases gets one todo per occurrence); preserve occurrence IDs, roles and barrier groups. Use native todo tools or an equivalent persistent ledger. Then mark the first todo in_progress; close each step line with its run or skip evidence, and complete a phase todo only when every line is closed and its applicable exit gates hold.
Mode selection and registry loading prepare tracking; any 'first action' below means the first substantive action after this bootstrap.
Call each step skill: start its linked SKILL.md through the active host's skill call with the registry args. When the host refuses that call (a user-only skill) or has no skill call, read the SKILL.md in full yourself (every line, with no line limit; in parts only when output is cut off) and follow it with the same args; that is the same execution, not a bypass. Naming a skill alone is not execution. After a context compaction, re-read the SKILL.md of the step in progress before continuing: compaction can drop or truncate a loaded skill. Required gates and core/optional flex follow the linked start-workflow Step Execution Protocol; keep this skill's quality gates, loops and evidence requirements.
Conditions: load each occurrence's registry applicability.when and skipReason verbatim, and record its run/skip evidence through the linked start-workflow protocol. Do not silently omit a todo or turn a conditional skill into an unconditional call; close, in one batch at triage, the todos whose condition is already false there. Declared parallel groups retain their all-return barrier.
Explicit step-skill calls by mode (registry order; roles and conditions remain owned by the registry):
- Mode
default:$investigate(core) →$spec [mode=clarify](core) →$plan(core) →$plan --mode=execute(core) →$seed-test-data(optional; conditional) →$integration-test(optional; conditional) →$spec [mode=sync](optional; conditional) →$workflow-review-changes --tests=defer(gate) →$integration-test --mode=verify(gate) →$workflow-e2e --source=context(optional; conditional) →$test --proven=@verify(gate) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (1) → Specify (1) → Plan (1) → Build (4; exit spec-synced) → Review (1; exit review-converged) → Verify (3; exit tests-pass) → Close (2; exit run-closed)
- Mode
greenfield-slice:$investigate(core) →$spec [mode=clarify](core) →$plan(optional; conditional) →$plan --mode=execute(core) →$seed-test-data(optional; conditional) →$integration-test(optional; conditional) →$spec [mode=sync](optional; conditional) →$workflow-review-changes --tests=defer(gate) →$integration-test --mode=verify(gate) →$workflow-e2e --source=context(gate) →$test --proven=@verify(gate) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (1) → Specify (1) → Plan (1) → Build (4; exit spec-synced) → Review (1; exit review-converged) → Verify (3; exit tests-pass) → Close (2; exit run-closed)
Regenerate this block with node .claude/scripts/lib/workflow-skill-contract.cjs --write after registry edits; $sync-codex refreshes it before mirroring.
Work tracking: Keep the project's tracked work current in the same change, as its root instructions (
CLAUDE.mdorAGENTS.md) say. When the project uses the portable tracker (taskTracking.modeisobserveorlinked), read the linked work integration guide at capture, start, saved-work, verification, handoff and close-out checkpoints. Use the actual linked producer and exact items; retain the primary outcome and record optional upkeep once through the common owner. Continue untracked when no link exists; acceptance remains explicit.
Quick Summary
Goal: Implement already-specified behavior within the supplied baseline, proven by green tests, converged review and reconciled spec evidence.
Summary: The supplied spec replaces feature discovery, spec-authoring and test-spec rounds. Triage → investigate → clarify gaps → plan → execute (code and tests together) → optional seed data → missing integration tests → sync changed behavior/evidence → review statically → verify integration tests → E2E (when asked for; always in greenfield-slice) → test remaining tiers → close → hand off.
Workflow: Activate $start-workflow workflow-implement-spec with the user's prompt; follow the registry and step contracts below.
Key Rules: Implement the supplied spec without re-authoring it or growing scope. Missing behavior routes to workflow-feature, which updates the spec first; other gaps stop for clarification before planning. Keep every phase within spec_baseline; review runs inline and tests run last.
Contents
- Workflow Calls and Todo Bootstrap
- Quick Summary
- Size & Kind Triage (first action)
- Required Quality Gates
- Gates and Optional Steps
- Orchestration Freedom
- Memory & Reporting
- Fix Path & Loop Bounds
- Closing Reminders
Size & Kind Triage (first action)
Classify the target before choosing depth; record it in the run report:
- Size (guidance, not a law): XS 1–3 files / ≤100 changed lines · S ≤15 files · M ≤60 · L ≤300 · XL >300.
- Kind: behavior change · public contract/API · data/schema/migration · security-sensitive (auth, secrets, money, PII) · UI surface · infra/CI · cross-module/cross-service · test-only · tooling/config.
- Risk: irreversible · data · security · cross-module. Escalate depth on risk and ambiguity, not file count alone.
Depth by band:
- XS/S — a short investigation and a short plan (a few tasks, each traced to the spec baseline); work inline. The plan step asks for plan approval only when the run's request does not already authorize the scope.
- M, or any public-contract, data/schema or security kind — full investigation and one lean plan that keeps every section; user-owned decisions go through the validation chain
$planruns inside this workflow (plan→ Standalone Validation Chain; the route lists no separate validate step), which applies the answers in the same step. - L/XL — partition the build, the integration tests and the review into bounded batches per module or TC group, one report per batch; the plan names the batches.
At every size, $spec [mode=clarify] checks the supplied spec against the request before $plan, through its EXISTING-SPEC gap-review profile (spec/references/mode-clarify.md), and $plan uses its light spec-supplied profile: the supplied spec is the scope and its cases are the scenario evidence, so it writes no scope-brief or scenario file.
Required Quality Gates
- Tests pass (
tests-pass) —$integration-test --mode=verify(incl. the mutation check) ran green in THIS run, once, after the static review, and$test --proven=@verifyran every tier that verify report does not cover; every implemented TC has a test that names itsBusiness Intent / Invariant Guardedand would fail if that intent broke - Review converged (
review-converged) — nested$workflow-review-changesran inline in the main session and converged — validated blocking findings fixed and the fixed state re-reviewed - Spec synced (
spec-synced, when behavior or evidence mappings changed) —$spec [mode=sync]reconciled the supplied spec with implemented behavior and actual case-to-test evidence after test authoring and before review; when review fixes invalidate that reconciliation, repeat only that scoped sync before final verification - Run closed (
run-closed) —$workflow-endchecked every gate - No guessed behavior — the gap review passed, or the route stopped per the escalation rule below
- Scope held — the workflow records the supplied
spec_baseline; plan phases and acceptance evidence stay within it - Greenfield first slice —
$workflow-greenfield-inithands its first slice off as$workflow-implement-spec --mode=greenfield-slice. That mode skips$planwhile the approved plan the foundation handed off still covers the slice and its spec (its registrywhenis false; cite the plan and its Validation Summary), runs seed data when the product persists state, and makes the near-end$workflow-e2e --source=contexta gate
[ESCALATION — BLOCKING]
$spec [mode=clarify]runs as a gap review of the supplied spec against the request. When the spec is vague or contradictory, or the requested behavior is not in the supplied spec, STOP before$planand ask the user to clarify the spec or switch toworkflow-feature, which updates the spec first. Never guess the missing behavior and never drop it silently. A spec with one open question is clarified before planning.
[PLAN SCOPE ANCHOR] Before
$plan, the workflow report records the supplied spec path and revision asspec_baseline.$plannames it as governing intent and keeps every phase and acceptance gate within that baseline. A requirement the baseline lacks is recorded asProposed additions — owner approval requiredand becomes a question, never an accepted plan phase.
Gates and Optional Steps
Step contract: Read $start-workflow → Step Execution Protocol for gate/core/optional execution and deviation logging. The table follows .claude/workflows.json → workflow-implement-spec; apply the triage above.
| Step | Role | Earns its cost when | Proves / feeds |
|---|---|---|---|
$investigate |
core | always — read the supplied spec and the affected code; find 3+ local examples | gap-review input |
$spec [mode=clarify] |
core | always — the EXISTING-SPEC gap review | no guessed behavior |
$plan |
core | always; light spec-supplied profile, with its own validation interview | spec_baseline, traced tasks |
$plan --mode=execute |
core | always | the change and its tests, written together per phase |
$seed-test-data |
optional | default: the change adds entities or flows that need realistic development data · greenfield-slice: the product persists state, or its tests or demo need seeded data |
development data for manual QC |
$integration-test |
optional | a test case still has no executing test after the execute step | tests for the remaining TCs |
$spec [mode=sync] |
optional | behavior or canonical case-to-test evidence/mappings changed | spec-synced |
$workflow-review-changes --tests=defer |
gate | always | review-converged |
$integration-test --mode=verify |
gate | always | tests-pass — the one verify, with the mutation check |
$workflow-e2e --source=context |
optional (default) · gate (greenfield-slice) |
default: the user explicitly asks for E2E work · greenfield-slice: always |
near-end E2E evidence, or an evidence-backed N/A / ENVIRONMENT-BLOCKED |
$test --proven=@verify |
gate | always | tests-pass — runs only the tiers this run's verify report does not cover |
$workflow-end |
gate | always | run-closed — prints the recap when $watzup does not run |
$watzup |
optional | a session report was requested, or several workflows need one handoff | consolidated session report |
Conditional steps:
$integration-testruns after the execute step only for test cases still without an executing test. Skip reason: "Every test case already has an executing test written by the execute step."$spec [mode=sync]runs after the tests exist when behavior differs or canonical case-to-test evidence/mappings changed, and before the nested review. Skip reason: "Behavior and canonical case-to-test evidence still match the supplied spec, so no reconciliation is needed."$seed-test-dataruns after the execute step when the change adds entities or flows that need development data (greenfield-slice: when the product persists state). Skip reason: "The implemented behavior adds no entity or flow that needs new development data." (greenfield-slice: "The product persists no state, and its tests and demo need no seeded data.")$workflow-e2e --source=context(defaultonly; a gate ingreenfield-slice) runs on an explicit E2E request. Skip reason: "No explicit E2E request was found in the user prompt; the optional E2E handoff is disabled by default."$plan(greenfield-sliceonly) runs when no approved plan was handed off, or the slice or its spec changed since approval. Skip reason: "The approved implementation plan workflow-greenfield-init handed off still covers this slice and its spec; cite its path and its Validation Summary."$watzupruns on a request for a session report or when several workflows or prompts need one handoff. Skip reason: "workflow-end printed the recap, or the short handoff when nothing was built, and every applicable outcome gate passed."
Keep this verifier-parsed chain equal to the registry; roles determine permitted flex:
IMPORTANT MANDATORY Steps: $investigate -> $spec [mode=clarify] -> $plan -> $plan --mode=execute -> $seed-test-data -> $integration-test -> $spec [mode=sync] -> $workflow-review-changes --tests=defer -> $integration-test --mode=verify -> $workflow-e2e --source=context -> $test --proven=@verify -> $workflow-end -> $watzup
On-demand skill (not a registry step): $investigate --mode=debug — a test fails and its cause is unknown.
Orchestration Freedom
Choose inline/sub-agent execution, parallel waves, batching and ordering at equal quality, preserving these dependencies:
- the gap review precedes
$plan; a change exists before it is reviewed or tested; tests run once, last, after the static review (--tests=defer); a fix made by the verify step re-runs$workflow-review-changes --tests=defer, and a fix made by that re-review re-runs the verify (SYNC:verify-last-order); $plan --mode=executewrites each phase's code and tests together, and$integration-test(when its condition holds) adds the executing tests still missing, before the single conditional$spec [mode=sync]reconciliation; the sync precedes review, and only that scoped sync repeats before final verification when review fixes invalidate it;- the nested
$workflow-review-changesruns inline in the main session — it owns the session's review→fix→re-review loop, and its own reviewers run as sub-agents; - a gap-review question to the user is never parallelized with later work;
$workflow-endruns last, then$watzupwhen its condition holds.
Memory & Reporting
- One phase task per phase, one row per selected step or L/XL batch; skipped steps keep tasks closed with logged deviations.
- Write the run report FIRST under
tmp/reports/— triage result,spec_baseline, gate evidence, deviations — and append per step or batch; re-read it and the current task list after compaction. - Sub-agent briefs carry the supplied spec path,
spec_baseline, resolved reference-doc paths and report-writing as their first deliverable.
Fix Path & Loop Bounds
- Validate findings (evidence-backed, reproducible) before fixing; fix at the owning layer; re-run the reviewer or test that raised each finding, plus a holistic pass when the fixes were non-trivial.
- A failing test gets a root-cause verdict before either the source or the test is edited; never weaken an assertion to force green. A test that contradicts the supplied spec is adjudicated against the spec, never silently rewritten.
- Re-run
$planonly when a material scope or contract decision invalidates the saved plan; ordinary implementation discovery stays with the executor. - The nested review keeps the framework loop bounds: round 1 exits on zero open validated findings (LOW deferral); round 2 exits on zero CRITICAL/HIGH/MEDIUM with LOW-only findings deferred; cap 3 review rounds; failed checks block and at the three-round cap require explicit user-approved bounded extension; escalate with
ask user question toolon no progress.
Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.
incremental-persistence— Persist results per file or section while the work proceeds; a sub-agent or heavy step processes more than three files → .claude/skills/shared/protocols/incremental-persistence.mdsession-goal-ledger— Keep the original goal and every user prompt of the session; running a long or multi-prompt session → .claude/skills/shared/protocols/session-goal-ledger.mdsubagent-return-contract— Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.mdverify-last-order— Build all phases and write tests, review statically, then verify once with a mutation check; planning or running any code-changing task → .claude/skills/shared/protocols/verify-last-order.mdworkflow-registry-binding— Read the workflow registry entry and the workflow skill together, since they must agree; executing or editing a workflow → .claude/skills/shared/protocols/workflow-registry-binding.md
- MANDATORY Session goal ledger per the
Task Planning Rules: pinOriginal goal:, keepUser prompts this session: P1…Pn, and map the result to every prompt before claiming done; full text:.claude/skills/shared/protocols/session-goal-ledger.md.
Closing Reminders
IMPORTANT MUST ATTENTION Goal: Implement already-specified behavior within the supplied baseline, proven by green tests, converged review and reconciled spec evidence.
IMPORTANT MUST ATTENTION Main steps: triage → investigate → clarify gaps → plan → execute (code and tests together) → missing integration tests → sync changed behavior/evidence → review statically → verify integration tests → E2E (when asked for; always in greenfield-slice) → test remaining tiers → close → hand off.
IMPORTANT MUST ATTENTION a vague, contradictory or incomplete spec stops the route before $plan — the user clarifies the spec or switches to workflow-feature.
IMPORTANT MUST ATTENTION the workflow records the supplied baseline before planning; every plan phase and acceptance gate stays within it, and anything beyond it needs owner approval.
IMPORTANT MUST ATTENTION gates never flex: tests green in THIS run · nested $workflow-review-changes converged inline · spec synced before the review when behavior differs · $workflow-end last.
IMPORTANT MUST ATTENTION triage size, kind and risk first; depth follows risk, and every deviation is logged with evidence.