@iowarp/clio-coder 0.4.1 → 0.4.2

package/skills/meta/clio-coder-test/references/harness.md

@@ -1,126 +1,102 @@
 # Clio test harness reference
 
-How to drive the real Clio binary, a mock provider, the ACP surface, and a
-real pseudo-terminal in tests. Every model here is a stub; these are machinery
-tests. A run against a real model is `benchmarks/internal/SKILL.md`.
-
-## Contents
-- The spawn harness (`runCli`, `makeScratchHome`)
-- Mocking a provider (OpenAI-compatible SSE fixture)
-- ACP over JSON-RPC/stdio
-- The PTY (`openPty`, `runInPty`)
-- One-off probes (no test file)
-
-## The spawn harness
-
-`tests/harness/spawn.ts` spawns `node dist/cli/index.js` with piped stdio, so
-**build first** (or keep `npm run dev` running) before running smoke.
-
-```ts
-import { makeScratchHome, runCli } from "../harness/spawn.js";
-
-const scratch = makeScratchHome();
-try {
-  await runCli(["doctor", "--fix"], { env: scratch.env });   // bootstrap config
-  const res = await runCli(["targets", "--json"], { env: scratch.env, timeoutMs: 20_000 });
-  // res = { code, signal, stdout, stderr }
-  const parsed = JSON.parse(res.stdout) as { targets: unknown[] };
-} finally {
-  scratch.cleanup();
-}
-```
-
-- `runCli(args, { env, cwd, timeoutMs, input })` → `Promise<{ code, signal, stdout, stderr }>`.
-  Default `timeoutMs` is 15_000; raise it for `run`/`acp`.
-- `makeScratchHome()` → `{ dir, env, cleanup }`. The `env` sets `CLIO_CODER_HOME`,
-  `CLIO_CODER_DATA_DIR`, `CLIO_CODER_CONFIG_DIR`, `CLIO_CODER_CACHE_DIR`, and
-  `CLIO_CODER_REQUIRE_HOME_PREFIX=1`. **Always pass `env: scratch.env`** so the test
-  never touches the developer's real config, and always `cleanup()` in `finally`.
-- Bootstrap a scratch home with `runCli(["doctor", "--fix"], …)` before commands
-  that need settings.
-
-Useful flags seen in smoke tests: `--no-context-files`, `--no-skills`,
-`--skill <path>`, `--json`. For the live CLI surface, run `clio-coder --help` and
-`clio-coder <command> --help` rather than hardcoding a command list here.
-
-## Mocking a provider
-
-To exercise an agent `run` without a real model, stand up an in-process
-OpenAI-compatible server that streams one SSE chunk, then point a target at it by
-patching `settings.yaml`. This is the pattern in `tests/smoke/cli.test.ts`:
-
-```ts
-// 1. Start a fixture that replies with a fixed string over text/event-stream.
-const fixture = await startOpenAICompatFixture("mock reply");
-// 2. Patch the scratch settings.yaml: add an `openai-compat` target whose
-//    url is fixture.url, set orchestrator.target/model to it, and supply the
-//    apiKeyEnvVar it expects.
-seedOpenAICompatOrchestrator(join(scratch.dir, "config"), fixture.url);
-// 3. Run, providing the key env var the target references.
-const res = await runCli(["--no-context-files", "run", "hello"], {
-  env: { ...scratch.env, CLIO_CODER_TEST_OPENAI_KEY: "sk-test" },
-  timeoutMs: 20_000,
-});
-// res.stdout === "mock reply\n"
-await closeServer(fixture.server);
-```
-
-The fixture also records `fixture.requests`, so you can assert what Clio sent
-(e.g. that an explicit `--skill` was injected into the prompt).
-
-## ACP over JSON-RPC/stdio
-
-`clio-coder acp` speaks ACP v1 over stdio. Drive it with a line-delimited JSON-RPC
-client (see `createJsonRpcProcessClient` in the smoke test): `initialize` →
-`session/new` → `session/prompt` → `session/close`. Streaming arrives as
-`session/update` notifications whose `update.sessionUpdate` must be a v1 variant
-(`agent_message_chunk`, `tool_call`, `plan`, `current_mode_update`, …). A
-non-spec discriminator breaks strict clients like Zed, so the smoke test asserts
-every emitted variant is in the v1 set.
-
-## The PTY
-
-Piped stdio reports no terminal width and no TTY, so the TUI refuses to start
-and every width-sensitive path collapses to 80 columns. `tests/harness/pty.ts`
-opens a real pseudo-terminal through `node-pty` (a devDependency, never
-shipped):
-
-```ts
-import { openPty, runInPty, stripAnsi, visibleLines } from "../harness/pty.js";
-
-// Scripted: type on a schedule, stop when the output matches, bounded by a timeout.
-const run = await runInPty(process.execPath, [CLI], { cols: 120, rows: 40, cwd, env,
-  readyWhen: /ctx /, input: [{ afterMs: 200, data: "/quit\r" }], until: /bye/, timeoutMs: 20_000 });
-
-// Controllable: write, resize, pause output, wait for a matcher, wait for exit.
-const session = await openPty(process.execPath, [CLI], { cols: 140, rows: 44, cwd, env });
-await session.waitForOutput((out) => /ctx /.test(stripAnsi(out)), 30_000);
-session.write("/quit\r");
-await session.waitForExit(10_000);
-```
-
-Use it only for what a pipe cannot show: width, raw mode, SIGINT through a
-terminal, the alternate-screen and keyboard-protocol teardown. The three
-suites that need it are `tests/smoke/tui-width-matrix.test.ts`,
-`instant-shell-pty.test.ts`, and `render-trace-pty.test.ts`. Anything else
-belongs on `runCli`.
-
-## One-off probes (no test file)
-
-To poke at Clio without writing a permanent test, drop a throwaway script in
-your scratch directory and run it with tsx. Delete it when done — never leave
-probes under `tests/`, `scripts/`, or `benchmarks/`.
-
-```ts
-// /tmp/probe.ts
-import { makeScratchHome, runCli } from "/abs/path/to/repo/tests/harness/spawn.js";
-const scratch = makeScratchHome();
-await runCli(["doctor", "--fix"], { env: scratch.env });
-const out = await runCli(["skills", "list", "--json", "--all"], { env: scratch.env, cwd: process.cwd() });
-console.log(out.stdout.slice(0, 400));
-scratch.cleanup();
-```
-
-```bash
-npx tsx /tmp/probe.ts
-```
+This reference covers the harness modules that exist in the current tree:
+temporary-state isolation, dispatch fixtures, a loopback OpenAI-compatible
+server, and the ACP stdio smoke driver. Deterministic tests do not contact a
+real model and the repository currently has no shared spawn or PTY harness.
+
+## Temporary roots and state isolation
+
+The `test:file` and `test` package scripts preload `tests/harness/tmp-root.ts`.
+It creates one guarded root below the system temp directory, points `TMPDIR`
+inside it before test modules load, sweeps abandoned roots only after a bounded
+age, and removes the current root on process exit. `tmp-git-guard.ts` prevents
+a test from creating `.git` at the system or run temp root, where it would alter
+project-boundary discovery for unrelated tests.
+
+Use `tests/harness/scratch-env.ts` for Clio-specific state:
+
+- `makeScratchHome()` returns a directory, a child-process environment, and a
+  cleanup function without mutating `process.env`.
+- `isolateClioEnv()` snapshots and mutates `process.env`, resets the XDG cache,
+  and returns a restoring teardown.
+- `newScratchClioHome()` and `clearScratchClioHome()` provide the same
+  in-process isolation when a plain directory string is more convenient.
+- `scratchClioEnvVars()` keeps `CLIO_CODER_HOME` and the data, config, state,
+  and cache overrides in one root. The child-process form also sets
+  `CLIO_CODER_REQUIRE_HOME_PREFIX=1`.
+
+In-process environment isolation is a process-wide critical section. Await the
+acquire helper in setup and always invoke its matching restore or clear helper
+in teardown.
+
+## Driving the built CLI
+
+Every file under `tests/smoke/` spawns `dist/cli/index.js` through a local
+process driver suited to that boundary:
+
+- `cli-core.test.ts` captures stdout and stderr with a bounded timeout.
+- `acp-boundary.test.ts` keeps stdin open and frames ACP v1 JSON-RPC messages.
+- `installed-package.test.ts` packs, installs, and launches the installed
+  artifact.
+- `process-lifecycle.test.ts` keeps the process live long enough to verify
+  signal propagation into a tool child.
+- `real-binary-boot.test.ts` supports interactive setup input and bounded
+  shutdown during first-run and migration checks.
+
+Build before a focused smoke run. `npm run ci` performs that build in the
+correct order. Keep environment roots under a scratch directory, capture both
+output streams, bound every wait, and terminate a surviving child in teardown.
+Do not import a nonexistent shared `runCli`; copy the closest smoke driver's
+small pattern or extract a helper only when more than one current boundary has
+the same contract.
+
+## Loopback provider fixtures
+
+`tests/harness/openai-compat-fixture.ts` exports
+`startOpenAICompatFixture()` and `closeServer()`. The fixture listens on an
+ephemeral loopback port, serves `/v1/models` and `/v1/chat/completions`, supports
+streaming text and one scripted tool call, and records request bodies for
+assertions. Its seed helpers write scratch target configurations for
+orchestrator, tool, fleet, bootstrap, and unregistered-runtime cases.
+
+The current reusable fixture is used by provider contracts. Smoke files define
+their own minimal loopback servers because their wire behavior differs. In
+either lane, close the server in teardown and assert the request body when the
+test's claim concerns payload fields.
+
+## Dispatch contracts
+
+`tests/harness/dispatch.ts` provides:
+
+- `makeDispatchBundle()` with the real prompt customization path and a fast,
+  argument-preserving reproducibility collector.
+- `isolateDispatchState()` and `restoreDispatchState()` for ledger, receipt,
+  and environment isolation.
+- `holdEventLoop()` for contracts that await an unref'd production watchdog.
+
+`dispatch-stub-context.ts` supplies the minimal domain context used by dispatch
+tests. `receipt.ts` supplies typed envelope and receipt drafts. Prefer these
+fixtures over reconstructing broad domain objects in each test.
+
+## ACP over JSON-RPC stdio
+
+`tests/smoke/acp-boundary.test.ts` owns the current `AcpClient`. It launches
+`clio-coder acp` with piped stdio, parses one JSON object per line, correlates
+responses by id, collects `session/update` notifications, and handles inbound
+`session/request_permission` calls.
+
+The exercised sequence is `initialize`, `session/new`, `session/prompt`, then
+`session/close`. Permission cases answer the inbound request with a selected
+`allow-once` or `reject-once` option and assert both the final tool-call update
+and the filesystem outcome. Keep stdout exclusively for protocol frames;
+diagnostics belong on stderr.
+
+## Disposable probes
+
+A one-off diagnostic belongs under `/tmp`, not `tests/`, `scripts/`, or an
+invented benchmark tree. Run TypeScript probes with `node --import tsx`, point
+all Clio state variables at a fresh temporary root, and delete the probe after
+recording the result. A result from a loopback fixture is machinery evidence,
+not live-model evidence. Live validation must name the configured target,
+model, runtime, prompt, and serving settings.

