aiblueprint-cli 1.4.108 → 1.4.110

package/agents-config/skills/skill-manager/SKILL.md

@@ -1,171 +1,32 @@
 ---
 name: skill-manager
-description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, prompts, frontmatter, references, scripts, discovery, and predictable skill design.
+description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and skill discovery.
 ---
 
-# Skill Manager
+Write skills the way `$analyze`, `$plan`, `$implement`, `$code-review`, and `$verify` are written.
 
-Authoring guide for skills/rules across three agent platforms. All three share the same idea: a small markdown file with frontmatter, optional references, optional scripts. The discovery rules and frontmatter fields differ.
+## Target
 
-| Platform     | File                                          | Frontmatter fields                                       | Optional config              |
-| :----------- | :-------------------------------------------- | :------------------------------------------------------- | :--------------------------- |
-| Claude Code  | `<scope>/skills/<name>/SKILL.md`              | `name`, `description`, plus invocation/execution fields  | -                            |
-| Codex        | `<scope>/.agents/skills/<name>/SKILL.md`      | `name`, `description`                                    | `agents/openai.yaml`         |
-| Cursor       | `.cursor/rules/<name>.md` or `.mdc`           | `description`, `globs`, `alwaysApply`                    | `AGENTS.md` (no frontmatter) |
+- One job. Imperative. Every line changes behavior.
+- Body under ~40 lines unless the job is genuinely multi-branch.
+- Description 50–300 chars: capability first, then `Use when` + trigger words.
+- No README, changelog, or theory. No restating model defaults.
+- References only for platform or schema detail the body cannot hold. Name the file and when to open it.
+- User-only workflows: `disable-model-invocation: true`.
 
-Pick the platform first, then read the matching reference file:
+## Write
 
-- Claude Code → see [references/claude-code.md](references/claude-code.md)
-- Codex      → see [references/codex.md](references/codex.md)
-- Cursor     → see [references/cursor.md](references/cursor.md)
-- Description quality → see [references/description-recommandation.md](references/description-recommandation.md)
-- Skill-writing vocabulary → see [references/skill-writing-glossary.md](references/skill-writing-glossary.md)
+1. Confirm 2–3 trigger prompts with the user.
+2. Pick the platform. Default from the path: `.claude` → Claude, `.agents` → Codex, `.cursor` → Cursor. Ask if unclear.
+3. Write frontmatter, then the body: inspect → act → return → stop.
+4. Run `bun ~/.agents/skills/skill-manager/scripts/inspect-description.ts` on the skill root.
 
-If unsure which the user wants, ask. Default to Claude Code when working under `~/.claude/` or `.claude/`, Codex when under `~/.agents/` or `.agents/`, Cursor when under `.cursor/`.
+Personal skills live in `~/.agents/skills/<name>/`. Platform layout and frontmatter: [claude-code.md](references/claude-code.md), [codex.md](references/codex.md), [cursor.md](references/cursor.md). Description rules: [description-recommandation.md](references/description-recommandation.md).
 
-## Core principles (all platforms)
+## Audit
 
-### Optimize for predictability
+For each line: would removing it change behavior? Delete no-ops, duplicates, and stale rules. State the positive target; keep prohibitions only as hard guardrails.
 
-A skill should make the agent follow the same process on repeated runs, even when the outputs differ. Treat predictability as the root quality; token cost and maintainability improve when the process is explicit and lean.
+Online research: `$find-docs` for current technical docs; `$exa-search` for broader web research.
 
