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-code-to-spec together with this skill. Call $start-workflow workflow-code-to-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
init-full:$investigate(core) →$plan(optional; conditional) →$plan --mode=validate(optional; conditional) →$spec [mode=init](core) →$spec [mode=tests](optional; conditional) →$work-item --mode=review --type=spec-tests --fix-loop(gate) →$docs-manager --mode=update(optional; conditional) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (3) → Specify (4; exit review-converged, spec-synced) → Close (2; exit run-closed)
- Mode
update:$workflow-review-changes --review-only(gate) →$spec [mode=update](core) →$spec [mode=tests](optional; conditional) →$work-item --mode=review --type=spec-tests --fix-loop(gate) →$spec [mode=sync](optional; conditional) →$docs-manager --mode=update(optional; conditional) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (1) → Specify (5; exit review-converged, spec-synced) → Close (2; exit run-closed)
- Mode
audit:$investigate(core) →$spec [mode=audit](core) →$why-review --validate-findings(gate) →$workflow-end(gate) →$watzup(optional; conditional) Phase todos: Discover (1) → Specify (2; exit review-converged, spec-synced) → 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.
[BLOCKING] Workflow steps follow the guided contract in
$start-workflow→ Step Execution Protocol:gatesteps are fixed; other steps may flex with a logged reason. [BLOCKING] Before each step or sub-skill call, update todo tracking: setin_progresswhen step starts, setcompletedwhen step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Quick Summary
Goal: Keep one canonical spec per capability aligned with implementation and test evidence: author from code (init-full), reconcile changes (update, default), or report staleness (audit).
Summary: Confirm mode and capability owners → triage scope → resolve the selected manifest → investigate/plan or review changes → author/update/audit → reconcile and review cases and changed spec intent (audit: validate the report's findings) → sync declared aids → refresh derived docs that embed the spec → outcome gates and close → handoff. Preserve native artifact contracts, full-chain evidence and bounded review convergence.
Key Rules: Code owns technical truth; specs own requirements and behavior. Create only declared derived aids, never a parallel authored tree. Confirm scope first; resolve the profile before writing; unknown coverage stays BLOCKED/UNKNOWN.
Use it when specs must be written from or reconciled with code: first-time specs for a capability or bucket, after significant code changes, onboarding/compliance handoff, before a migration, or a periodic health audit. Use a sibling instead when: no code exists yet → workflow-planned-work (idea-to-spec); one small spec edit → $spec or workflow-feature-spec; post-change sync inside a delivery run → workflow-spec-sync; only a derived index/ERD → $spec [mode=index].
IMPORTANT MANDATORY Steps: $workflow-review-changes --review-only -> $spec [mode=update] -> $spec [mode=tests] -> $work-item --mode=review --type=spec-tests --fix-loop -> $spec [mode=sync] -> $docs-manager --mode=update -> $workflow-end -> $watzup
That line is the default update sequence. Each mode resolves its own manifest (fingerprint + occurrence IDs) through $start-workflow before any task is created:
| Mode | When | Recommended sequence (gate in bold) |
|---|---|---|
init-full |
no canonical spec exists for the target scope | investigate → plan* → plan --mode=validate* → spec [mode=init] → spec [mode=tests]* → work-item --mode=review --type=spec-tests → docs-manager --mode=update* → workflow-end → watzup* |
update |
code changed, new requirement or task | workflow-review-changes --review-only → spec [mode=update] → spec [mode=tests]* → work-item --mode=review --type=spec-tests → spec [mode=sync]* → docs-manager --mode=update* → workflow-end → watzup* |
audit |
freshness check before a release or on a cadence | investigate → spec [mode=audit] → why-review --validate-findings → workflow-end → watzup* |
* = optional; apply the registry conditions and skip reasons below verbatim.
- init-full / plan: run when more than three capabilities are in scope, or the split strategy, naming or ownership was not confirmed at mode selection. Skip reason: "One to three capabilities whose names, owners and target paths the user confirmed at mode selection; the Coverage Ledger carries the split."
- init-full / plan --mode=validate: run when the plan step ran in this run. Skip reason: "The plan step did not run (one to three capabilities whose names, owners and target paths the user confirmed at mode selection), so there is no plan to validate; the mode-selection confirmation records those decisions."
- init-full / spec [mode=tests]: run when four or more capabilities fan out to spec sub-agents, or the init step could not write complete test cases with real source anchors. Skip reason: "The init step wrote every test case with its real source anchor."
- init-full / docs-manager --mode=update: run when a derived index, README or reference doc that embeds the new specs must be refreshed. Skip reason: "No derived index or reference doc embeds the new specs; the spec steps wrote the canonical owners."
- update / spec [mode=tests]: run when the change alters business-visible behavior, a public contract, or the test evidence of a specified capability. Skip reason: "A purely cosmetic change (styling, comments, configuration) with no behavioral or test-evidence impact."
- update / spec [mode=sync]: run when native case/evidence links or project-declared derived outputs changed in this cycle. Skip reason: "No case/evidence link or declared derived output changed in this cycle."
- update / docs-manager --mode=update: run when a derived index, README or reference doc that embeds the updated spec must be refreshed. Skip reason: "No derived index or reference doc embeds the updated spec; the spec steps wrote the canonical owner."
- every mode / watzup: run when the user asked for a session report or an HTML wrap-up, or the session spanned several workflows or prompts that need one consolidated handoff. Skip reason: "workflow-end printed the recap, or the short handoff when nothing was built, and every applicable outcome gate passed."
Contents
- Workflow Calls and Todo Bootstrap
- Quick Summary
- 1. Step 0 — Mode and Scope (MANDATORY FIRST)
- 2. Triage (sets depth, recorded in the run report)
- 3. Required Quality Gates (non-negotiable)
- 4. Recommended Skills
- 5. Orchestration Freedom
- 6. Memory, Reporting and Fix Path
- Prompt-Enhance Closing Anchors
- Closing Reminders
1. Step 0 — Mode and Scope (MANDATORY FIRST)
Resolve the configured business spec root and artifact contract, then suggest a mode: no current spec for the target → init-full; a diff touches an already-specified capability → update; an explicit audit/freshness request → audit. Map changed code to its capability owner through the App Bucket Mapping in the local spec-system-reference.md (reference-docs root from docsRoots.projectReference.path). For audit, choose the supported mode, capability names and target paths under SYNC:review-decision-autonomy and record the rationale; ask only for an indispensable missing fact or actual action authority. For non-audit modes, BLOCKING: confirm mode, capability names and target paths via ask user question tool before any other action.
2. Triage (sets depth, recorded in the run report)
| Scope | Signal | Strategy |
|---|---|---|
| Single capability (XS/S) | one feature or one diff | inline; no separate plan when names, owners and paths were confirmed at mode selection; plan --mode=validate only when naming or ownership is ambiguous |
| Single bucket (M) | one module/service, 2–10 capabilities | 2–3 confirmed capabilities run inline like XS/S; more than three, or an unconfirmed split, naming or ownership, plan one task per capability and validate that plan; 4–10 capabilities → one spec sub-agent per capability in ONE message |
| Multi-bucket / whole project (L/XL) | "all specs", several buckets | Coverage Ledger (below); groups of at most 10 capabilities per run, run sequentially across resumable sessions |
Split by independently nameable capabilities, never by line count; apply the native profile's cardinality rule (the >40 cases heuristic is portable-default only). Update-mode kinds: purely cosmetic change (styling, comments, config) → no case/evidence change; behavior or contract change → cases reconciled; user-facing behavior → interaction-intent refresh.
Coverage Ledger (BLOCKING for multi-bucket/whole-project). Enumerate every bucket × capability found by investigate, then write tmp/reports/code-to-spec-coverage-{date}.md with one row per capability: owner · capability · canonical spec path · intent · contracts · test/evidence coverage · chain trace · status (NOT STARTED → IN PROGRESS → SPEC DONE → REVIEWED). Update the row after each capability. Resume rule: after compaction or a new session read the ledger and the current task list FIRST, re-enumerate the business spec root, continue from the first non-REVIEWED row — never re-author a done capability, never re-run investigate or plan for enumerated buckets.
3. Required Quality Gates (non-negotiable)
| Gate | Evidence that proves it |
|---|---|
| Artifact profile resolved | Read docs/project-config.json (specRoots.business.path, workflowPatterns.featureDocTemplate, docsRoots.projectReference.path, specArtifacts), the configured template, local spec-system-reference.md and spec-principles.md before any author/update/audit step. A malformed or conflicting contract is BLOCKED. |
| Full vertical chain traced | Per capability: UI view/action → API → handler → domain rule → event → consumer/read model → UI outcome, reconciled by the $spec [mode=init] chain-reconciliation step — no orphan UI, no orphan operation, event and read-side closure. A BROKEN chain is a spec finding, never silently dropped. |
Three-way sync (spec-synced, modes that write the spec) |
Native intent/contract/acceptance roles ↔ configured cases/evidence ↔ executing test code agree; follow the local spec-system-reference.md, including its STATE MACHINE DATA ASSERT mandate. Each case names its Business Intent / Invariant Guarded, links to executing proof, and would fail if that intent broke. |
Spec review converged (review-converged) |
Writing modes: $work-item --mode=review --type=spec-tests on the cases and on the spec intent §1-7 the run authored or changed, including the BLOCKING M1-M7 gate: zero [UNVERIFIED] without an exclusion reason, complete role/evidence coverage, tech-term checks only on designated intent roles. Audit: $why-review --validate-findings validates the audit report's findings; the run stays read-only. |
| Change review (update mode) | $workflow-review-changes --review-only run INLINE in the main session: one validated pass with no source edits and no nested docs step; its report is the impact map for the spec update. A validated code defect (CODE-WRONG) is not encoded in the spec: the spec keeps the intended behavior, and the close handoff lists the defect with a workflow-bugfix or workflow-review-changes --fix-loop route. |
| Coverage complete (multi-bucket) | Every ledger row REVIEWED or carrying a recorded deferral reason; the run report and the close recap report {reviewed}/{total} capabilities. |
| Goal satisfied | Resolve the active Goal Contract at start (active plan goal.md, else a new goal under the plans root); append per-cycle evidence to its Iteration Log; emit the Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before $workflow-end. |
Run closed (run-closed) |
$workflow-end checked every outcome gate; in a writing mode $docs-manager --mode=update ran before it when a derived index, README or reference doc embeds the spec. |
Profile rules. The native profile or local artifact contract owns paths, section roles, identifiers, ownership and test/evidence carriers. Keep designated intent roles tech-agnostic; keep permitted technical detail in contract/evidence roles; mark unknown claims [UNVERIFIED], never blank. The portable form — {SPEC_ROOT}/{Bucket}/README.{Feature}.md, tech-free Sections 1–7 with the mandatory inline §5 Mermaid ERD and §6.2–§6.5 for UI-bearing features, Section 8 TC-{FEATURE}-{NNN} cases with GIVEN/WHEN/THEN, Business Intent / Invariant Guarded, Evidence: [Source: namespace/service/id], CoveredBy and status — applies only when neither exists. Missing or unmapped coverage is BLOCKED/UNKNOWN, never NOT-APPLICABLE or PASS.
4. Recommended Skills
Follow the selected mode table; read each step's skill before executing. Apply these depth and input decisions:
$investigate: init-full maps capability registry, entry points and both UI/backend ends; audit uses a lightweight trace. This establishes the ledger denominator and chain scope.$plan: init-full, when its registry condition above holds, plans one task per capability, core domain first; the current task list count must cover capability count before authoring. Otherwise the Coverage Ledger carries the split. Apply validation's registry condition above.$spec [mode=init|update|audit]: use the selected mode; update only impacted roles. Init writes the cases itself;spec [mode=tests]follows in init-full only for a sub-agent fan-out or missing source anchors. Tests mode checks existing IDs and preserves tested evidence. Each review's depth scales with case count.$spec [mode=sync]: reconcile changed case/evidence links or declared outputs. Use$spec [mode=index]alone when only a project-maintained derived index/ERD lags.$work-item --mode=dorand$work-item --mode=mockup: when making a new task implementation-ready; mockup only for UI/journey changes. Planned cases guide implementation and do not prove verified behavior.$docs-manager --mode=update→$workflow-end→$watzup: derived-doc refresh when a doc embeds the spec (writing modes only), outcome-gate closure with the recap, then$watzuponly when its registry condition holds.- Audit is read-only:
$why-review --validate-findingsvalidates the audit report, and nothing but the report is written.
UI intent (conditional): when changed code carries user-facing behavior, refresh the interaction-intent owner the profile declares and link its design-spec/mockup where the contract expects it (portable form: §6 View Inventory, Key UI States, per-story click-path with US-/OP-/BR- references). A profile with no UX owner → surface the gap; never invent a section.
New task / requirement update: map requirement → domain entities → capabilities; record planned intent in native roles with the profile's planned-state convention; add planned cases in the native carrier; review them with $work-item --mode=review --type=spec-tests. They are implementation guidance, not verified spec.
5. Orchestration Freedom
Choose inline/delegated execution, waves and batching at equal quality under $start-workflow; keep gates fixed and log allowed flex. Dependencies: investigate and plan precede authoring; a spec exists before it is reviewed; cases exist before their review; $workflow-review-changes --review-only runs inline in the main session; $docs-manager --mode=update, when it runs, follows the review fixes and precedes $workflow-end, which runs last. Recommended for 4+ capabilities: investigate + plan in the main context → spawn spec sub-agents (one per capability) in ONE message → barrier → spec [mode=tests] sub-agents in ONE message → main context assembles and reviews. Each brief carries capability name + bucket, output path, the resolved profile and its prose/evidence rules, the SYNC protocols (critical thinking, evidence, incremental persistence, cross-scope boundary), and "write each section immediately"; no sub-agent handles more than 3 capabilities.
6. Memory, Reporting and Fix Path
- One phase task per phase, one row per selected step and per capability; write the run report under
tmp/reports/FIRST and append per section — never hold findings in memory. - Findings are validated before fixing; fix only validated gaps that block the current round, in the owning spec role, then repeat the full
$work-item --mode=review --type=spec-testspass. Review loop: round 1 exits on zero open findings (LOW deferral); round 2 on zero CRITICAL/HIGH/MEDIUM with LOWs recorded as deferred; binary gates always block; cap 3 review rounds; escalate viaask user question toolon no progress. - Spec-loop discipline: derive property cases with boundary counter-cases for every hard invariant; protected core logic uses the mutation-score gate, not line coverage; feed uncovered behavior into both spec and tests through a dual-feedback ledger until no new gap or hidden rule remains.
- Audit output:
tmp/reports/spec-audit-{date}-{Bucket}.md— stale capabilities/roles, stale coverage %, priority order, validated by$why-review --validate-findings; the close handoff recommends anupdaterun scoped to the stale capabilities.
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.mdreview-decision-autonomy— Choose supported review decisions and ask before extending the round budget; running any review or audit skill or mode → .claude/skills/shared/protocols/review-decision-autonomy.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.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.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 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.
Prompt-Enhance Closing Anchors
IMPORTANT MUST ATTENTION workflow steps follow the guided contract in $start-workflow — gate steps are fixed; other steps may flex only with a logged reason
IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses
- 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.
MUST ATTENTION Decide supported review choices and recommendations, record the rationale, and finish without routine user questions. Keep round-limit extension, indispensable facts and actual action authority; preserve source coverage, validation, tests, read-only boundaries and budgets. Review decisions do not accept open risks or make a failed gate pass.
Closing Reminders
IMPORTANT MUST ATTENTION Goal: Keep one canonical spec per capability aligned with implementation and test evidence: author from code (init-full), reconcile changes (update, default), or report staleness (audit).
MUST ATTENTION Main steps: confirm mode/scope → triage → resolve manifest → investigate/plan or review changes → author/update/audit → reconcile/review cases and changed intent (audit: validate findings) → sync declared aids → derived docs when embedded → outcome gates/close → handoff. Apply optional steps by registry conditions and record exact skip reasons.
- [BLOCKING] Step 0 FIRST — confirm mode, capabilities and target paths via
ask user question tool; then triage by capability count and breadth; multi-bucket scope keeps the Coverage Ledger and clears the completeness gate ({reviewed}/{total}) before$workflow-end. - [BLOCKING] resolve the artifact profile before authoring; the portable eight-section/
TC-{FEATURE}-{NNN}form applies only when no native profile or local contract exists; unknown mappings stay BLOCKED. - [BLOCKING] trace the FULL vertical chain per capability and reconcile it;
$work-item --mode=review --type=spec-testsconverges with the M1-M7 gate (audit:$why-review --validate-findingson the report); update mode runs$workflow-review-changes --review-onlyinline in the main session;$docs-manager --mode=update, when it runs, precedes$workflow-end. - [BLOCKING] 4+ capabilities → one
specsub-agent per capability, all spawned in ONE message; after compaction read the ledger and the current task list first and never re-author a done capability. - MUST ATTENTION resolve the active Goal Contract at start and emit the Goal Satisfaction matrix before close; every case names the business intent it guards.
| Evasion | Required action |
|---|---|
| "The preview is the route" | Resolve the complete selected variant through $start-workflow. |
| "Tests pass, coverage is known" | Trace case intent to executing assertions; unresolved coverage stays BLOCKED/UNKNOWN. |