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-feature together with this skill. Call $start-workflow workflow-feature 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=discovery](optional; conditional) →$domain-analysis(optional; conditional) →$why-review(optional; conditional) →$spec(core) →$scenario(optional; conditional) →$work-item --mode=mockup --explore(optional; conditional) →$spec [mode=tests](core) →$work-item --mode=review --type=spec-tests(core) →$spec [mode=clarify](optional; conditional) →$plan(core) →$plan --mode=execute(core) →$seed-test-data(optional; conditional) →$integration-test(optional; conditional) →$spec [mode=sync](core) →$workflow-review-changes --tests=defer(gate) →$integration-test --mode=verify(gate) →$workflow-e2e --source=context(optional; conditional) →$test --proven=@verify(gate) →$demo-guide(optional; conditional) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (4) → Specify (6) → Plan (1) → Build (4; exit spec-synced) → Review (1; exit review-converged) → Verify (4; 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: Deliver a well-defined feature whose reviewed canonical spec matches the implementation, verified tests and converged change review.
Summary:
- Triage size, kind and risk; activate the workflow and resolve its registry, Goal Contract and artifact authority.
- Main route: investigate → spec discovery → domain analysis → design rationale review (real alternatives only) → spec authoring → scenarios → explore mockup → test specs → test-spec review → clarification → plan (with its own validation interview) → execute (code and tests together) → QC seed data → missing integration tests → spec sync → static change review → integration verification → E2E → remaining test tiers → demo → close → handoff. Evaluate optional steps by the registry's conditions and record its skip reasons.
- Preserve spec-first/test-first dependencies, human approval gates and verify-last ordering; close only with the required outcome evidence. Spec-complete work uses
workflow-implement-spec; large ambiguous work usesworkflow-big-feature.
Contents
- Workflow Calls and Todo Bootstrap
- Quick Summary
- Purpose
- Size & Kind Triage (first action)
- Required Quality Gates
- Gates and Optional Steps
- Orchestration Freedom
- Memory & Reporting
- Fix Path & Loop Bounds
- Closing Reminders
Purpose
Deliver a well-defined feature spec-first and test-first: the canonical Feature Spec states the intended behavior, test specs are written and reviewed before implementation, and the run ends with green tests, a converged change review and a spec re-verified against what was actually built. Use it when no canonical spec holds the requested behavior yet — this workflow updates the spec first. Spec-complete work goes to workflow-implement-spec; large, ambiguous or research-heavy work belongs in workflow-big-feature; a focused one-module change with no contract change is usually a custom-simple route, not this workflow.
Activate the workflow-feature workflow. Run $start-workflow workflow-feature with the user's prompt as context.
Size & Kind Triage (first action)
Classify the target before choosing steps and record the result 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 (one or more): docs-only · tooling/config · test-only · behavior change · public contract/API · data/schema/migration · security-sensitive (auth, secrets, money, PII) · UI surface · infra/CI · cross-module/cross-service
- Risk: irreversible · data · security · cross-module
- Large idea:
isLargeIdea = multipleIndependentOutcomes || ambiguousOrResearchHeavy || releaseScopeDecomposition || oversizedTaskThatMustSplit(shared/product-roadmap-contract.md)
Escalate depth on risk and ambiguity, not file count alone:
- XS/S, one module, clear intent — light investigation; update only the affected spec sections; one plan in the light profile; no re-plan. Test specs receive one quality review before the build. Work inline — sub-agents rarely pay off.
- M, or any public-contract, data/schema, security or cross-module kind — every core step at full depth plus each optional step whose condition holds (
$scenario,$domain-analysis,$spec [mode=clarify], ...). - L/XL, or
isLargeIdeatrue — everything M runs, plus the embedded decomposition and bounded batches per module or slice for the build, test specs and review (one report per batch). A research-heavy scope that cannot be cut into slices → recommendworkflow-big-featureto the user.
Representation authority: resolve shared/sdd-artifact-contract.md and the configured/native case contract before interpreting the gates. Section/TC examples below apply only to the strict fallback; native profiles use their declared intent/evidence roles, owner-qualified IDs, carriers and mapping relation. Never create a second registry or default section to satisfy an example; unresolved mappings block.
Required Quality Gates
The run is not done until each applicable gate holds with its evidence:
- 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 changed behavior maps to a §8 TC that names itsBusiness Intent / Invariant Guardedand would fail if that intent broke; lifecycle behavior asserts persisted state transitions and invalid-transition rejection - 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 a public contract changed) — Feature Spec §1-7 re-verified against the built behavior (the post-implementation re-verify is part of the gate, not optional cleanup); every divergence adjudicated perSYNC:spec-drift-adjudicationinshared/sdd-artifact-contract.md→ Drift Gates: CODE-WRONG → fix code/tests, SPEC-STALE →$specupdate then the test-spec update and$spec [mode=sync], AMBIGUOUS → escalate to the spec owner; §8 TCs ↔ test code synced - Run closed (
run-closed) —$workflow-endchecked every gate and emitted the Goal Satisfaction matrix - Spec-first, test-first — the canonical Feature Spec was authored or updated before the first
$plan; test specs were written and reviewed before$plan --mode=execute - Goal Contract — the active Goal Contract is resolved at start per
SYNC:goal-contract-satisfaction-loop(active plangoal.md→goals/{YYMMDD-HHmm}-{slug}/goal.mdunder the plans root, defaultplans/, relocated bydocsRoots.plans.pathindocs/project-config.json→ create from the request); the plan's success criteria map to it before$plan --mode=execute; every child step reads that same goal file; closure needs every criterion PASS, or BLOCKED with a user-facing escalation - Plan Gate —
$planruns its own validation chain inside this workflow (plan→ Standalone Validation Chain; the route lists no separate validate step) and applies the answers in that step;$plan --mode=executenever starts while the plan's## Plan GateisBLOCKEDor lacks human approval - Large idea (when
isLargeIdeais true) — the complete five-fieldlarge_idea_decompositionblock (outcome_slices,dependencies_order,non_goals,risks_evidence,deferred_work_owner) sits in the owning spec/task before the first mutating$specand carries its slice IDs through downstream presentation/mock-up artifacts; all-false work omits it; a genuinely isolated brownfield change recordsEXEMPTwith reason and accepting owner and keeps the spec, scenario, test, review and human-confirmation gates. This workflow never creates a roadmap artifact — an explicitly supplied roadmap is read-only context - Existing behavior preserved (when an existing final output, persisted state, API response, projection or user-visible flow changes) — before the build: an end-to-start trace of the existing path (final reader → storage/projection → writer → producer/origin), its feeder paths, the invariants to keep, and forward proof for the new behavior; the plan and review evidence state expected, unchanged and no-regression behavior
- Performance route (when the feature is a performance enhancement) —
$performance-reviewwith SLA/benchmark evidence — target metric, baseline, measurement command, regression budget;$plan --mode=executestill runs; functional no-regression checks run whenever behavior can change; spec/docs updated for a changed SLA, performance constraint or behavior boundary - UI intent (when user-facing behavior changed) — alongside
$spec [mode=sync], the Feature Spec §6 interaction surface (View Inventory, Key UI States, per-story click-path) is refreshed perSYNC:ui-intent-layerand linked to the governing$design-spec; a backend-only change states its skip reason
Gates and Optional Steps
Step contract: $start-workflow → Step Execution Protocol owns how gate, core and optional steps run; the registry (.claude/workflows.json → workflow-feature, delivered in the Tier-2 output) owns each step's role and its applicability (when / skipReason, recorded verbatim on skip). This table adds only what the registry does not state: what each step proves or feeds, plus triage hints.
| Step | Role | Proves / feeds · triage hint |
|---|---|---|
$investigate |
core | plan evidence — read the affected area's spec under the business spec root first (default docs/specs; a specRoots.business.path entry in docs/project-config.json overrides the path) and find 3+ local examples |
$spec [mode=discovery] |
optional | overlaps and missing TCs before authoring — pass this run's investigation report as --investigation=<report path> so it is not re-run |
$domain-analysis |
optional | entity model, ownership |
$why-review |
optional | a design choice between real alternatives in the investigation or spec draft |
$spec |
core | spec-first gate — Feature Spec §1-7 before planning |
$scenario |
optional | plan risk coverage |
$work-item --mode=mockup --explore |
optional | selected mockup before planning — see New-UI Explore Mockup below |
$spec [mode=tests] |
core | test-first gate — every invariant mapped to TC IDs in §8 |
$work-item --mode=review --type=spec-tests |
core | test-spec quality, and the design trade-offs the spec encodes (its trade-off questions) |
$spec [mode=clarify] |
optional | one decision interview after the test-spec review: user-confirmed spec decisions, including the material trade-offs that review raised |
$plan |
core | decisions, areas, discovery, gates — one plan over the reviewed intent and cases; its own validation interview records human approval and applies the answers (light profile for XS/S) |
$plan --mode=execute |
core | the change and its tests, written together per phase; the performance route included |
$seed-test-data |
optional | QC data |
$integration-test |
optional | executing tests for any TC the execute step left without one |
$spec [mode=sync] |
core | spec-synced — after executing tests exist, reconcile spec, cases and actual test evidence |
$workflow-review-changes --tests=defer |
gate | review-converged |
$integration-test --mode=verify |
gate | tests-pass — the one verify, after the review; runs the mutation check |
$workflow-e2e --source=context |
optional | E2E evidence |
$test --proven=@verify |
gate | tests-pass — runs only the tiers this run's verify report does not cover |
$demo-guide |
optional | demo path |
$workflow-end |
gate | run-closed — prints the recap when $watzup does not run |
$watzup |
optional | consolidated session report on request or across several workflows |
New-UI Explore Mockup (conditional, BEFORE $plan). When the requirement or spec adds completely new user-facing UI — a new page/view, component or dialog — or the owner asks for a new look or a new layout of existing views, run $work-item --mode=mockup --explore, passing the spec (or the investigation report when no spec covers the UI yet) as --source. work-item --mode=mockup Step 0 owns the scope gate (asked first, before any analysis or drafting) and the direction pick; both run in the main session only. Record the outcome (Mockup: SKIPPED by user or the Selection: line) in the plan or run report; the plan's UI Layout builds on the selected mockup. Other changes inside existing views skip it with the registry skipReason.
The registry's default order, parsed by the workflow verifier — keep it equal to workflows.json; the roles above decide what may flex:
IMPORTANT MANDATORY Steps: $investigate -> $spec [mode=discovery] -> $domain-analysis -> $why-review -> $spec -> $scenario -> $work-item --mode=mockup --explore -> $spec [mode=tests] -> $work-item --mode=review --type=spec-tests -> $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 -> $demo-guide -> $workflow-end -> $watzup
On-demand skills (not registry steps):
$design-spec --mode=wireframe— UI work arrives with an image or wireframe: run it before$plan; a design link alone (e.g. a Figma URL) → ask the user to export the frames as images. When$planfinds frontend phases, include theui-wireframe-protocol.mdsections in them.$performance-review— the performance route above.$investigate --mode=debug— a test fails and its cause is unknown; establish the root cause before editing either side.
$workflow-e2e --source=context runs only on an explicit E2E request ("include E2E", "write E2E", "run E2E", "do end-to-end verification"); otherwise it records its registry skip reason. When it runs, its nested workflow keeps default-on screenshot review and records evidence-backed N/A or ENVIRONMENT-BLOCKED when the repository lacks the capability.
Orchestration Freedom
You choose inline vs sub-agent, parallel waves vs sequential, batching and ordering — optimize wall-clock and token cost at equal quality. Main session only: the mockup scope gate and pick (work-item --mode=mockup Step 0) never run inside a delegated sub-agent. Only these data dependencies are fixed:
- 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); - the Feature Spec precedes the first
$plan, and test specs are reviewed before$plan --mode=execute; $plan --mode=executewrites each phase's code and tests together, and$integration-test(when its condition holds) adds the executing tests still missing, before one$spec [mode=sync]reconciliation; the sync runs before the review that checks 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; - steps awaiting user answers (
$spec [mode=clarify], the plan's validation interview and Plan Gate approval) are never parallelized; $workflow-endruns last, then$watzupwhen its condition holds.
Recommended: independent read-only work in one parallel wave ($spec [mode=discovery] follows $investigate and reuses its report); L/XL partitioned into bounded batches per module or slice with one report per batch; XS/S done inline. The nested review owns $integration-test --mode=review, $security-audit, $domain-analysis --mode=review, $experience-review and the conditional domain-entity reference refresh ($scan --target=domain-entities → $docs-manager --mode=update, run when the final diff changes an entity, data contract or schema represented in domain-entities-reference.md); this workflow's tail does not repeat them. $experience-review records NOT-APPLICABLE or ENVIRONMENT-BLOCKED honestly and never promotes a new expectation without explicit acceptance.
Memory & Reporting
- One phase task per phase, one row per selected step (and per batch for L/XL) so nothing is lost after compaction; a step that does not run keeps its task, closed with its logged deviation.
- Write the run report FIRST under
tmp/reports/— triage result, gate evidence, deviations — and append per step or batch; re-read it and the current task list after compaction. - Sub-agent briefs carry the goal file path and the resolved reference-doc paths, and make report-writing their first deliverable.
- Project conventions come from
docs/project-config.jsonanddocs/project-reference/docs-index-reference.md; apply the shared SDD Artifact Contract (shared/sdd-artifact-contract.mdin the active skills root). Any supported AI tool may implement or review once that contract, synced context and local docs are available. Code-extracted specs and TCs stay reference-only until canonical review accepts them.
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.
- Replanning is exceptional: only a material scope/contract decision invalidating the saved plan returns to
$plan; ordinary implementation discovery stays with the executor. - Review loops (each
$work-item --mode=reviewoccurrence, the nested review): 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 withask user question toolon no progress. Convergence lives inside each skill's own loop, so the sequence lists each review once. - Spec-loop discipline: §8 derives invariant/property TCs for every hard rule and invariant, not only example scenarios; every behavior-changing finding updates BOTH the spec and the tests, never code alone.
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.
end-to-start-debugger-trace— Walk backward from the observed end state through every feeder path before fixing; investigating non-trivial bugs or failed verification, changing code behavior, or tracing unclear code flow → .claude/skills/shared/protocols/end-to-start-debugger-trace.mdincremental-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.mdseverity-rubric— One consequence-based Critical, High, Medium, Low scale for every finding and gate; classifying a finding or deciding whether a review round passes → .claude/skills/shared/protocols/severity-rubric.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.mdui-intent-layer— Tech-agnostic UI intent layer in every UI-bearing spec; writing a spec for a feature with a user interface → .claude/skills/shared/protocols/ui-intent-layer.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
IMPORTANT MUST ATTENTION for non-trivial bugs, failed verification, regression fixes, behavior-changing code or unclear code flow, trace backward from the observed output through every feeder path before fixing. Establish hypotheses, the authoritative invariant owner and forward proof; retain validation at untrusted boundaries. Ordinary artifact review or graph lookup alone does not trigger a debugging workflow.
- MANDATORY Resolve the active Goal Contract BEFORE work (active plan
goal.md→<plans root>/goals/{YYMMDD-HHmm}-{slug}/goal.md, plans root defaultplansand overridable via adocsRoots.plans.pathentry indocs/project-config.json→ create from current request) and read saved success criteria before editing. - MANDATORY Append iteration evidence after execution; emit a Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before reporting PASS; loop on validated FAIL; escalate repeated no-progress or blockers. NEVER store secrets in goal files.
- MANDATORY For UI-bearing specs, author/maintain the tech-agnostic interaction-surface layer (views with information priority now/later/not-here and container role + navigation map + observable states + user-action flows), resolving it through the configured profile's intent/evidence roles and logical IDs; an unresolved owner, role, ID, carrier, or link stays
UNKNOWN/BLOCKED. Strict portable fallback — only when neither config nor local references declares a native artifact contract: trace each flow to the defaultUS-/OP-/BR-IDs and record the companion artifact in thedesign_spec:/mockup:frontmatter keys. Name ZERO frameworks/routes/CSS/component classes; skip ONLY for backend-only features with a stated reason.
- MANDATORY Classify every finding Critical/High/Medium/Low by consequence using the affected asset, shipped impact, exposure, reversibility, evidence location, and confidence; Critical/High/MEDIUM remain actionable under the round bar, while LOW is recorded/deferred from round 2 onward.
- MANDATORY A finding names a reachable trigger path (caller, input, state or event that reaches the defect) and a consequence; an unreachable concern is an observation, and unsettled reachability is
NOT VERIFIABLEonly when the concern would be MEDIUM or higher (an observation otherwise) — never a speculative LOW. - MANDATORY Keep binary gates separate from severity: a failed test, security must-fix, required artifact, or parity check blocks at every round and is never relabeled LOW.
- MANDATORY Score-based skills (sre 0-2, perf two-axis) map onto the same four tiers — no parallel severity vocabulary.
- 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: Deliver a well-defined feature whose reviewed canonical spec matches the implementation, verified tests and converged change review.
IMPORTANT MUST ATTENTION Main route: triage and activate → investigate → spec discovery → domain analysis → design rationale review (real alternatives only) → spec authoring → scenarios → explore mockup → test specs → test-spec review → clarification → plan (with its own validation interview) → execute (code and tests together) → QC seed data → missing integration tests → spec sync → static change review → integration verification → E2E → remaining test tiers → demo → close → handoff. Registry conditions govern optional steps; record their skip reasons.
IMPORTANT MUST ATTENTION triage size, kind and risk FIRST — depth follows risk and ambiguity, not file count; record the triage and every deviation.
IMPORTANT MUST ATTENTION gates never flex: tests green in THIS run · nested $workflow-review-changes converged inline · Feature Spec re-verified and synced when behavior changed · Goal Satisfaction matrix at $workflow-end.
IMPORTANT MUST ATTENTION spec before the first $plan, test specs reviewed before $plan --mode=execute; a BLOCKED Plan Gate stops the build.
IMPORTANT MUST ATTENTION large ideas embed the five-field large_idea_decomposition; this workflow never creates a roadmap artifact.
IMPORTANT MUST ATTENTION cite file:line evidence with confidence >80% to act; tests name the invariant they guard and fail when it breaks.