-### Concise is key
-
-The context window is shared with the system prompt, conversation, other skills' metadata, and the user request. Only add context the agent doesn't already have. Challenge each line: does it justify its tokens?
-
-### Match freedom to fragility
-
-- **High freedom** (prose instructions): multiple valid approaches, decisions depend on context.
-- **Medium freedom** (pseudocode, scripts with parameters): preferred pattern exists, some variation OK.
-- **Low freedom** (specific scripts, few parameters): fragile, error-prone, must run a fixed sequence.
-
-### Progressive disclosure
-
-Three loading levels:
-
-1. **Metadata** (name + description): always in context. Keep tight.
-2. **SKILL.md body**: loaded when the skill triggers. Aim under ~500 lines.
-3. **References**: loaded on demand. Move variant-specific detail, schemas, and long examples here.
-
-Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.
-
-### Design the information hierarchy
-
-Put ordered actions in steps and definitions or rules in reference sections. End important steps with a checkable completion criterion; vague criteria invite premature completion. Inline what every execution branch needs and move branch-specific material behind a context pointer whose wording says when to load it.
-
-Split a skill only when the split earns its cost:
-
-- **By invocation:** a distinct leading word must trigger the new skill independently.
-- **By sequence:** hiding later steps prevents the agent from rushing the current step.
-
-Every model-invoked skill spends context load through its description. Every user-only skill spends human cognitive load because the user must remember it. When user-only skills become hard to remember, add one router instead of making every skill model-invoked.
-
-### Use leading words
-
-A leading word is a compact pretrained concept such as `tight loop`, `tracer bullet`, or `handoff`. Reuse the same term in the description and body so it anchors both invocation and execution. Prefer one strong term over repeated prose that restates the same behavior.
-
-### Prune aggressively
-
-Keep each meaning in one authoritative place. Audit every sentence with the no-op test: would removing it change agent behavior? Delete no-ops instead of polishing them. Watch for:
-
-- **Duplication:** the same rule appears in several places.
-- **Sediment:** stale instructions remain because removal feels risky.
-- **Sprawl:** every line may be relevant, but the active path carries too much context.
-- **Negation:** naming forbidden behavior makes it more available; state the positive target and reserve prohibitions for hard guardrails.
-- **Negative space:** omitted decisions silently fall back to model priors; decide whether each omission is intentional.
-- **Premature completion:** sharpen the completion criterion before splitting the sequence.
-
-### Online research routing
-
-When a skill or agent needs online research, name the exact research skill to use instead of relying on vague web-search language:
-
-- Use `~/.agents/skills/find-docs/SKILL.md` for current technical documentation, API references, config options, SDKs, CLIs, cloud services, and code examples.
-- Use `~/.agents/skills/exa-search/SKILL.md` for broader online research, recent information, source discovery, similar pages, URL extraction, or cited web answers.
-- Mention default harness tools for local code, file, git, shell, and browser inspection.
-- Keep built-in `WebSearch` and `WebFetch` as fallback tools unless the user explicitly asks for them.
-- For restricted agents, include `Skill` and `Bash` in the tool list when these skills need to run local CLIs.
-- Never put secrets, tokens, credentials, personal data, or proprietary code in external queries.
-
-### Skill anatomy
-
-```
-skill-name/
-├── SKILL.md            # required: frontmatter + instructions
-├── references/         # optional: docs loaded on demand
-├── scripts/            # optional: deterministic code
-└── assets/             # optional: templates/icons used in output
-```
-
-Do NOT add README, CHANGELOG, INSTALLATION_GUIDE, etc. Only files the agent needs at runtime.
-
-## Authoring workflow
-
-1. **Pin down the use case.** Get 2-3 concrete example prompts that should trigger the skill. Confirm with the user.
-2. **List reusable parts.** What scripts, references, or assets recur? Add only those.
-3. **Write SKILL.md.** Frontmatter first (description is what triggers it - front-load keywords). Then imperative-form body.
-4. **Test the description.** The description has to read like a trigger phrase, not a label. Examples in each reference file.
-5. **Iterate after real use.** Note what the agent got wrong; refine the relevant section.
-
-## Writing the description
-
-The `description` field is the single most important line in the file - it's what the model uses to decide to load the skill. This is a hard rule: descriptions must be between 50 and 300 characters.
-
-Write it as:
-
-- Front-load trigger words ("Use when...", "create a skill", "review a PR").
-- State scope and boundaries explicitly.
-- Mention concrete file names or commands the user might type.
-- Keep it short enough to stay under 300 characters, while still specific enough to trigger reliably.
-
-Bad: `"Helper for skills."`
-Good: `"Create and edit skills/rules across Claude Code, OpenAI Codex, and Cursor. Use when the user asks to 'create a skill'..."`
-
-To validate skill descriptions, frontmatter fields, `agents/openai.yaml`, and skill directory shape, run:
-
-```bash
-bun scripts/inspect-description.ts
-```
-
-By default, this checks `~/.agents/skills` only and follows symlinked skill directories inside that root. Pass one or more roots to inspect a different set. Passing a `.cursor/rules` directory validates Cursor rule frontmatter too:
-
-```bash
-bun scripts/inspect-description.ts .agents/skills
-```
-
-For researched guidance and examples, see [references/description-recommandation.md](references/description-recommandation.md).
-
-## Where each platform stores skills
-
-**Canonical personal skills:** `~/.agents/skills/` is the single source of truth (git repo `Melvynx/agents-config`). It is an official user-level root for both Cursor and Codex, so they read it directly. Write new personal skills only under `~/.agents/skills/<name>/`.
-
-### Codex profile activity icons
-
-Codex's Profile activity view does not resolve standalone skill icons from `agents/openai.yaml`. It resolves known built-in skill icons or the logo of a matching installed plugin. After creating, renaming, or changing the icon metadata of a personal skill, sync the identity-only personal plugin wrappers:
-
-```bash
-bun ~/.agents/scripts/sync-codex-profile-icons.ts --install
-bun ~/.agents/scripts/audit-codex-profile-icons.ts
-```
-
-The wrappers intentionally contain no executable skills, so they provide `logo` / `logoDark` metadata without duplicating skill discovery. Keep `~/plugins` linked to `~/.agents/plugins/plugins`; the sync script creates the link when absent.
-
-Per the official Cursor docs ([cursor.com/docs/skills](https://cursor.com/docs/skills)), user-level roots are `~/.agents/skills/` and `~/.cursor/skills/`, plus compat dirs `~/.claude/skills/` and `~/.codex/skills/`. `~/.cursor/skills-cursor/` is NOT a documented path; do not use it.
-
-Because `~/.agents/skills/` is read directly, the only symlinks needed are the compat dirs for agents that do not read `~/.agents/skills/` themselves:
-
-```bash
-~/.claude/skills -> ~/.agents/skills   # Claude Code reads ~/.claude/skills
-~/.codex/skills  -> ~/.agents/skills   # Codex compat (optional; Codex also reads ~/.agents/skills)
-```
-
-Do NOT symlink `~/.cursor/skills` or `~/.cursor/skills-cursor` to `~/.agents/skills/`; that makes Cursor scan the same skills two or three times. To repair the compat symlinks if missing:
-
-```bash
-ln -s ~/.agents/skills ~/.claude/skills
-```
-
-See the per-platform reference files. Quick reminders:
-
-- **Cursor**: reads `~/.agents/skills/` and `~/.cursor/skills/` (user-level), `.agents/skills/` and `.cursor/skills/` (project). Use `~/.agents/skills/` as the single root; skip the `~/.cursor/skills*` symlinks.
-- **Claude Code**: `~/.claude/skills/` (symlink → `~/.agents/skills/`) or `.claude/skills/` (project). Higher scope wins on name collision.
-- **Codex**: `.agents/skills/` walks up from CWD to repo root, then `~/.agents/skills/`, then `/etc/codex/skills`, then system bundled.
+After creating or renaming a personal skill icon, run `bun ~/.agents/scripts/sync-codex-profile-icons.ts --install`. Compat: `~/.claude/skills` and `~/.codex/skills` symlink to `~/.agents/skills`. Do not symlink `~/.cursor/skills`.

package/agents-config/skills/skill-manager/references/description-recommandation.md

@@ -1,97 +1,27 @@
-# Description Recommendations
+# Description
 
-Use this when writing or refining the `description` field for Claude Code skills, OpenAI Codex skills, or Cursor intelligent rules.
+Load this when writing or refining a `description` field.
 
-## Sources
+Official docs: Codex https://developers.openai.com/codex/skills · Claude https://docs.anthropic.com/en/docs/claude-code/skills · Cursor https://cursor.com/docs/skills
 
-- OpenAI Codex Agent Skills: https://developers.openai.com/codex/skills
-- Anthropic Agent Skills best practices: https://console.anthropic.com/docs/en/agents-and-tools/agent-skills/best-practices
-- Anthropic Agent Skills overview: https://console.anthropic.com/docs/en/agents-and-tools/agent-skills/overview
-- Claude Code skills docs: https://docs.anthropic.com/en/docs/claude-code/skills
-- Cursor rules docs: https://cursor.com/help/customization/rules
+## Rules
 
-## Hard Rules
+- 50–300 characters.
+- First clause useful alone; skill lists may truncate.
+- What it does + when to use it. Third person. No `I can` / `You can`.
+- No XML, tables, long examples, or body-level steps.
+- Trigger-first: nouns, verbs, file names, and commands the user would type.
 
-- Keep every description between 50 and 300 characters.
-- Make the first clause useful on its own; skill lists may shorten descriptions.
-- Include both what the skill does and when it should be used.
-- Use third person. Do not write "I can..." or "You can...".
-- Do not include XML tags, markdown tables, long examples, or implementation steps.
-- Do not duplicate the full SKILL.md body. The description is only discovery metadata.
-
-## What Good Descriptions Do
-
-A good description helps the model decide whether to load the skill before it has read the skill body. It should answer three questions:
-
-1. What capability does this skill provide?
-2. Which user requests, file names, commands, or domain terms should trigger it?
-3. What boundary keeps it from triggering on adjacent but wrong tasks?
-
-Prefer concrete nouns, verbs, and file names over generic labels. Use terms a user would actually type: `SKILL.md`, `.cursor/rules`, `commit message`, `invoice`, `wrangler`, `Netlify deploy`, `DOCX`, `.xlsx`.
-
-## Recommended Shape
-
-Use one or two compact sentences:
-
-```yaml
-description: <Primary capability>. Use when <trigger phrases, file types, commands, or task context>.
-```
-
-For reference-only skills:
-
-```yaml
-description: <Domain conventions or reference material>. Use when working on <specific files, modules, APIs, or workflows>.
-```
-
-For side-effecting workflows, be narrower:
-
-```yaml
-description: Prepare and verify production deploys. Use only when the user explicitly asks to deploy, release, publish, or check deployment status.
-```
-
-## Examples
-
-Good:
-
-```yaml
-description: Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and discovery rules.
-```
-
-Good:
-
-```yaml
-description: Review GitHub pull request feedback and implement requested changes. Use when the user asks to address PR comments, review threads, or requested changes.
-```
-
-Too vague:
+## Shape
 
 ```yaml
-description: Helps with skills.
+description: <Primary capability>. Use when <trigger phrases, files, commands, or task context>.
 ```
 
-Too broad:
+Good: `Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and discovery rules.`
 
-```yaml
-description: Manage all developer workflow tasks, docs, rules, automation, repository work, deployment, testing, and issue handling.
-```
-
-Wrong point of view:
+Good: `Review GitHub pull request feedback and implement requested changes. Use when the user asks to address PR comments, review threads, or requested changes.`
 
-```yaml
-description: I can help you write better skill descriptions.
-```
+Bad: `Helps with skills.` / `I can help you write better skill descriptions.` / a catalog of every adjacent task.
 
-## Checklist
-
-- [ ] 50-300 characters.
-- [ ] First words contain the primary trigger.
-- [ ] Mentions the key files, commands, domains, or user phrases.
-- [ ] Says when to use it, not only what it is.
-- [ ] Specific enough to avoid accidental invocation.
-- [ ] No body-level instructions, setup steps, or long examples.
-
-Run the local inspector after editing:
-
-```bash
-bun scripts/inspect-description.ts
-```
+Then run `bun ~/.agents/skills/skill-manager/scripts/inspect-description.ts` on the skill root.

package/agents-config/skills/test-audit/CAMPAIGN.md

@@ -0,0 +1,117 @@
+# Test-pruning campaign
+
+Campaign mode prunes one subsystem's whole test surface in one PR: a package,
+a plugin, or one core area. The value bar, retention bar, candidate evidence,
+and validation in [SKILL.md](SKILL.md) apply to every lane. This file adds the
+order of work and the lessons of a full campaign, drawn from a campaign on a
+Telegram messaging plugin. Each step ends on its completion criterion; do not
+start the next step early.
+
+## 1. Baseline
+
+Record the subsystem's test and support line counts and every test file's
+pass/fail state at a pinned `main` SHA. Keep baseline failures in their own
+list: in the Telegram campaign, all three were real delivery bugs, not stale
+tests.
+
+Done when every in-scope test file has a recorded baseline result.
+
+## 2. Lanes and inventory
+
+Split the surface into **lanes** along production owner boundaries, not file
+prefixes. For Telegram these were accounts, commands, context, dispatch,
+inbound, outbound, persistence, transport, shared, harness, and live/QA
+scenarios. Include the subsystem's cases at shared core boundaries and its QA
+and live-proof harness tests.
+
+Done when every test file and QA scenario the subsystem owns belongs to exactly
+one lane.
+
+## 3. Read-only ledger per lane
+
+Give each lane to its own read-only agent. The agent reads every assigned test
+in full, including parameter tables. It also reads the production owners and
+their entry points, callers, history, and CI routing. Each test declaration
+goes into a written **ledger** with one mark. An `it.each` is one declaration
+unless its rows need different marks; then mark each row.
+
+- `R`: retain, naming the contract and the bug it catches; a retained test that
+  only moves to a better-named file stays `R` with the move noted;
+- `F`: retain the contract but repair the assertion, such as a vacuous negative
+  that passes when only one of several items is missing;
+- `C`: consolidate, naming the owner that absorbs the assertion first: a sibling
+  table case, a stronger boundary suite, or the shared owner in another package;
+- `D`: delete, naming the proof that remains, or why no contract exists.
+
+Judge a test by its assertions, not its name. One Telegram test named for
+retiring a progress window asserted the window was _not_ cleared.
+
+Done when every declaration in the lane has a mark and an evidence line.
+
+## 4. Layer plan per lane
+
+Treat the per-test ledger as input, not as the edit list. A second read-only
+pass, starting from the ledger, looks for the redundant **layer**. In Telegram,
+several dispatch suites replayed the same shared compositor through one mocked
+preview, around stronger real-stream and HTTP-fixture suites. Name the
+**keeper** suite for each contract. Prefer the real transport boundary with a
+fake network over a mocked collaborator. Correct any ledger errors this pass
+finds.
+
+Done when each lane plan names its retired files, its keeper per contract, the
+assertions to carry into keepers, and the test-only production seams unlocked.
+
+## 5. Cutover
+
+Edit lane by lane. Serialize changes to shared harnesses and support files
+through one owner. With each lane, remove the test-only production seams it
+unlocks: injection parameters, getters, reset exports, and indirection layers.
+Register moved suites in CI routing and test inventories. Update shrink-only
+line-cap baselines. Put durable test-ownership rules in the subsystem's
+`AGENTS.md`, drawn from mistakes this campaign actually found.
+
+Done when every lane plan is applied and each lane's keepers pass.
+
+## 6. Preservation review
+
+Before claiming completion, have independent reviewers compare deleted
+coverage against the keepers, one reviewer per boundary group. They look for
+contracts that lost their only proof. They also look for new assertions that
+cannot fail, such as a rejection row the production code never reaches. The
+Telegram review found nine real gaps and one unreachable assertion.
+
+For each restored contract, make one deliberate **mutation** of the production
+owner and confirm the keeper goes red. Then restore the source byte for byte.
+
+Done when every reported gap is restored or rejected with source evidence, and
+every restored contract has a caught mutation.
+
+## 7. Product defects
+
+A baseline failure that survives into a keeper is a bug report. Fix it at its
+owner as a separate commit, and prove it through the real user flow, with a
+**control** run that reverts the fix and shows the old behavior. Record
+unrelated product discrepancies you find as follow-ups instead of fixing them
+in the campaign.
+
+Done when each repaired defect has a failing control and a passing candidate
+on the same harness.
+
+## 8. Reconcile and hand off
+
+Campaigns outlive many `main` commits. Merge `main` rather than rebasing a
+long, many-commit campaign. When `main` modified a file the campaign
+deleted, keep the deletion. Port the new contract into the keeper instead, and
+confirm every new regression `main` added still has a home. Rerun the whole
+subsystem suite and repeat live proof on the merged head.
+
+Expect review tooling to see a truncated file list on a diff this large.
+Record maintainer decisions for generic compatibility flags in the PR evidence
+rather than editing gates.
+
+Hand off with the [SKILL.md](SKILL.md) report, plus:
+
+- baseline and final test/support line counts, with production counted separately;
+- lanes, retired layers, and keepers;
+- preservation gaps found and their mutations;
+- product defects with control and candidate proof.

package/agents-config/skills/test-audit/LICENSE

@@ -0,0 +1,23 @@
+Adapted from https://github.com/openclaw/openclaw/tree/main/.agents/skills/test-audit
+
+MIT License
+
+Copyright (c) 2026 OpenClaw Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,169 @@
+---
+name: test-audit
+description: "Invoke whenever writing, changing, reviewing, or sweeping tests. Authoring gate for new tests plus audit workflow for low-value, implementation-coupled, or duplicative tests and the test-only production seams they demand."
+---
+
+# Test Audit
+
+Three modes, one value bar. Authoring mode gates every new or changed test at
+write time. Audit mode runs focused sweeps of tests that re-assert source,
+duplicate stronger proof, couple behavior to implementation, or keep test-only
+production seams alive. Continue broad audits as separate coherent follow-up
+PRs; optimize for confidence, not deletion count. Campaign mode prunes one
+whole subsystem's test surface (every test file a package, plugin, or core area
+owns); before starting one, read [CAMPAIGN.md](CAMPAIGN.md).
+
+## Authoring gate
+
+Before adding any test, answer four questions; a missing answer means do not
+add it yet:
+
+1. What observable behavior, invariant, or independent contract does it protect?
+2. What credible regression makes it fail?
+3. Why does existing coverage not already catch that failure? Each contract has
+   one primary test owner at the strongest boundary; another layer needs its
+   own distinct risk, such as a transport or lifecycle failure the owner cannot
+   reach. Prefer extending a table-driven case or shared fixture over a
+   near-duplicate test; consolidate duplicated setup in the same change.
+4. Does it need a production seam (export, flag, wrapper, injection hook) that no
+   production caller needs? If yes, move the test to the real boundary instead.
+
+Then check the test against every [junk pattern](#junk-patterns); a match fails
+the gate unless the [retention bar](#retention-bar) names the contract it
+independently guards. A test that would break under behavior-preserving
+refactoring is asserting implementation, not behavior; rewrite it at the
+owning boundary before landing it.
+
+Bug regression tests must fail on the pre-fix code for the intended reason and
+pass after the owner-boundary repair. A regression test that never demonstrably
+failed proves the mock, not the fix. One regression at the owner boundary
+covers the bug; do not replay the same scenario at every layer it crosses.
+
+## Junk patterns
+
+The shared checklist for both modes: the authoring gate rejects a new test that
+matches one, and audits hunt for existing tests that do.
+
+- assertion-free coverage probes;
+- self-comparisons and identity copiers;
+- copied fixtures, inventories, manifests, or export lists;
+- exact source, import, or string greps;
+- private predicate or call-shape tests duplicated at real boundaries;
+- duplicate invocations of the same contract;
+- provider-local replays of shared helpers;
+- tests whose only purpose is preserving test-only exports, globals, or wrappers;
+- dead production code whose only callers are tests;
+- expected values produced by the helper or renderer under test;
+- mocks that implement the asserted behavior, or one identical mock standing in
+  for different APIs;
+- fixtures that supply the receipt, admission, or callback ordering the owner
+  should produce, or persistence asserted against a store the path never writes;
+- capability tests that restate declared flags instead of exercising the
+  delivery or acknowledgement the flag promises;
+- negative controls that pass for an unrelated reason, such as a denial from a
+  different guard or a rejection the production path never reaches;
+- names or fixtures that promise more than the input exercises, such as a
+  "retires the window" test asserting the window was not cleared.
+
+## Value bar
+
+Tests justify their maintenance cost by protecting behavior, a credible
+regression, or an independently meaningful contract. In an audit, an existing
+test that must change for behavior-preserving source reorganization is suspect,
+not automatically deletable; the authoring gate still rejects new ones.
+
+Before judging a candidate, read the complete test and production owner, its
+entry point, callers, callees, sibling implementations, overlapping tests, CI
+routing, and relevant history. Read root and scoped `AGENTS.md` files first.
+When the test claims dependency-backed behavior, inspect the dependency source
+or types directly.
+
+## Discovery
+
+Keep discovery read-only and report evidence before editing. For broad scope,
+run parallel discovery lanes when available:
+
+- core source and packages;
+- plugins, extensions, or integrations;
+- UI, apps, scripts, and tooling;
+- a cross-cutting pattern sweep.
+
+Outside campaign mode, prefer a few high-confidence candidates over a large
+speculative inventory. Hunt for the [junk patterns](#junk-patterns).
+
+## Retention bar
+
+Keep a test when it independently enforces a public API, SDK, protocol, config,
+migration, storage, security, platform, default, generated-output, package,
+release, or architecture contract. Also keep:
+
+- call ordering when order is observable behavior;
+- regressions with a credible failure mode;
+- source inspection when it is the cheapest independent guard: it fails when
+  the contract changes (the user-facing key, byte, or path) and survives an
+  identifier-only refactor;
+- a retained test that fails on the baseline: treat it as a possible product
+  bug, reproduce it, and repair the owner rather than deleting it.
+
+Static or slow is not a deletion reason. A test that resembles implementation
+may still be the independent contract; prove otherwise before removing it.
+
+## Candidate evidence
+
+Record every field below before editing. A missing field means the candidate is
+not ready for deletion:
+
+- exact test name and location;
+- what failure it can actually detect;
+- non-test callers of the covered production or support seam;
+- stronger remaining owner-boundary proof, or why no proof is needed;
+- relevant history and the reason the test or seam exists;
+- production or test-support deletion unlocked;
+- risk and the focused validation command.
+
+## Edit shape
+
+Choose one coherent owner-boundary batch. Delete obsolete test-only exports,
+globals, wrappers, and dead production paths instead of preserving aliases.
+Move retained regressions to their canonical owners. Consolidate repeated
+package or dependency assertions into one generic contract.
+
+Prefer net-negative production LOC. Do not add replacement tests that restate
+the same implementation, and do not convert uncertain candidates into cleanup
+to increase deletion counts.
+
+## Validation
+
+Never edit source or tests while a test watcher is running in the checkout. Use
+the test commands documented in the repository's `AGENTS.md`, `CLAUDE.md`, or
+package scripts.
+
+1. Run the smallest owner and sibling tests with the repository's test runner,
+   filtered to the affected paths.
+2. For removed source greps or plan assertions, run the executable script or
+   dry-run that owns the real contract.
+3. Run targeted formatting, then `git diff --check`.
+4. Run the changed-files gate required by repository policy (lint, typecheck,
+   and the CI checks those paths trigger).
+5. Inspect `git diff --numstat`; report production/tooling separately from
+   tests and test support.
+6. After final audit edits, get an independent review of the deleted coverage
+   against the remaining keepers.
+
+## Landing and continuation
+
+Commit, push, open a PR, or land only when authorized. Follow the repository's
+PR flow. Land one coherent PR at a time; after landing, refresh from current
+`main` and rerun read-only discovery for the next high-confidence batch.
+
+## Handoff
+
+Report:
+
+- root cause and removed low-value categories;
+- production owner simplifications;
+- retained false positives and why they remain valuable;
+- focused and full proof actually run;
+- production versus test LOC;
+- PR and merge state;
+- named follow-ups.

package/agents-config/skills/test-audit/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Test Audit"
+  short_description: "Gate new tests and prune low-value ones"
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#737373"
+  default_prompt: "Use $test-audit to gate these tests or audit low-value ones."
+
+policy:
+  allow_implicit_invocation: true

package/agents-config/skills/test-audit/assets/codex-icon.svg

@@ -0,0 +1 @@
+<svg role="img" aria-label="test-audit skill icon" xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 24 24" fill="none" stroke="#F5F5F5" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 2v6.5L4.5 17A3 3 0 0 0 7.2 21h9.6a3 3 0 0 0 2.7-4L15 8.5V2"/><path d="M8 2h8"/><path d="M7 15h10"/></svg>