@ikon85/agent-workflow-kit 0.30.0 → 0.32.0

package/.agents/skills/audit-skills/SKILL.md

@@ -23,6 +23,35 @@ skills the other steps rely on drift, and nothing fixes them unless a recipe doe
 Not for: rewriting a domain skill's content on demand (that is the skill itself),
 or auditing application code (a code review or a diagnosis does that).
 
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before enumerating skills, launching research subagents, or editing any skill,
+run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill audit-skills --json
+```
+
+- `ready`: continue silently with the generic audit and the active
+  `projectChecks` block.
+- `degraded`: keep the generic audit active, omit only `projectChecks`, and emit
+  exactly one concise summary: `Readiness degraded — inactive block
+  projectChecks (auditSkillsLayer: <state>). Run /setup-workflow, configure
+  docs/agents/skills/audit-skills.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability
+  plus the exact `/setup-workflow` recovery path.
+- Invalid evidence is always visible in that one summary; never interpret it as
+  an opt-out or invent project checks.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectChecks -->
+When `projectChecks` is active, read
+`docs/agents/skills/audit-skills.md` and apply its concrete class assignments,
+project-specific guard commands, and drift checks in addition to the generic
+recipe below.
+<!-- readiness:end -->
+
 ## Standing guards (run without this audit)
 
 Two automatic nets catch the most common drift classes before an audit — this
@@ -31,7 +60,7 @@ recipe complements them, it does not replace them:
 1. **A skill-sync test** — for any un-guessable enumeration a skill documents (a
    status→bucket map, a design-token list), a test parses the value out of the
    SKILL.md and asserts equality with the code constant. Drift breaks the build.
-   Your project layer names the concrete tests.
+   Run the concrete tests available in the repository.
 2. **The drift-hint hook** (`.claude/hooks/skill-drift-hint.py`) + a per-skill
    `SOURCES.txt`: at SessionStart it flags any skill whose declared source file
    is newer in git than its SKILL.md.
@@ -79,8 +108,9 @@ plus the `SOURCES.txt` files. Sort every skill into one of three classes:
    scripts or hooks with no `SOURCES.txt` and no hook net. No hook warns, so
    re-check them manually each audit.
 
-Your project layer assigns each concrete skill to a class — a completeness gate
-catches the next new skill that would otherwise stay invisible.
+Derive each concrete skill's class from the manifest, its `SOURCES.txt`, and the
+repository surfaces — a completeness gate catches the next new skill that would
+otherwise stay invisible.
 
 ### 2. Audit in parallel — one subagent per skill
 
@@ -129,8 +159,7 @@ alongside the Claude source), sync the mirror in the **same** change — otherwi
 the second surface rots silently. Mirror the body, but preserve each surface's
 own frontmatter: a mirror's `description` may be deliberately condensed, so never
 blind-copy the whole file over it. A `SOURCES.txt` is a plain anchor list and can
-be mirrored verbatim. Your project layer names the surfaces and the exact
-transform.
+be mirrored verbatim. Use the repository's declared surfaces and exact transform.
 
 ## Done
 

package/.agents/skills/board-to-waves/SKILL.md

@@ -8,6 +8,20 @@ disable-model-invocation: false
 
 **Survey the board → cluster open issues by theme → anchor stub issues.** Systematizes how Welle F came about: first look at what's open and what fits together, then form thematic waves. Result lands durably as an anchor issue on the board (GitHub = SSOT), not as a chat list.
 
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill board-to-waves --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `missing`, `pending`, and `invalid` remain distinct, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/board-to-waves`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/board-to-waves` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
+
 ## Pipeline Position
 
 ```

package/.agents/skills/code-review/SKILL.md

@@ -16,7 +16,26 @@ A code-review compares one diff against **two independent axes** — Standards a
 | "Why is this broken / slow?" (root-cause of a known defect) | `diagnose` |
 | "Clean this up — reuse, simplify, cut waste." (no bug-hunting) | a dedicated simplification pass |
 
-## Preflight (fail-fast, before either axis starts)
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before the diff preflight or either review axis, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill code-review --json
+```
+
+- `ready`: continue without a readiness message. Ready is silent.
+- `degraded`: keep the generic two-axis review active, omit only the inactive block `projectEnrichment`, and emit exactly one concise summary: `Readiness degraded — inactive block projectEnrichment (codeReviewLayer: <state>). Run /setup-workflow, configure docs/agents/code-review.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability plus the exact `/setup-workflow` recovery path.
+- Invalid is always visible: include the `invalid` capability state in the single summary and never treat it as an opt-out. Do not emit separate warnings later in the workflow.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectEnrichment -->
+When `projectEnrichment` is active, read `docs/agents/code-review.md` first. Apply its project-specific guidance about which sources count and how this method relates to adjacent tools already running in the environment.
+<!-- readiness:end -->
+
+## Diff preflight (fail-fast, before either axis starts)
 
 1. **Fixed point** — whatever the requester names: a SHA, branch, tag, `main`, `HEAD~N`. Missing → ask; do not guess.
 2. **Three-dot diff against the merge-base** — `git diff <fixed-point>...HEAD` (three dots, not two — two dots diffs tip-to-tip and pulls in unrelated upstream changes), plus the commit list: `git log <fixed-point>..HEAD --oneline`.
@@ -24,7 +43,7 @@ A code-review compares one diff against **two independent axes** — Standards a
 
 ## Axis 1 — Standards
 
-**Sources.** This repo's own documented conventions: a root convention file (`CLAUDE.md`/`AGENTS.md`/`CONTRIBUTING.md` — whichever this repo uses), any per-package convention files in a monorepo, a `docs/conventions/` folder. If `docs/agents/code-review.md` exists (this skill's project layer, seeded by `/setup-workflow`), read it first — it names exactly which sources count here and how this method relates to any other review tooling already running in this environment. Absent that file, gather the sources yourself from the repo root before reviewing.
+**Sources.** This repo's own documented conventions: a root convention file (`CLAUDE.md`/`AGENTS.md`/`CONTRIBUTING.md` — whichever this repo uses), any per-package convention files in a monorepo, and a `docs/conventions/` folder. Gather these generic sources from the repo root before reviewing.
 
 **Plus a Fowler-smell baseline** (*Refactoring*, ch. 3) — applies even when the repo documents nothing. Each smell is a **judgment call** (flag as "possible X"), never a hard violation:
 
@@ -61,4 +80,4 @@ A code-review compares one diff against **two independent axes** — Standards a
 
 ## Relationship to adjacent review tooling
 
-This skill governs one thing: a diff/branch/PR review split into Standards vs. Spec. It is not the only review-shaped tool an environment may have — a pre-code plan-review loop, a security-specific audit, a pure reuse/simplification pass, or a dedicated reviewer subagent can all coexist with it; each stays its own axis, not a replacement for this one. If this repo has seeded `docs/agents/code-review.md`, it names the concrete adjacent tools and how they relate; absent that, treat any other review tool you find as complementary unless it explicitly says otherwise.
+This skill governs one thing: a diff/branch/PR review split into Standards vs. Spec. It is not the only review-shaped tool an environment may have — a pre-code plan-review loop, a security-specific audit, a pure reuse/simplification pass, or a dedicated reviewer subagent can all coexist with it; each stays its own axis, not a replacement for this one. Without active project enrichment, treat any other review tool you find as complementary unless it explicitly says otherwise.

package/.agents/skills/git-worktree-recover/SKILL.md

@@ -20,11 +20,36 @@ discipline and its guards) didn't stop it.
 
 ## Precondition
 
-If your project has a prevention layer — a SessionStart warning on active
-worktrees, a pre-edit guard that blocks edits on the wrong branch — this skill
-handles the case where that layer did NOT prevent a misplaced commit. Your project
-layer names those guards (`docs/agents/skills/git-worktree-recover.md`, seeded as
-an empty stub by `/setup-workflow`).
+This generic recovery remains usable whether or not the project has prevention
+guards or a custom worktree setup command.
+
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before assessing refs or moving a branch, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill git-worktree-recover --json
+```
+
+- `ready`: continue silently with generic recovery and the active
+  `projectRecovery` block.
+- `degraded`: keep generic reflog recovery active, omit only
+  `projectRecovery`, and emit exactly one concise summary: `Readiness degraded
+  — inactive block projectRecovery (worktreeRecoveryLayer: <state>). Run
+  /setup-workflow, configure docs/agents/skills/git-worktree-recover.md, then
+  rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability
+  plus the exact `/setup-workflow` recovery path.
+- Invalid evidence is always visible in that one summary; never interpret it as
+  an opt-out or invent a project command.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectRecovery -->
+When `projectRecovery` is active, read
+`docs/agents/skills/git-worktree-recover.md` and apply its named prevention
+guards and exact worktree setup command around the generic recovery below.
+<!-- readiness:end -->
 
 ---
 
@@ -124,16 +149,12 @@ it.
 
 ## Phase 5 — Set up a worktree
 
-Set the recovered branch up cleanly in its own worktree. If your project has a
-worktree-setup command, use it (it typically runs `git worktree add`, installs
-deps and copies env files); otherwise:
+Set the recovered branch up cleanly in its own worktree. The generic fallback is:
 
 ```bash
 git worktree add <path> <recovered-branch>
 ```
 
-Your project layer names the exact command and what it copies.
-
 **Verify after setup:**
 
 ```bash

package/.agents/skills/kit-update/SKILL.md

@@ -34,12 +34,30 @@ release contain the same artifact.
    `npm test` command there, and activates only a verified candidate. A staging
    or verification failure leaves the installed tree byte-identical.
 
+   The staged candidate also adopts the current readiness schema without
+   invoking `setup-workflow`: it preserves explicit readiness decisions and
+   legacy project evidence, and seeds only newly introduced safe project-layer
+   stubs whose destinations are absent. Those generated consumer-owned paths
+   are destination-race checked and activate or roll back in the same
+   transaction as kit files and the consumer manifest. Never create project
+   data, infer an external fact, or manufacture `pending`/`not-applicable` to
+   make a capability appear ready.
+
 3. Read the terminal report. `aktuell` proves a second run found no upstream
    delta. A conflict report names and counts every category and leaves every
    consumer file untouched. Follow its recommendation and resolve each named
    conflict manually; never auto-merge, delete a local edit, or silently choose
    the incoming copy.
 
+   Read all four availability categories alongside the file delta: newly
+   available skill core, newly degraded optional blocks, newly blocked skill
+   core, and still unresolved capability states. Missing readiness for genuinely
+   new behavior does not block a compatible kit update; only that behavior stays
+   unavailable. A compatible update must stop if it would make previously
+   available skill core unavailable. `--yes` answers only package reconciliation
+   questions and never supplies a readiness decision. Automated update pull
+   requests carry the same availability summary and remain manual-merge only.
+
    For each conflicted kit-shipped file, always ask the user whether the local
    edit is a generic improvement or project-specific; never decide or act
    automatically. For a generic improvement, offer to file an issue in the
@@ -74,4 +92,6 @@ release contain the same artifact.
 The update API reports `checking -> preview/awaiting_decision -> staging ->
 verifying -> applied | conflicted | failed | aborted`. `conflicted`, `failed`,
 and `aborted` never authorize partial activation. The existing manifest,
-three-way diff, and atomic-write seams remain the source of truth.
+three-way diff, and atomic-write seams remain the source of truth. A failure
+also names its transaction phase and whether consumer state stayed unchanged or
+was rolled back.

package/.agents/skills/local-ci/SKILL.md

@@ -20,6 +20,22 @@ live in the **project layer** for this skill (its `docs/agents/skills/local-ci.m
 seeded as an empty stub by `/setup-workflow` and filled per project). This
 skeleton names the two profiles generically; run the two your project layer names.
 
+## Required readiness preflight
+
+Before running a guard, hook, test, or any other project command, run:
+
+```sh
+node scripts/readiness.mjs check --skill local-ci --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent: continue with
+the existing gate and its safety rules. For a `blocked` verdict, stop without
+running any guessed command and report `Local CI unavailable`, the
+`localCiRecipe` state (`missing`, `pending`, `not-applicable`, or `invalid`),
+and one recovery path: run `/setup-workflow`, then fill
+`docs/agents/skills/local-ci.md` with the project's exact commands. Never infer
+commands from package scripts, hooks, CI configuration, or another repository.
+
 ## When
 
 - **Before opening ANY PR** → run the full local gate. Red → fix it, or defer a

package/.agents/skills/orchestrate-wave/SKILL.md

@@ -13,13 +13,46 @@ correctly, AFK. Subagents BUILD; **you** integrate + verify + land.
 The anchor, its sub-issues and the locked plan doc contain the verbatim contracts
 you must NOT paraphrase.
 
-> **Phase 0 probes a project layer.** Concrete tooling — exact test/verify
+## Readiness preflight — first
+
+<!-- readiness:optional-preflight:start -->
+Before reading from the issue tracker, claiming a wave, creating worktrees, or
+making any local or remote mutation, run this once from the project root:
+
+```bash
+node scripts/readiness.mjs check --skill orchestrate-wave --json
+```
+
+- `ready`: continue silently with the required tracker/board context and the
+  active `projectRecipe` block.
+- `degraded`: required tracker and managed-board evidence is ready, so keep the
+  complete generic orchestration fallback active, omit only `projectRecipe`,
+  and emit exactly one concise summary: `Readiness degraded — inactive block
+  projectRecipe (orchestrateWaveRecipe: <state>); using the generic
+  orchestration fallback. Run /setup-workflow, configure
+  docs/agents/skills/orchestrate-wave.md, then rerun this skill.`
+- `blocked`: `STOP` before tracker access, dispatch, claims, worktrees, or other
+  mutation. Report `issueTracker=<state>` and `managedBoard=<state>`, then give
+  exactly one recovery path: **Run `/setup-workflow`, then rerun
+  `/orchestrate-wave`.** Never fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/orchestrate-wave` is
+  inapplicable without a managed board. This is a terminal project decision,
+  not invalid evidence and not a partially active mode.
+- Invalid evidence is always visible and never treated as an opt-out.
+<!-- readiness:optional-preflight:end -->
+
+<!-- readiness:block projectRecipe -->
+> **Phase 0 consumes the active project recipe.** Concrete tooling — exact test/verify
 > commands, a DB/tunnel setup, a headless login recipe, brand checks, deploy
 > lockstep — is project-specific and lives in a **project layer** this skill reads
 > at runtime, not in this skeleton. The skeleton names the layer's sections
 > (`§Setup`, `§Builder Commands`, `§Builder Hard Rules`, `§Integration Suites`,
 > `§Verify Recipe`, `§Headless Login`, `§Landing`) and falls back to generic
 > instructions when the layer is absent. See **Phase 0**.
+>
+> When `projectRecipe` is active, read the filled project layer before applying
+> any phase-specific command below.
+<!-- readiness:end -->
 
 ## Standing rules (all phases)
 
@@ -59,15 +92,11 @@ you must NOT paraphrase.
 1. **Read everything**: the anchor body, every sub-issue body (each has a Handoff
    block: scope, blast-radius, live-verify, PR line), and the locked plan /
    plan-review doc in the planning worktree (file-exact).
-2. **Probe the project layer.** Read the project layer doc for this skill (the
-   consumer's `docs/agents/skills/orchestrate-wave.md` or the path your project
-   uses). If its `§`-sections carry **filled** content, follow the project recipe
-   wherever a phase below points at a `§`-section. If the file is only a
-   `setup-workflow` sentinel stub (empty headings, no real content) or absent,
-   treat the layer as **ABSENT** → use the generic fallback in each phase and warn
-   **once** that `/setup-workflow` plus project maintenance fill the layer (the
-   commands/tunnel/login can't be guessed). Never treat an empty heading as a
-   verify recipe.
+2. **Select exact commands or the generic fallback.** If the readiness result
+   activated `projectRecipe`, use the loaded filled recipe wherever a phase below
+   points at a `§`-section. Otherwise use each phase's generic fallback; the
+   preflight's single degraded summary is the only warning. Never guess a project
+   command, tunnel, login, or verify recipe.
 3. **Preflight — refuse a wave already in flight, otherwise claim it.** Before
    dispatch, inspect all three same-machine collision signals: **(a)** an existing
    `wave-active/<anchor>` tag; **(b)** any slice branch ahead of the wave's current
@@ -88,10 +117,10 @@ you must NOT paraphrase.
    tunnel or service the live-verify depends on. Absent layer → start whatever your
    live-verify environment requires before Phase 4.
 
-**Done when:** anchor + every sub-issue + plan read · project layer probed
-(filled → project recipe; stub/absent → generic + one-time warning) · preflight
-clean + this run's local claim planted · wave branch ff'd to `origin/main` + deps
-installed · project setup steps running.
+**Done when:** anchor + every sub-issue + plan read · readiness result consumed
+(active `projectRecipe` → exact recipe; inactive → generic fallback) · collision
+preflight clean + this run's local claim planted · wave branch ff'd to
+`origin/main` + deps installed · project setup steps running.
 
 ## Phase 1 — Disjointness recon (the load-bearing step)
 

package/.agents/skills/project-release/SKILL.md

@@ -9,6 +9,24 @@ Prepare a consumer-owned multi-package release through the kit's shared
 SemVer, preview, and transactional apply engine. This skill changes only the
 profiled version files. It does not commit, tag, push, publish, or merge.
 
+## Required readiness preflight
+
+Before previewing a release or changing any version file, run:
+
+```sh
+node scripts/readiness.mjs check --skill project-release --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent and hands
+execution to `scripts/project-release.mjs`; the helper remains the authority
+for preview, confirmation, validation, and transactional apply. For a
+`blocked` verdict, stop without invoking that helper or changing files and
+report `Project Release unavailable`, the `projectReleaseProfile` state
+(`missing`, `pending`, `not-applicable`, or `invalid`), and one recovery path:
+run `/setup-workflow`, then fill the `projectRelease` section in
+`docs/agents/workflow-capabilities.json`. Never infer packages, version files,
+tag prefixes, or versions.
+
 ## Profile contract
 
 Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and

package/.agents/skills/security-audit/SKILL.md

@@ -13,6 +13,24 @@ generic runbook structure ships as a template you copy and fill:
 your actual stack, and keep it as the checklist single source of truth. Read your
 filled runbook first.
 
+## Required readiness preflight
+
+Before reading application code, creating a tracking issue, launching either
+model, or writing audit scratch files, run:
+
+```sh
+node scripts/readiness.mjs check --skill security-audit --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent: continue with
+the existing two-model procedure and all human approval gates. For a `blocked`
+verdict, stop without starting an audit or mutating repository or remote state
+and report `Security Audit unavailable`, the `securityAuditRunbook` state
+(`missing`, `pending`, `not-applicable`, or `invalid`), and one recovery path:
+run `/setup-workflow`, then fill `docs/agents/skills/security-audit.md` and the
+project runbook it references. Never guess the stack, security scope, commands,
+tracking anchor, or board wiring.
+
 **Scope guard:** code + config only. Infrastructure (firewall, exposed ports,
 TLS, SSH, backups) is audited **separately** — an exposed database port beats any
 code fix. Keep the two audits apart.

package/.agents/skills/setup-workflow/SKILL.md

@@ -331,7 +331,36 @@ Seed `## Workflow` from [workflow-overview.md](./workflow-overview.md) when the
 
 > `wrapup` and live-verify reference where this project deploys (host, command, URL). It lives in the `## Prod` block of CLAUDE.md/AGENTS.md, not a separate file.
 
-Ask for the deploy target in plain terms (where does this ship, how is it deployed, what's the live URL?). Record it for the `## Prod` block (Write step). If the user has no deploy target, skip — do not invent one.
+First run `node scripts/readiness.mjs check --skill wrapup --json`. If
+`prodTarget` is `ready`, adopt the evidence, clear any superseded pending
+decision with `node scripts/readiness.mjs decision clear prodTarget`, and do
+not ask again. Malformed or divergent `## Prod` evidence is `invalid`: leave
+all instruction files untouched, show the conflict, and stop this section
+until the user resolves it.
+
+For a missing or pending target, ask where this ships, how it is deployed, and
+what the live URL is. Offer only the bounded choices permitted by the readiness
+catalog:
+
+- **Configure now** — collect a non-empty host/platform, deploy command or
+  trigger, and live URL. Preview the exact local `## Prod` replacement for
+  every applicable existing Claude/Codex instruction surface and obtain
+  approval before writing it. Any external mutation retains its own separate
+  preview and approval; approving the local block never approves repository,
+  hosting, DNS, or deployment changes.
+- **Configure later** — run
+  `node scripts/readiness.mjs decision set prodTarget pending`; create or alter
+  no `## Prod` block, and report exactly:
+  `wrapup.deployReport omitted (prodTarget pending)`.
+- **Not applicable** — offer only when the manifest catalog entry has
+  `allowNotApplicable: true`; record it with `readiness.mjs decision set` and
+  deactivate the dependent block (or the whole skill when the declaration
+  requires the capability). `prodTarget` does not permit this choice, so never
+  offer it for Prod.
+
+Ready and terminal `not-applicable` choices are not re-asked. A pending choice
+remains deliberately retryable so a later `setup-workflow` run can take the
+Configure-now path. Never invent a deploy target.
 
 ### 8b. Section H — Size-Profil (optional LoC-offender gate, non-interactive)
 
@@ -391,6 +420,14 @@ For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reco
 - If **neither** exists → ask the user which surface(s) to create (**default `CLAUDE.md`**), then write there.
 - If a `## Workflow` block already exists → skip it; this block is often repo-specific.
 - If an `## Agent skills` / `## Prod` block already exists → update its contents in-place; never duplicate or clobber surrounding user content.
+- For Configure now, apply the approved `## Prod` preview to every applicable
+  existing surface as one coherent local change. Preserve each file's
+  `## Workflow` and `## Agent skills` blocks byte-for-byte, including spacing,
+  and leave all unrelated setup blocks untouched. Re-read every written Prod
+  body and run `node scripts/readiness.mjs check --skill wrapup --json`; all
+  surfaces must agree and `activeBlocks` must be exactly `["deployReport"]`.
+  Only then clear a prior `prodTarget` decision. A partial write is not ready:
+  restore the previewed surface set before reporting the section complete.
 
 `## Workflow` block:
 
@@ -411,7 +448,7 @@ Use [workflow-overview.md](./workflow-overview.md) verbatim as the generic seed.
 [one-line summary — single- or multi-context]. See `docs/agents/domain.md`.
 ```
 
-`## Prod` block (only if Section F produced a deploy target):
+`## Prod` block (only if Section G's Configure-now path produced a deploy target):
 
 ```markdown
 ## Prod

package/.agents/skills/spec-self-critique/SKILL.md

@@ -11,15 +11,24 @@ A portable, structural self-review pass over a freshly written spec/plan. The **
 
 - After a spec was written/edited (a `SPEC.md` / `PLAN.md`, or a spec/design doc), BEFORE the user-review gate.
 
-## Step 0 — Project-layer probe
+## Readiness preflight — first
 
-First, check whether a project layer exists: from the project root, look for `docs/agents/skills/spec-self-critique.md`.
+<!-- readiness:optional-preflight:start -->
+Before any other step, run this once from the project root:
 
-- **Present** → **full pass**: run the 12 generic checks AND apply the per-point enrichment that file defines (incidents, grep patterns, extra sub-checks).
-- **Absent** → **base pass**: run the 12 generic checks only, then add this one-line warning to the summary:
-  > ⚠ No project layer found (`docs/agents/skills/spec-self-critique.md`) — only the generic base checks ran. `/setup-workflow` creates the layer; it fills in project-specific content via `/retro`.
+```bash
+node scripts/readiness.mjs check --skill spec-self-critique --json
+```
+
+- `ready`: continue without a readiness message. Ready is silent.
+- `degraded`: keep the generic 12-point critique active, omit only the inactive block `projectEnrichment`, and emit exactly one concise summary: `Readiness degraded — inactive block projectEnrichment (specCritiqueLayer: <state>). Run /setup-workflow, configure docs/agents/skills/spec-self-critique.md, then rerun this skill.`
+- `blocked`: stop before continuing and report the non-ready required capability plus the exact `/setup-workflow` recovery path.
+- Invalid is always visible: include the `invalid` capability state in the single summary and never treat it as an opt-out. Do not emit separate warnings later in the workflow.
+<!-- readiness:optional-preflight:end -->
 
-> **Routing — keep this skeleton clean.** Project-specific checks, incidents, and grep patterns belong in the project layer (`docs/agents/skills/spec-self-critique.md`), **NOT here**. `/retro` appends new project-specific lore to the project layer, never into this generic skeleton.
+<!-- readiness:block projectEnrichment -->
+When `projectEnrichment` is active, read `docs/agents/skills/spec-self-critique.md` and apply its per-point enrichment, including project-specific incidents, grep patterns, conventions, and extra sub-checks. Project-specific checks belong in that layer, **not here**; `/retro` appends new project-specific lore there rather than into this generic skeleton.
+<!-- readiness:end -->
 
 ## Altitude — a portable kit concept
 
@@ -63,7 +72,7 @@ Self-Critique complete — <N> corrections:
 - ...
 ```
 
-or, if none were needed: `Self-Critique complete — no corrections needed.` (append the Step-0 layer-absent warning if it applied). THEN ask the user-review question.
+or, if none were needed: `Self-Critique complete — no corrections needed.` THEN ask the user-review question.
 
 ## The 12-point checklist
 

package/.agents/skills/to-issues/SKILL.md

@@ -9,7 +9,19 @@ description: "Break a plan, spec, or PRD into independently-grabbable issues on
 
 Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-workflow` if not.
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill to-issues --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-issues`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/to-issues` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
 
 ## Process
 

package/.agents/skills/to-prd/SKILL.md

@@ -10,6 +10,20 @@ description: "Turn a locked plan (PLAN.md in the worktree, conversation context,
 
 Takes an **already-locked plan** and publishes it as a **Draft-PRD issue**. **Never invents requirements** — only synthesizes what's already decided. Pipeline: `board-to-waves → grill(-with-docs) → to-prd → to-issues`. The **grill sits upstream**; to-prd writes the PRD after the grill. **Slicing + promotion to an anchor (cluster/Wave, child link) = `to-issues`** (future), not here.
 
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill to-prd --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `missing`, `pending`, and `invalid` remain distinct, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-prd`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/to-prd` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
+
 Board constants (project node, field/status IDs) + helpers live **consumer-side**: read `docs/agents/board-sync.md` from the project root + use the helper `scripts/board-sync.py` (missing → `/setup-workflow` scaffolds the project layer). Issue body **always** via `--body-file` (inline `--body` with backticks/parens crashes bash).
 
 ## 1. Input — source-agnostic

package/.agents/skills/to-waves/SKILL.md

@@ -14,6 +14,20 @@ Takes a **Program-PRD** — the native Sub-Issue anchor over a multi-wave progra
 The **grill and to-prd sit upstream**; to-waves runs once the Program-PRD exists.
 It **never invents structure** — it only unfolds what the plan already decided.
 
+<!-- readiness:required-preflight:start -->
+## 0. Required readiness preflight
+
+This is the first executable workflow step. From the project root, before any remote write or other `gh`/`board-sync.py` command, run this read-only check:
+
+```bash
+node scripts/readiness.mjs check --skill to-waves --json
+```
+
+- `verdict=ready`: continue with the existing workflow without announcing the check. **Ready is silent.**
+- `verdict=blocked`: `STOP` before any mutation. Report every required capability as `<capability>=<state>` so `issueTracker`, `managedBoard`, and `specCompleteness` failures — including distinct `missing`, `pending`, and `invalid` states — stay visible, then give exactly one recovery path: **Run `/setup-workflow`, then rerun `/to-waves`.** Do not fall back to bare tracker or board commands.
+- `managedBoard=not-applicable`: `STOP` and report that `/to-waves` is **inapplicable** for a project that deliberately has no managed board. This is a terminal project decision, not invalid evidence and not a partially active mode.
+<!-- readiness:required-preflight:end -->
+
 Board constants (project node, field/status IDs) + helpers live **consumer-side**:
 read `docs/agents/board-sync.md` from the project root + use the helper
 `scripts/board-sync.py` (missing → `/setup-workflow` scaffolds the project layer).
@@ -36,8 +50,8 @@ target, an anchor is already a single wave.
 
 ## 2. Parse + validate — the graph preflight
 
-Run the graph preflight first — it is **read-only** (a single board read, zero
-mutations):
+After the required readiness preflight, run the graph preflight before preview or
+publication — it is **read-only** (a single board read, zero mutations):
 
 ```bash
 python3 scripts/board-sync.py validate-graph --issue <prd#>

package/.agents/skills/triage/SKILL.md

@@ -14,6 +14,30 @@ Every comment or issue posted to the issue tracker during triage **must** start
 > *This was generated by AI during triage.*
 ```
 
+## Required readiness preflight
+
+Before reading from or writing to the issue tracker, labels, or board, run:
+
+```sh
+node scripts/readiness.mjs check --skill triage --json
+```
+
+Treat the result as authoritative. A `ready` verdict is silent: continue with
+the existing triage flow and all of its confirmation gates. For a `blocked`
+verdict, stop without querying or mutating the issue tracker and report
+`Triage unavailable`, the exact state (`missing`, `pending`, `not-applicable`,
+or `invalid`), and the matching recovery path:
+
+- `issueTracker` → run `/setup-workflow`, then fill
+  `docs/agents/issue-tracker.md`.
+- `managedBoard` → run `/setup-workflow`, then configure
+  `docs/agents/board-sync.md`; `not-applicable` means this board-driven skill is
+  unavailable, not partially usable.
+- `triageLabels` → run `/setup-workflow`, then fill
+  `docs/agents/triage-labels.md`.
+
+Never guess a tracker, label, board, field, status, or fallback workflow.
+
 ## Reference docs
 
 - [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs