From bf7c5a657e172daee941396a262f796cd86f99bc Mon Sep 17 00:00:00 2001 From: Devlin Pajaron Date: Wed, 16 Sep 2026 15:29:44 +0800 Subject: [PATCH] Apply codex-kit v1.5.0 --- .agents/skills/docs-site-ui/SKILL.md | 34 +++++++++++++ .agents/skills/verify-source-changes/SKILL.md | 48 ++++++++----------- .../verify-source-changes/agents/openai.yaml | 4 +- .../references/focused-source-testing.md | 13 +++++ .../production-release-preparation.md | 23 +++++++++ .codex-kit-state.json | 8 ++-- AGENTS.md | 23 ++++++--- TEMPLATE_AGENTS.md | 36 ++++++++++++-- 8 files changed, 146 insertions(+), 43 deletions(-) create mode 100644 .agents/skills/docs-site-ui/SKILL.md create mode 100644 .agents/skills/verify-source-changes/references/focused-source-testing.md create mode 100644 .agents/skills/verify-source-changes/references/production-release-preparation.md diff --git a/.agents/skills/docs-site-ui/SKILL.md b/.agents/skills/docs-site-ui/SKILL.md new file mode 100644 index 0000000..efdef5c --- /dev/null +++ b/.agents/skills/docs-site-ui/SKILL.md @@ -0,0 +1,34 @@ +--- +name: docs-site-ui +description: >- + Implement or review appearance, layout, responsive behavior, accessibility, + or interaction changes in the common-utils-pkg Docusaurus documentation site. + Use for docs UI and visual-regression work, not utility source changes or + prose-only documentation edits. +--- + +# Documentation Site UI + +Before editing, inspect the closest same-purpose shipped Docusaurus feature and +reuse its patterns. The site uses Docusaurus classic and Infima; configuration +lives in `docusaurus.config.ts` and `sidebars.ts`, global theme overrides live in +`css/custom.css`, content lives in `docs-md`, and static assets live in `static`. +Prefer those existing extension points over swizzling or adding dependencies. + +Identify the analogue's tokens, spacing, typography, responsive behavior, +interaction states, and light/dark-mode treatment. Preserve semantic HTML, +accessible names and instructions, keyboard operation, logical focus, visible +focus, readable contrast, and non-color status cues. Use ARIA only when native +semantics are insufficient. + +Ask before deliberate divergence from an established analogue, changing a +written convention, or proceeding when precedents conflict or no trustworthy +analogue exists. Keep independently changeable UI concerns feature-local and +leave page or configuration entrypoints focused on composition. + +Run the narrowest relevant checks, then `pnpm run format:check` and +`pnpm run docusaurus:build`. When browser or screenshot tooling is available, +compare the changed view with its analogue at relevant sizes, themes, and states; +otherwise report that rendered comparison was unavailable. For visual-regression +tests under `src`, also use `$verify-source-changes` and follow its test-only +branch. diff --git a/.agents/skills/verify-source-changes/SKILL.md b/.agents/skills/verify-source-changes/SKILL.md index cb83490..fa573c1 100644 --- a/.agents/skills/verify-source-changes/SKILL.md +++ b/.agents/skills/verify-source-changes/SKILL.md @@ -1,36 +1,28 @@ --- name: verify-source-changes description: >- - Determine the next semantic version, update the changelog, regenerate derived - documentation and exports, then validate source changes in common-utils-pkg. - Use whenever files under src are added, updated, moved, or removed. + Test and validate changes under src in common-utils-pkg, adding release + preparation only when production source changes. Use whenever files under src + are added, updated, moved, or removed. --- # Verify Source Changes -## Workflow +Classify pending `src` changes by behavior, not merely path: -1. Confirm public utilities follow - `src//.ts`, use a camelCase named export, - include JSDoc, and have a colocated `.test.ts` file when behavior changes. -2. Inspect all pending source changes and classify the highest-impact SemVer - bump: - - **major**: any backward-incompatible public API or behavior change - - **minor**: a new public method or substantial backward-compatible update - - **patch**: a smaller backward-compatible fix, refactor, or code update -3. Calculate the next version from `package.json`. Update - `docs-md/changelog.md` with a concise entry under that version, merging into - an existing unreleased entry when present. Do not change the package version, - create a tag, or publish unless explicitly requested. -4. Run `pnpm run docusaurus:generate`. It rewrites `docs-md/api` and regenerates - `src/index.ts`. -5. Inspect changelog and generated changes. Keep only updates caused by the - source change. -6. Run the relevant focused Vitest test, then: - - `pnpm exec biome check .` - - `pnpm run test:ci` - - `pnpm run build` -7. Run `pnpm run docusaurus:build`. -8. Report the recommended version, changelog and generated files, and validation - results. If pnpm or a security policy blocks validation, do not bypass it or - change dependency policy; report the exact blocker. +- For test-only changes, read + [references/focused-source-testing.md](references/focused-source-testing.md) + and follow only that workflow. +- For production-source changes, read both + [references/focused-source-testing.md](references/focused-source-testing.md) + and + [references/production-release-preparation.md](references/production-release-preparation.md). +- For mixed test and production changes, follow both references. + +Test-only work does not require a SemVer recommendation, changelog entry, +documentation generation, export generation, build, or release checks unless +the test changes expose a required production change. + +Do not publish, tag, change the package version, alter dependency or security +policy, or bypass a policy failure unless explicitly requested. Report blockers +instead. diff --git a/.agents/skills/verify-source-changes/agents/openai.yaml b/.agents/skills/verify-source-changes/agents/openai.yaml index 9cc938c..d5a815d 100644 --- a/.agents/skills/verify-source-changes/agents/openai.yaml +++ b/.agents/skills/verify-source-changes/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Verify Source Changes" - short_description: "Version, document, and verify source changes" - default_prompt: "Use $verify-source-changes to version, document, and validate pending source changes." + short_description: "Test source changes and prepare releases when needed" + default_prompt: "Use $verify-source-changes to test pending source changes and prepare production changes for release." diff --git a/.agents/skills/verify-source-changes/references/focused-source-testing.md b/.agents/skills/verify-source-changes/references/focused-source-testing.md new file mode 100644 index 0000000..63e4a35 --- /dev/null +++ b/.agents/skills/verify-source-changes/references/focused-source-testing.md @@ -0,0 +1,13 @@ +# Focused Source Testing + +Read this reference for every change under `src`. + +1. Inspect the changed contract and nearby tests. Preserve existing assertions + unless behavior intentionally changes. +2. Add or update only focused colocated Vitest coverage for changed observable + behavior, regressions, meaningful boundaries, and costly failures. Use one + representative case per equivalent behavior; skip implementation details and + redundant permutations. +3. Run the narrowest relevant Vitest command. For broader production changes, + also run the repository checks required by the release-preparation reference. +4. Report the tests run and any unavailable or blocked validation. diff --git a/.agents/skills/verify-source-changes/references/production-release-preparation.md b/.agents/skills/verify-source-changes/references/production-release-preparation.md new file mode 100644 index 0000000..1d3f597 --- /dev/null +++ b/.agents/skills/verify-source-changes/references/production-release-preparation.md @@ -0,0 +1,23 @@ +# Production Release Preparation + +Read this reference only when production files under `src` are added, updated, +moved, or removed. + +1. Confirm public utilities follow + `src//.ts`, use a camelCase named export, + include JSDoc, and have a colocated `.test.ts` file when behavior changes. +2. Classify the highest-impact SemVer recommendation: + - **major**: backward-incompatible public API or behavior change + - **minor**: new public API or substantial backward-compatible update + - **patch**: smaller backward-compatible fix, refactor, or code update +3. Calculate the next version from `package.json`. Update + `docs-md/changelog.md` under that version, merging with an existing unreleased + entry when present. Do not change the package version unless explicitly + requested. +4. Run `pnpm run docusaurus:generate`, which replaces `docs-md/api` and + regenerates `src/index.ts`. Inspect generated and changelog changes, keeping + only changes caused by the production source work. +5. After the focused test, run `pnpm exec biome check .`, `pnpm run test:ci`, + `pnpm run build`, and `pnpm run docusaurus:build`. +6. Report the recommended version, changelog and generated changes, validation + results, and exact blockers. diff --git a/.codex-kit-state.json b/.codex-kit-state.json index bedf874..50e55ec 100644 --- a/.codex-kit-state.json +++ b/.codex-kit-state.json @@ -1,9 +1,9 @@ { "version": 1, "template": { - "availableHash": "f6a02cb2b17078ae108000975e2c2105b6e208e8f7cfeeb19e1765fb52d39b81", - "availableVersion": "1.1.5", - "appliedHash": "f6a02cb2b17078ae108000975e2c2105b6e208e8f7cfeeb19e1765fb52d39b81", - "appliedAt": "2026-08-14T05:46:22.901Z" + "availableHash": "6b9dffb93c7ef2e775904edd18de29d3f80cb21604b9aa2c0bf554d3ce5933a9", + "availableVersion": "1.5.0", + "appliedHash": "6b9dffb93c7ef2e775904edd18de29d3f80cb21604b9aa2c0bf554d3ce5933a9", + "appliedAt": "2026-09-16T07:28:37.117Z" } } diff --git a/AGENTS.md b/AGENTS.md index e915031..5e6405b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,16 +34,21 @@ ## Changes And Verification +- Before work, classify the requested behavior and load only the project skills + and skill-owned references needed for that work and its validation. - Match existing structure and reuse existing types and helpers. Keep changes minimal, localized, and limited to the requested behavior. +- Keep shared configuration and behavior in one source of truth at the narrowest + shared scope. Do not change architecture, core module boundaries, or project + paradigms without explicit approval. - Add or update focused colocated Vitest tests for changed contracts, regressions, and meaningful boundaries, using one representative case per equivalent behavior. Preserve existing assertions unless behavior intentionally changes; skip redundant and implementation-detail cases. -- After adding, updating, moving, or removing source code, use the project - `$verify-source-changes` skill to determine the next SemVer version, update - `docs-md/changelog.md`, regenerate documentation and exports, then inspect - generated changes and run the required checks. +- For changes under `src`, use `$verify-source-changes`; it routes test-only + work to focused testing and production-source work to testing plus release + preparation. +- For Docusaurus appearance or interaction work, use `$docs-site-ui`. - Do not use `format` or `fix` scripts for read-only validation because they rewrite files. Inspect generated changes after build or documentation generation. @@ -62,7 +67,13 @@ - `TEMPLATE_AGENTS.md` is a staged reusable reference; active guidance lives in this file and applicable project skills under `.agents/skills`. +- Read and preserve `PLANS.md` when it exists. Create it only for real durable + product context, decisions, roadmap/status, or resume-worthy milestones; do + not invent history or use it as a per-change changelog. - When `codex-kit project status` reports `reconciliation required`, use the global `$codex-kit-reconcile-agents` skill. Preserve local rules, merge only - applicable reusable guidance, validate changes, and run - `codex-kit project mark-applied` only after validation succeeds. + applicable reusable guidance, and validate changes. Never run + `codex-kit project sync` on the user's behalf. Run + `codex-kit project mark-applied` only after an eligible user-run init or sync, + an initial `reconciliation required` status, and successful reconciliation + and validation. diff --git a/TEMPLATE_AGENTS.md b/TEMPLATE_AGENTS.md index 0adb230..c7b07e9 100644 --- a/TEMPLATE_AGENTS.md +++ b/TEMPLATE_AGENTS.md @@ -12,8 +12,29 @@ product context, and local conventions in the project's active `AGENTS.md`. priorities, deferred requirements, product or implementation decisions, and major completed milestones. +## PLANS.md Maintenance + +- Read and preserve an existing `PLANS.md` during initialization and template + reconciliation; semantically merge durable content instead of replacing it. +- Create `PLANS.md` only when repository evidence contains real roadmap items, + durable decisions, or resume-worthy completed work. Never invent or backfill + speculative history. +- Keep it concise, using sections such as current context, decisions, + roadmap/status, and major milestones. It is not a per-change changelog. +- Move roadmap or history misplaced in `AGENTS.md` into `PLANS.md` when the + content is durable, and keep `AGENTS.md` focused on always-on instructions. + ## Instructions And Skills +- Before planning, classify the requested work and select only the project + skills and supporting references required for that work and its necessary + validation. Do not load every available or linked guide preemptively. +- Route every task by narrow relevance. Representative examples: testing work + uses applicable testing guidance; UI appearance or interaction work uses + styling/UI guidance; visual-regression work may require both; unrelated + tooling uses neither. Load release or deployment guidance only when that + operation is requested or required. Apply the same classification to any + other project-specific workflow. - Keep `AGENTS.md` focused on durable, always-applicable repository context: architecture, conventions, commands, safety and authorization boundaries, verification expectations, and concise pointers to specialized workflows. @@ -33,6 +54,9 @@ product context, and local conventions in the project's active `AGENTS.md`. skill. - Each project skill must use valid YAML frontmatter with a clear `name` and a `description` that states when the skill should trigger. +- Put substantial conditional detail in a skill-owned Markdown reference only + when it improves selective loading. The owning `SKILL.md` must state exactly + when to read it; never replace actionable guidance with a bare link. ## Template Maintenance @@ -77,6 +101,9 @@ including local/template conflicts and any generalized template-worthy promotion. Keep critical safety, authorization, secrets, database, deployment, and destructive-operation rules always-on in `AGENTS.md`; extract only concrete conditional procedures into validated project skills. +Classify both existing and incoming guidance by task relevance, keep the +always-on baseline concise, and route conditional detail through narrowly +triggered skills and selectively read references. ## Core Behavior @@ -89,9 +116,12 @@ conditional procedures into validated project skills. - Work within imperfect architecture. If it prevents safe completion, stop, explain the limitation, propose the smallest viable design change, and wait for approval. Escalate blockers instead of bypassing them. -- Reuse existing constants, schemas, enums, shared types, and components before - creating duplicates. Add reusable domain values at their existing source of - truth instead of scattering magic strings. +- Keep identical configuration and behavior in one source of truth at the + narrowest shared scope. Reuse that owner across callers or features; create a + separate implementation or instance only when scope, lifecycle, or behavior + genuinely differs. Reuse existing constants, schemas, enums, shared types, + and components before creating duplicates. Add reusable domain values at + their existing source of truth instead of scattering magic strings. - Replace numeric literals that encode domain rules, limits, durations, units, or protocol values with descriptively named constants. Universally obvious structural values, such as basic indexes or empty-state values, may remain