package/skills/meta/clio-coder-test/references/test-map.md

@@ -1,69 +1,96 @@
 # Where Clio's tests live
 
-Three layers under `tests/`. Add a new test next to the closest existing file;
-create a new file only for a genuinely new domain cluster.
+The root repository has contract and smoke tests under `tests/`; import
+boundaries run through the lint hygiene checker. Add a test beside the closest
+current behavior, and create a new file only for a genuinely new cluster.
 
 ## Layout
 
-| Layer | Path | Runner | Build needed |
+| Lane | Path | Runner | Build needed |
 |---|---|---|---|
-| contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <glob>` (tsx + scratch root) | no (imports `src`) |
-| smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <glob>` | **yes** (spawns `dist/`) |
-| boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` (hygiene) | no |
-| harness (not tests) | `tests/harness/*.ts` | imported by contracts and smoke | — |
+| Contracts | `tests/contracts/*.test.ts` | `npm run test:file -- <file-or-files>` through tsx and the temp-root preload | No; imports `src/` |
+| Smoke | `tests/smoke/*.test.ts` | `npm run test:file -- <file-or-files>` | Yes; spawns `dist/cli/index.js` |
+| Boundaries | `tests/boundaries/check-boundaries.ts` | `npm run lint` through `scripts/check-hygiene.ts` | No |
+| Root full suite | Contract and smoke files | `npm run test` | Yes for current smoke behavior |
+| Trace viewer | `apps/trace-viewer/tests/*.test.mjs` | `npm run test:trace-viewer` | No |
+| Workbench | `apps/workbench/tests/` | `deno task verify` from `apps/workbench` | The command builds the app |
 
-The harness modules: `spawn.ts` (run the built CLI with pipes), `scratch-env.ts`
-(isolated Clio home), `pty.ts` (a real pseudo-terminal), `openai-compat-fixture.ts`
-and `fake-lmstudio-server.ts` (stub providers), `fake-ssh.ts` (stub fleet node),
-`clock.ts` (steppable clock), plus dispatch, receipt, and module-graph helpers.
-Everything under `tests/` stubs the model. Real-model runs are
-`benchmarks/internal/` and never run under `npm test`.
+`npm run ci` orders typecheck, lint, skill-pin verification, build, the root
+suite, and trace-viewer tests. `npm run ci:release` adds the release audit. The
+Workbench gate is separate.
 
-## Contract test files
+## Contract files
 
-| Area | File |
+| Area | Current files under `tests/contracts/` |
 |---|---|
-| ACP contract | `tests/contracts/acp.test.ts` |
-| context bootstrap / CLIO-CODER.md parse+render | `tests/contracts/bootstrap.test.ts` |
-| config schema + hot-reload classification | `tests/contracts/config.test.ts` |
-| dispatch (validation / admission / ledger) | `tests/contracts/dispatch.test.ts` |
-| session / memory / evidence persistence | `tests/contracts/persistence.test.ts` |
-| prompt fragments + hashing | `tests/contracts/prompts.test.ts` |
-| provider catalog / matcher / resolver | `tests/contracts/providers.test.ts` |
-| safety classification | `tests/contracts/safety.test.ts` |
-| skills loader / collisions / provenance | `tests/contracts/skills.test.ts` |
-| skill activation + compaction interplay | `tests/contracts/skill-activation-compaction.test.ts` |
-| tool registry / names / profiles | `tests/contracts/tools.test.ts` |
-
-## Smoke + boundaries
-
-| Area | File |
+| Authentication | `auth-login-write-failure`, `auth-storage-durability` |
+| Context, session, and state | `context-lifecycle`, `memory-scope`, `project-bootstrap`, `session-durability`, `state-file-lock`, `task-board-done`, `working-set-core` |
+| Config, routing, and presentation | `footer-context-window`, `knob-aliases`, `pane-remedies`, `rendering-invariants`, `route-identity-keying`, `settings-migration` |
+| Dispatch, fleet, and workers | `dispatch-admission`, `dispatch-lifecycle`, `dispatch-schema`, `fleet-lifecycle`, `host-verification-batch`, `intent-requirements`, `worker-attestation-surface`, `worker-boundary` |
+| Prompts, engine loop, and middleware | `compact-prompt-contracts`, `engine-lifecycle`, `loop-detector`, `loop-guard-epoch`, `middleware-hooks`, `prompt-cache-correctness`, `prompt-prefix-layout`, `prompt-role-routing`, `prompt-session-snapshot`, `prompt-tool-hints` |
+| Providers and model policy | `gemma-channel-filter`, `llamacpp-router-probe`, `local-model-family-resolution`, `provider-context-boundary`, `provider-transport`, `synthesis-lock`, `thinking-off-wire` |
+| Safety and tools | `bash-exec-settlement`, `rejection-feedback`, `safe-resource-write`, `safety-gates`, `tool-boundaries` |
+| Evidence, eval, and release | `eval-boundary`, `evidence-integrity`, `metering-integrity`, `release-boundary` |
+| Extensions, interop, and skills | `extension-compatibility`, `extension-reload-coordinator`, `extension-reload-slash`, `extension-resources`, `extension-snapshot`, `interop-boundary`, `marketplace-offer`, `skill-install` |
+| Documentation server | `docs-server` |
+
+Append `.test.ts` to every stem in the table. Use `rg` over the files before
+choosing a lane; related behavior can span more than one focused contract.
+
+## Smoke files
+
+| Boundary | File under `tests/smoke/` |
+|---|---|
+| ACP v1 over JSON-RPC stdio, permission requests, and text/image content | `acp-boundary.test.ts` |
+| Core CLI health, local-provider run, receipts, events, and autonomy | `cli-core.test.ts` |
+| `npm pack`, installed resources, and installed codewiki navigation | `installed-package.test.ts` |
+| Signal propagation through a real tool child | `process-lifecycle.test.ts` |
+| Real-binary setup, onboarding, migration, and launch behavior | `real-binary-boot.test.ts` |
+
+The smoke files own their child-process helpers. There is no shared
+`tests/harness/spawn.ts` and no PTY smoke lane in the current tree.
+
+## Harness and fixture modules
+
+| File | Purpose |
 |---|---|
-| non-interactive CLI + ACP-over-stdio end-to-end | `tests/smoke/cli.test.ts` |
-| the package as installed from `npm pack` | `tests/smoke/pack-install.test.ts` |
-| TUI at real terminal sizes, NO_COLOR, Ctrl-C teardown (PTY) | `tests/smoke/tui-width-matrix.test.ts` |
-| instant shell before hydration, SIGTERM through the lease (PTY) | `tests/smoke/instant-shell-pty.test.ts` |
-| committed-frame render trace under PTY backpressure (PTY) | `tests/smoke/render-trace-pty.test.ts` |
-| import boundary rules (rule1/2/3), run under `npm run lint` | `tests/boundaries/check-boundaries.ts` |
+| `tests/harness/tmp-root.ts` | Preloaded guarded temp root and cleanup for every root test run |
+| `tests/harness/tmp-git-guard.ts` | Prevents accidental `.git` creation in the system or test temp root |
+| `tests/harness/scratch-env.ts` | Child-process and in-process Clio state isolation |
+| `tests/harness/dispatch.ts` | Dispatch bundle, fast reproducibility, isolated state, and event-loop helpers |
+| `tests/harness/dispatch-stub-context.ts` | Minimal domain context for dispatch contracts |
+| `tests/harness/receipt.ts` | Typed run-envelope and receipt fixtures |
+| `tests/harness/openai-compat-fixture.ts` | Loopback OpenAI-compatible server and target seeders |
+
+Child fixtures in `tests/fixtures/` are
+`capacity-lease-child.ts`, `codewiki-coordinator-child.ts`, and
+`evidence-index-writer.ts`.
 
 ## Running a subset
 
 ```bash
-# all contracts
-npm run test:file -- 'tests/contracts/**/*.test.ts'
-# one file
-npm run test:file -- tests/contracts/skills.test.ts
-# only it.only / describe.only within a file
-npm run test:file -- --test-only tests/contracts/skills.test.ts
+# all contracts (the shell expands the file pattern)
+npm run test:file -- tests/contracts/*.test.ts
+
+# one contract or smoke file
+npm run test:file -- tests/contracts/skill-install.test.ts
+npm run build
+npm run test:file -- tests/smoke/cli-core.test.ts
+
+# only it.only or describe.only within one file
+npm run test:file -- --test-only tests/contracts/skill-install.test.ts
 ```
 
 ## Writing tests
 
-- `node:test` + `node:assert/strict`. Group with `describe` / `it`.
-- Local imports end in `.js` (NodeNext), e.g. `from "../../src/domains/x/y.js"`.
-- `tsconfig.tests.json` is strict with `noUncheckedIndexedAccess` and
-  `exactOptionalPropertyTypes`; narrow array access before use.
-- Biome rejects `delete obj.key`; use `Reflect.deleteProperty(obj, "key")` when
-  cleaning env maps or object keys.
-- Filesystem tests use a scratch home via `makeScratchHome()` (smoke) or the
-  `CLIO_CODER_HOME` / `CLIO_CODER_*_DIR` env overrides (contracts); clean up in `finally`.
+- Use `node:test` and `node:assert/strict`.
+- End local TypeScript import specifiers in `.js` for NodeNext resolution.
+- Keep `tsconfig.tests.json` strict, including `noUncheckedIndexedAccess` and
+  `exactOptionalPropertyTypes`; narrow indexed values before use.
+- Let the package script preload `tmp-root.ts`. Tests that mutate Clio state or
+  `process.env` should use `scratch-env.ts` and restore in teardown.
+- Use a loopback fixture for provider behavior. Do not contact a configured or
+  public model from a deterministic test.
+- Build before a focused smoke run. `npm run ci` already builds before testing.
+- Keep a smoke process driver local to the boundary it exercises unless a
+  genuinely shared contract appears.

package/skills/meta/credentials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: credentials
-description: Use before running any tool or script that needs an API key, token, or other credential, when a command fails with an auth error, when the user must supply a new secret, or when a secret may have leaked into output. Covers facility surfaces such as kerberos tickets, globus and scheduler tokens, ssh agents, and netrc. Triggers on "API key", "credential", "token", "auth error", "permission denied", "add a secret", "leaked". Not for provider target configuration; use clio-coder auth and target settings.
+description: Handles API keys, tokens, and facility credentials (kerberos tickets, globus and scheduler tokens, ssh agents, netrc) before a tool needs one, after an auth error, when a new secret is supplied, or when one may have leaked. Not for provider target configuration; use clio-coder auth and target settings.
 triggers:
   - API key
   - credential missing
@@ -8,7 +8,7 @@ triggers:
   - permission denied
   - add a secret
   - secret leaked
-version: 0.1.3
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - read

package/skills/meta/find-skills/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: find-skills
-description: Use when the user asks "is there a skill for X", "find a skill", "install a skill", "add a skill", asks whether a capability exists as an installable skill, or wants to extend the agent with functionality that might already be published. Searches with `clio-coder skills search`, browses the ecosystem read-only, and installs only through `clio-coder skills install`. Not for authoring a new skill; use skill-craft.
+description: Finds and installs published skills when the user asks whether a capability exists as a skill, searching with clio-coder skills search and installing only through clio-coder skills install. Not for authoring a new skill; use skill-craft.
 triggers:
   - find a skill
   - is there a skill for this
   - install a skill
   - add an agent skill
   - search the skills marketplace
-version: 0.1.2
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - bash

package/skills/meta/herdr/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: herdr
-description: Use when the user explicitly mentions Herdr or asks to launch, drive, or inspect another agent or command in a Herdr pane, tab, or workspace — including starting a second Clio Coder instance and delegating work to it. Requires HERDR_ENV=1. Not for background work a plain shell or dispatch already covers; do not activate merely because a task could benefit from parallelism.
+description: Launches, drives, or inspects another agent or command in a Herdr pane, tab, or workspace, including a second Clio Coder instance; requires HERDR_ENV=1. Not for background work a plain shell or dispatch already covers.
 triggers:
   - use Herdr
   - launch an agent in a Herdr pane
   - inspect a Herdr agent
   - start a second Clio Coder instance
   - drive a command in a Herdr workspace
-version: 0.1.1
+version: 0.2.0
 license: Apache-2.0
 allowed-tools:
   - bash

package/skills/meta/skill-craft/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: skill-craft
-description: Use when writing, reviewing, or pruning a SKILL.md — authoring a new skill, editing an installed one, or judging whether a skill's description, body, or length is earning its cost. Triggers on "write a skill", "improve this skill", "why isn't this skill firing", "is this skill too long".
+description: Writes, reviews, or prunes a SKILL.md, judging whether its description, body, and length earn their cost. Not for packaging a workflow that just happened; use workflow-distiller.
 triggers:
   - write a SKILL.md
   - create a new skill
   - improve this skill
   - why isn't this skill firing
   - prune a skill body
-version: 0.1.3
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read
@@ -36,11 +36,14 @@ tool. Project skills live in `.clio-coder/skills/<name>/`; user skills in the Cl
 config dir under `skills/<name>/`. The loader validates on load; check work
 with `clio-coder skills validate`. Frontmatter contract (Agent Skills compatible):
 
-- `name`: lowercase-hyphen, ≤64 chars, must match the folder.
+- `name`: lowercase-hyphen, ≤64 chars. Catalog convention requires it to match
+  the folder; the runtime loader warns on a mismatch and uses the frontmatter
+  name.
 - `description`: required, ≤1024 chars; its craft is the section below. Quote
   it when it contains ` #` — an unquoted YAML scalar is truncated there.
-- `version` and `license`: required for catalog publication; bump the version
-  on any name or description change so drift detection can tell copies apart.
+- `version` and `license`: required for catalog publication. Follow the
+  marketplace versioning policy for body, trigger-surface, and sibling-file
+  changes; the normalized `SKILL.md` hash handles drift separately.
 - `disable-model-invocation: true`: hides the skill from the agent; only the
   user can activate it.
 - `allowed-tools` / `disallowed-tools`: a *narrowing* declaration, not a
@@ -50,7 +53,7 @@ with `clio-coder skills validate`. Frontmatter contract (Agent Skills compatible
   names only (see skills/README.md, "Claude Code interop").
 - `requires`: `skill:<name>` dependencies; the loader warns when one is
   missing. Reference an installed skill by name instead of restating its job.
-- `clio:`: the reserved publication block (`registry-id`, `source-url`,
+- `clio-coder:`: the reserved publication block (`registry-id`, `source-url`,
   `audit`, `provenance` designed|adapted|imported with `origin` when not
   designed, `eval-status`, optional `model-size` and `agents`). Required for
   catalog skills; approval is judged against it (skills/README.md).
@@ -66,17 +69,19 @@ but the user must remember it exists: cognitive load. Keep a description only
 when the agent must reach the skill on its own or another skill requires it;
 if it only ever fires by hand, set `disable-model-invocation: true`.
 
-## Description: Triggers, Not Identity
+## Description and Triggers
 
-The description is the skill's trigger surface, so every word competes with
-every other skill's description:
+Two frontmatter fields share the trigger surface, and every word in both
+competes with every other skill's:
 
-- Front-load the strongest trigger word.
-- One trigger per distinct branch. Synonyms restating one branch ("API key",
-  "credential", "token") are duplication; keep the strongest.
-- Cut identity the body already states; keep triggers, plus one "Not for X;
-  use <other-skill>" clause per real boundary.
-- Word triggers with the language the user actually types.
+- `triggers`: the phrases a user actually types, one per distinct branch.
+  Synonyms restating one branch ("API key", "credential", "token") are
+  duplication; keep the strongest.
+- `description`: one lead sentence saying what the skill does, then one
+  "Not for X; use <other-skill>" clause per real boundary. It is what the
+  agent reads in the `context(scope="skills")` listing on every skill-shaped
+  turn, so it carries no trigger list and no identity the body already
+  states.
 
 ## Body: Steps and Reference
 
@@ -113,7 +118,8 @@ Before finishing any skill, pass the body line by line:
   or split the skill; a split description must earn its permanent context
   load.
 
-Done when: description is triggers-only, every step has a checkable
+Done when: the description is one sentence plus routing clauses and the
+triggers carry the phrases, every step has a checkable
 completion criterion, no line fails the relevance/duplication/no-op pass, and
 an `evals.md` records at least one RED-GREEN scenario distinguishing
 with-skill from without.

package/skills/planning/architecture/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: architecture
-description: 'Use when an intent (PRD, epic, brief, or idea) needs its engineering approach decided — "how should we build this", "pick the stack", "architecture for this feature". An interactive working session: investigates, proposes 2-3 genuinely different approaches with trade-offs, recommends with reasoning, lets the user decide, and writes a high-level architecture decision doc. Not a task-by-task plan; use cut-it for that. Not a multi-perspective debate; use design-council. Not product intent; use product-intent. Not a typed implementation handoff with code-shaped contracts; use tech-spec.'
+description: "Decides the engineering approach for an intent in an interactive session: investigates, proposes two or three genuinely different approaches with trade-offs, recommends, lets the user decide, and writes the decision doc. Not a task-by-task plan; use cut-it. Not a multi-perspective debate; use design-council. Not product intent; use product-intent. Not a typed implementation handoff; use tech-spec."
 triggers:
   - how should we build this
   - pick the stack
   - architecture for this feature
   - decide the engineering approach
   - compare architecture options
-version: 0.2.2
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read

package/skills/planning/backlog/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: backlog
-description: Use when a finished PRD or architecture doc must become a real ticket backlog — "create the stories", "turn this PRD into issues", "build the backlog". Decomposes phases and user stories into small tickets with verifiable acceptance criteria, confirms the list, then creates them as GitHub issues (or in another tracker when an integration exists). Not for local sprint slicing into a SPRINT.md; use cut-it.
+description: Turns a finished PRD or architecture doc into a ticket backlog of small stories with verifiable acceptance criteria, confirmed, then created as GitHub issues or in another configured tracker. Not for local sprint slicing into a SPRINT.md; use cut-it.
 triggers:
   - create the stories
   - turn this PRD into issues
   - build the backlog
   - decompose this plan into tickets
   - create GitHub issues from this architecture
-version: 0.2.1
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read

package/skills/planning/prd/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: prd
-description: Use when the user wants to turn an idea into a product requirements document through a phase-gated interview — each phase locks before the next opens — ending in PRD.md plus per-milestone prompt files ready to drive a coding agent. Triggers on "write a PRD", "spec this out", "help me define this feature/product", or a brain dump that needs structure before planning.
+description: Turns an idea into a product requirements document through a phase-gated interview, ending in PRD.md plus per-milestone prompt files ready to drive a coding agent. Not for the problem-first product thesis; use product-intent.
 triggers:
   - write a PRD
   - spec this product out
   - define this feature
   - structure this product brain dump
   - create milestone prompts
-version: 0.2.2
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read

package/skills/planning/product-intent/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: product-intent
-description: Use at the start of a greenfield product effort, when the user wants a problem-first product document — "why are we building this", "write the product thesis", "PRD for this idea". Interviews for the problem, evidence, and a falsifiable hypothesis; writes an intent-only PRD with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd.
+description: "Writes a problem-first product document for a greenfield effort: interviews for the problem, evidence, and a falsifiable hypothesis, with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd."
 triggers:
   - why are we building this
   - write the product thesis
   - problem-first PRD
   - define a falsifiable product hypothesis
   - greenfield product intent
-version: 0.2.1
+version: 0.3.0
 license: Apache-2.0
 allowed-tools:
   - read

package/skills/planning/tech-spec/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: tech-spec
-description: Write a typed call-stack architecture handoff — code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only. Not for weighing approaches or deciding the design; use architecture first.
+description: "Writes a typed call-stack architecture handoff: code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only. Not for weighing approaches or deciding the design; use architecture first."
 triggers:
   - write a tech spec
   - typed call-stack handoff
   - code-shaped contracts
   - implementation-ready technical specification
   - specify execution flows
-version: 0.1.2
+version: 0.2.0
 license: Apache-2.0
 disable-model-invocation: true
 allowed-tools: