@ikon85/agent-workflow-kit 0.29.1 → 0.31.0

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/codex-adapter-sync/SKILL.md

@@ -9,50 +9,128 @@ Use this skill when the user asks for a Codex adapter sync, Codex drift check,
 Claude-to-Codex migration check, or when changes to Claude-facing project
 knowledge may need to be reflected in Codex-facing files.
 
+## Audit mode (default)
+
+Audit is a read-only diagnosis from the current checkout. Inventory and compare
+the source and adapter surfaces, then report the exact proposed changes. Do not
+create or switch branches or worktrees, edit files, or change external state.
+
+## Apply mode
+
+Apply only when the user asked to update or fix the adapter. Create or reuse the
+correct issue or slice worktree before the first edit. Never apply adapter
+changes on `main`; move any accidental main-checkout diff into the worktree and
+leave the main checkout clean.
+
+## Model routing
+
+Default to inherited parent model configuration. Do not pin a model merely
+because the source workflow delegates, and do not invent model or role fields
+on a spawn call. The supported built-in agent names are `default`, `worker`, and
+`explorer`; custom agents declare overrides in their TOML files.
+
+When an explicit custom-agent model is genuinely justified, route by task
+shape:
+
+- `gpt-5.6-sol` for complex, open-ended judgment work.
+- `gpt-5.6-terra` for everyday tool-using development.
+- `gpt-5.6-luna` for clear, repeatable, high-volume work.
+
+Use `model_reasoning_effort` for a supported reasoning override. The family
+name `gpt-5.6` describes the family and is not a fourth concrete variant in
+this routing table. Keep user gates, security judgment, and approval decisions
+in the main thread.
+
 ## Scope
 
 Source side:
-- `CLAUDE.md`
-- `frontend/CLAUDE.md`
-- `backend/CLAUDE.md`
+- every repository instruction file matched by `**/CLAUDE.md`
 - `~/.claude/CLAUDE.md` when the user explicitly mentions global Claude
   instruction drift or global Claude changes
 - `.claude/skills/`
 - `.claude/agents/`
+- Claude hook declarations and implementations
 - `.gitignore`
 
 Codex adapter side:
-- `AGENTS.md`
+- every repository instruction file matched by `**/AGENTS.md` or
+  `**/AGENTS.override.md`
 - `.agents/skills/`
-- `.codex/config.toml`
+- every trusted project config layer matched by `**/.codex/config.toml`
 - `.codex/agents/`
+- Codex hook declarations
 - `.gitignore`
 
+## Inventory
+
+Derive a fresh, counted inventory from the repository root; do not assume only
+known package names or root-level files. Include:
+
+- arbitrary nested `**/CLAUDE.md`, `**/AGENTS.md`, and
+  `**/AGENTS.override.md` instruction layers;
+- every `**/.codex/config.toml`, noting that Codex loads project config and
+  hooks only from trusted project layers;
+- `.claude/skills/**`, `.agents/skills/**`, `.claude/agents/**`, and
+  `.codex/agents/**`;
+- Claude hook definitions in `.claude/settings*.json` and implementations in
+  `.claude/hooks/**` as adaptation candidates;
+- Codex targets in `.codex/hooks.json` and inline `[hooks]` tables in each
+  active config layer; and
+- ignore rules and every skill reference, asset, script, template, and other
+  distributed support file, regardless of extension.
+
+For every relevant Claude hook behavior, record one explicit classification:
+**Codex-adapted** with its target, or **intentionally Claude-only** with the
+reason. Never port hooks blindly.
+
+## Custom-agent validation
+
+Codex custom-agent files are standalone TOML config layers. Parse every
+`.codex/agents/*.toml` file and require non-empty string values for the required
+`name`, `description`, and `developer_instructions` fields. Validate supported
+optional `model` and `model_reasoning_effort` fields as strings when present,
+then let strict Codex config validation reject unsupported keys or values.
+Reject a file that is malformed, misses a required field, or uses the legacy
+schema. A README or no-op note is not a custom-agent TOML file.
+
+## Validation
+
+Run validation from the repository root and keep the evidence in the report:
+
+1. Run `codex --strict-config --version` from the root and from a representative
+   nested directory for every discovered project config layer. Any unknown
+   active key is a failure, not a warning to ignore.
+2. Validate skill metadata and loading with the repository's strict
+   skill-frontmatter guard when one is available, then start a fresh Codex
+   session and check that every enabled skill is discoverable without load
+   warnings.
+3. Parse and validate every custom-agent TOML file against the
+   Custom-agent validation section above; strict config validation must also
+   accept its supported optional fields.
+4. Use `git check-ignore --no-index` on `.codex/config.toml`, every
+   `.codex/agents/*.toml`, `.agents/skills/**`, `.codex/hooks.json`, and any
+   adapted hook implementation. A checked-in adapter target being ignored is a
+   failure; local state and override files should remain ignored.
+5. Resolve every path named by skill prose and verify that all references,
+   assets, scripts, templates, and other distributed support files exist. Run
+   the repository's all-file mirror-parity guard when available so non-Markdown
+   presence parity and Markdown body/`mirror-xform` parity are both checked.
+6. Recompute the dual-surface skill denominator from the manifest, compare all
+   distributed files in both trees, and report the fresh result as **X of Y**
+   mirrored skills. Do not reuse a remembered count.
+7. Enforce this repository's 1024-character description cap as a named
+   repository safeguard. It is not a Codex product limit; the local guard owns
+   the policy and must fail when a description exceeds it.
+
 ## Workflow
 
-1. Establish a worktree before making adapter changes — pick the mode by how
-   the sync was triggered:
-   - **In-current-worktree (default for a per-slice gate).** If you are already
-     in a non-main slice/feature worktree — e.g. invoked as the mandatory
-     `codex-adapter-sync` gate at the end of a skill-touching slice — sync the
-     adapter **here**, in that same worktree. Commit the adapter changes
-     alongside the slice and ship them in the slice's own PR. Do **not** spin up
-     a separate adapter branch or PR: a per-slice gate that demanded its own
-     worktree/PR would collide with the slice it is gating.
-   - **Dedicated adapter worktree.** Only when invoked standalone from the main
-     checkout (no active slice worktree): create or reuse a dedicated adapter
-     worktree before inventory or edits — your project's worktree helper (or
-     `git worktree add`) on an issue-anchored branch when an anchor exists, or a
-     `chore/codex-adapter-sync-<slug>` worktree for a deliberate no-issue chore
-     — and ship it through its own PR.
-   - Either way: never land adapter changes directly on `main`. Move any
-     accidental main-checkout adapter diff into the chosen worktree first, then
-     leave the main checkout clean.
-2. Inventory the source side and adapter side from inside that worktree. If
-   global Claude instructions are in scope, read them from the main thread but
-   keep personal overrides, secrets, and machine-local state out of the repo
-   diff.
-3. Compare project knowledge:
+1. Select the mode from the user's request. Audit in the current checkout. For
+   Apply, reuse the active non-main slice worktree when the sync gates that
+   slice; otherwise create or reuse a dedicated issue-anchored adapter worktree.
+2. Build the Inventory before proposing or making changes. If global Claude
+   instructions are in scope, inspect them without exposing personal overrides,
+   secrets, credentials, or machine-local state.
+3. Compare project knowledge and instruction precedence:
    - New or changed durable conventions in `CLAUDE.md` should be reflected in
      `AGENTS.md` only as concise adapter guidance or references.
    - Do not duplicate long `CLAUDE.md` sections into `AGENTS.md`.
@@ -62,26 +140,16 @@ Codex adapter side:
      Codex-facing adapter rule in `AGENTS.md` or a minimal safe Codex config
      change; do not copy personal style, identities, credentials, or long
      global sections.
-4. Compare skills:
+4. Compare every skill and distributed support file:
    - Important repo/domain/workflow skills from `.claude/skills/` belong in
      `.agents/skills/`.
    - Keep each `SKILL.md` and its support files together.
    - Do not copy skills into `.codex/skills/`.
    - Leave clearly Claude-only setup, hook, or personal/meta skills out unless
      the user explicitly wants them ported.
-   - Translate Claude-specific model delegation instead of copying it
-     literally (tier mapping per your routing doctrine; if the repo carries a
-     Codex mirror table in `AGENTS.md`, keep it in sync). In particular, Claude `Agent` dispatches with
-     `model: sonnet` should become Codex `spawn_agent` dispatches with the
-     appropriate `agent_type`; for mechanical coding/git work use a `worker`
-     subagent with `model: gpt-5.4-mini` and `reasoning_effort: low` unless the
-     source skill gives a stronger task-specific reason. Claude `opus` /
-     judgment-tier dispatches (subtle logic, review/verify verdicts) map to
-     `model: gpt-5.5` with `reasoning_effort: high` (verdicts never below
-     high). Translate Claude `effort:` params to the nearest
-     `reasoning_effort` value (`minimal|low|medium|high|xhigh`; Claude `max`
-     → `xhigh`). Keep user gates, security judgment, and approval decisions
-     in the main thread.
+   - Translate Claude-specific delegation rather than copying it literally.
+     Apply the Model routing section above only when an explicit custom-agent
+     override is justified; otherwise preserve inherited parent configuration.
    - Keep dual-surface generic/vendored skill bodies content-synced. When a
      Codex mirror must intentionally differ from the Claude source, bracket the
      source region and the Codex replacement with a matching transform marker
@@ -111,36 +179,30 @@ Codex adapter side:
      `chaseai-yt/grill-me-codex`, `docs/agents/skills/grill-with-docs-codex.md`)
      is not an escalation target and must NOT be rewritten — rewriting it would
      break attribution/a real link.
-5. Validate Codex skill frontmatter:
-   - `name` and `description` are required.
-   - Quote `description` when it contains colons, arrows, commas, or other
-     YAML-sensitive punctuation.
-   - Keep `description` under 1024 characters.
-   - Keep trigger detail in the body if the original Claude description is too
-     long.
-6. Compare agents:
-   - Claude agents are `.md` files under `.claude/agents/`.
-   - Codex agents are `.toml` files under `.codex/agents/`.
-   - Convert agent instruction bodies into `developer_instructions`.
-   - If no Claude agents exist, keep only a short README or no-op note.
-7. Compare config and ignore rules:
-   - Keep `.codex/config.toml` minimal and safe.
-   - Never add secrets, provider credentials, auth tokens, or local personal
-     overrides.
-   - Ensure `.gitignore` excludes local Codex state and override files while
-     allowing checked-in project config, agents, and skills.
-8. Before edits, show the exact files that will be created or changed.
-9. After edits, validate:
-   - `.codex/config.toml` parses as TOML.
-   - All `.agents/skills/*/SKILL.md` files load without Codex warnings.
-   - No skill description exceeds 1024 characters.
-   - `.codex/config.toml`, `.codex/agents/*.toml`, and `.agents/skills/**`
-     are not accidentally ignored.
-10. Prepare the branch for review:
-   - Commit the adapter changes on the worktree branch after checking for
-     secrets and ignored files.
-   - Push the branch and create or update a PR.
-   - Report the PR URL, changed files, skipped items, and verification results.
+5. Compare agents, hooks, config, and ignore rules:
+   - Claude agents are `.md`; Codex custom agents are `.toml` and must satisfy
+     Custom-agent validation.
+   - Classify each Claude hook behavior using the Inventory contract and check
+     Codex hook targets at every active trusted config layer.
+   - Keep `.codex/config.toml` minimal and safe. Never add secrets, provider
+     credentials, auth tokens, or local personal overrides.
+   - Ensure ignore rules exclude local Codex state and override files while
+     allowing checked-in config, agents, hooks, skills, and support files.
+6. In Audit mode, run every read-only Validation step that the checkout
+   supports and report the proposed file changes without mutating anything.
+7. In Apply mode, show the exact files to create or change before editing, make
+   only those changes, then run the complete Validation section. Prepare the
+   existing worktree branch for review: check for secrets and ignored files,
+   commit the adapter changes, push, and create or update its PR.
+
+Codex skill frontmatter must also satisfy these repository rules:
+
+- `name` and `description` are required.
+- Quote `description` when it contains colons, arrows, commas, or other
+  YAML-sensitive punctuation.
+- Enforce the Validation section's named description safeguard.
+- Keep trigger detail in the body if the original Claude description is too
+  long.
 
 ## Output
 

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/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#>