@ikon85/agent-workflow-kit 0.29.0 → 0.30.0

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/.claude/skills/skill-manifest.json

@@ -1,8 +1,37 @@
 {
   "schema_version": 1,
   "description": "Public skill classification and publishing SSOT.",
+  "readiness": {
+    "contractVersion": 1,
+    "capabilities": {
+      "issueTracker": { "evidence": { "type": "sentinel", "paths": ["docs/agents/issue-tracker.md"], "allowLegacy": true } },
+      "triageLabels": { "evidence": { "type": "sentinel", "paths": ["docs/agents/triage-labels.md"], "allowLegacy": true } },
+      "managedBoard": { "allowNotApplicable": true, "evidence": { "type": "board-profile", "paths": ["docs/agents/board-sync.md"] } },
+      "specCompleteness": { "evidence": { "type": "sentinel", "paths": ["docs/conventions/spec-completeness.md"], "allowLegacy": true } },
+      "localCiRecipe": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/local-ci.md"], "allowLegacy": true } },
+      "projectReleaseProfile": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "validator": "project-release" } },
+      "securityAuditRunbook": { "evidence": { "type": "runbook-reference", "paths": ["docs/agents/skills/security-audit.md"], "allowLegacy": true } },
+      "prodTarget": { "evidence": { "type": "prod-section", "paths": ["CLAUDE.md", "AGENTS.md"] } },
+      "orchestrateWaveRecipe": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/orchestrate-wave.md"], "allowLegacy": true } },
+      "specCritiqueLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/spec-self-critique.md"], "allowLegacy": true } },
+      "codeReviewLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/code-review.md"], "allowLegacy": true } },
+      "verifySpikeLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/verify-spike.md"], "allowLegacy": true } },
+      "auditSkillsLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/audit-skills.md"], "allowLegacy": true } },
+      "worktreeRecoveryLayer": { "evidence": { "type": "sentinel", "paths": ["docs/agents/skills/git-worktree-recover.md"], "allowLegacy": true } },
+      "domainDocs": { "evidence": { "type": "sentinel", "paths": ["docs/agents/domain.md"], "allowLegacy": true } },
+      "censusChoice": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["census"] } },
+      "memoryLifecycle": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["memoryLifecycle"] } },
+      "worktreeLifecycle": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["worktreeLifecycle"] } },
+      "workflowAdvisories": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["workflowAdvisories"] } },
+      "safetyGuardrails": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["safetyGuardrails"] } },
+      "workflowSummary": { "evidence": { "type": "nonempty", "paths": ["CLAUDE.md", "AGENTS.md"] } },
+      "locProfile": { "evidence": { "type": "json", "paths": ["docs/agents/max-lines-allowlist.json"] } },
+      "kitOriginHint": { "evidence": { "type": "json", "paths": ["docs/agents/workflow-capabilities.json"], "required": ["kitOriginHint"] } }
+    }
+  },
   "skills": {
     "to-prd": {
+      "readiness": { "required": ["issueTracker", "managedBoard"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -13,6 +42,7 @@
       "provenance": "matt-pocock"
     },
     "to-issues": {
+      "readiness": { "required": ["issueTracker", "managedBoard", "specCompleteness"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -51,6 +81,7 @@
       "provenance": "own"
     },
     "wrapup": {
+      "readiness": { "optionalBlocks": { "deployReport": "prodTarget" } },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -61,6 +92,7 @@
       "provenance": "own"
     },
     "verify-spike": {
+      "readiness": { "optionalBlocks": { "projectPlacement": "verifySpikeLayer" } },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -81,6 +113,7 @@
       "provenance": "own"
     },
     "spec-self-critique": {
+      "readiness": { "optionalBlocks": { "projectEnrichment": "specCritiqueLayer" } },
       "class": "generic",
       "publish": true,
       "surfaces": [
@@ -90,6 +123,7 @@
       "provenance": "own"
     },
     "code-review": {
+      "readiness": { "optionalBlocks": { "projectEnrichment": "codeReviewLayer" } },
       "class": "generic",
       "publish": true,
       "surfaces": [
@@ -118,6 +152,7 @@
       "provenance": "own"
     },
     "board-to-waves": {
+      "readiness": { "required": ["issueTracker", "managedBoard"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -138,6 +173,7 @@
       "provenance": "own"
     },
     "to-waves": {
+      "readiness": { "required": ["issueTracker", "managedBoard", "specCompleteness"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -187,6 +223,7 @@
       "provenance": "matt-pocock"
     },
     "triage": {
+      "readiness": { "required": ["issueTracker", "managedBoard", "triageLabels"] },
       "class": "vendored",
       "publish": true,
       "entryPoint": true,
@@ -327,6 +364,7 @@
       "provenance": "own"
     },
     "audit-skills": {
+      "readiness": { "optionalBlocks": { "projectChecks": "auditSkillsLayer" } },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -337,6 +375,7 @@
       "provenance": "own"
     },
     "local-ci": {
+      "readiness": { "required": ["localCiRecipe"] },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -347,6 +386,10 @@
       "provenance": "own"
     },
     "orchestrate-wave": {
+      "readiness": {
+        "required": ["issueTracker", "managedBoard"],
+        "optionalBlocks": { "projectRecipe": "orchestrateWaveRecipe" }
+      },
       "class": "generic",
       "publish": true,
       "entryPoint": true,
@@ -357,6 +400,7 @@
       "provenance": "own"
     },
     "git-worktree-recover": {
+      "readiness": { "optionalBlocks": { "projectRecovery": "worktreeRecoveryLayer" } },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -367,6 +411,7 @@
       "provenance": "own"
     },
     "security-audit": {
+      "readiness": { "required": ["securityAuditRunbook"] },
       "class": "generic",
       "publish": true,
       "entryPoint": false,
@@ -388,6 +433,7 @@
       "provenance": "own"
     },
     "project-release": {
+      "readiness": { "required": ["projectReleaseProfile"] },
       "class": "generic",
       "publish": true,
       "entryPoint": true,

package/README.md

@@ -348,6 +348,19 @@ concurrency-safe. Do not run manifest-mutating commands concurrently. Flags:
 
 ## Release notes
 
+### 0.30.0
+
+- added: `.claude/skills/skill-manifest.json`
+- added: `scripts/readiness.mjs`
+- added: `src/lib/atomicWrite.mjs`
+- added: `src/lib/manifest.mjs`
+- added: `src/lib/sentinel.mjs`
+- changed: `.agents/skills/codex-adapter-sync/SKILL.md`
+
+### 0.29.1
+
+- Metadata-only release.
+
 ### 0.29.0
 
 - added: `scripts/codex-exec.sh`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.29.0",
+  "kitVersion": "0.30.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -107,7 +107,7 @@
       "ownerSkill": "codex-adapter-sync",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "3a8ad73c4bfce8c01e561d2dc0c7f0e24d9ac85c1bb2c8c0194a2de278cd6a2d",
+      "sha256": "ae398e40308e6ad8d6091c418435e2dca8a4f67e526ab85efa88e8e57c0354c2",
       "mode": 420,
       "origin": "kit"
     },
@@ -2023,6 +2023,14 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/skill-manifest.json",
+      "kind": "doc",
+      "installRole": "consumer",
+      "sha256": "290cc3e847a10cb10b4ecb17cf0d45be0f60f95e96b7a70417b3e8da0a32e23c",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/spec-self-critique/scenarios.md",
       "kind": "skill",
@@ -2575,6 +2583,14 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "scripts/readiness.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "f5e8bc2e724f72d1aa9f94c4f8d87b8f4d3f9843797cd6ae59f48e563dc7c7fb",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
@@ -2727,6 +2743,22 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/atomicWrite.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "dbb971617ae641127857341a02cc029f30633ab5ef0c6efff2bab27b95794a9f",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "src/lib/manifest.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "171eba2662054379c40c1c629110fa8e34353de72e136004b861b2ac6a4edc13",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/release-apply.mjs",
       "kind": "script",
@@ -2750,6 +2782,14 @@
       "sha256": "7d0a8da3740ed1eb79edb80f0eedb3cd1de47692d4886c6b119b39073a6468d1",
       "mode": 420,
       "origin": "kit"
+    },
+    {
+      "path": "src/lib/sentinel.mjs",
+      "kind": "script",
+      "installRole": "consumer",
+      "sha256": "f99d28d2053d55222650d2ca426509d3f56eec5ef70709bbf8c4a278bf80024e",
+      "mode": 420,
+      "origin": "kit"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {