@skillit/client 0.2.0 → 0.4.0

package/skills/skillit-bootstrap/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: skillit-bootstrap
+description: 'Bootstrap an AI-agent skill from a TypeScript codebase by running the deterministic skillit generate/audit loop and enriching repo source (JSDoc, README, config-type properties, MCP tool annotations, examples, package.json) until the skill reaches its grade target. Use for cli, typedoc, config, or mcp (build-mode) projects; never edit SKILL.md/references directly.'
+version: 0.1.0
+toSkills:
+  managed: bundled-orchestrator
+---
+
+# skillit-bootstrap
+
+Bootstrap a high-quality AI-agent skill from a TypeScript codebase. You run the
+deterministic skillit pipeline, read its machine-readable findings, and enrich
+the **repo source** (JSDoc, README, examples, package.json) until the generated
+skill reaches its grade target. skillit owns the skill output; you own the
+inputs.
+
+## The one hard rule
+
+**Never create or edit any `SKILL.md` or `references/*.md` for the target
+project.** Those are pure outputs of `skillit gen` — regenerated every pass. You
+edit only repo _source surfaces_. If you find yourself about to write a
+`SKILL.md`, stop: the fix belongs in the source the skill is generated from.
+
+## When to use
+
+- A `cli` (Commander), `typedoc` (TypeScript library), `config` (a TypeScript
+  config type), or `mcp` (an MCP server whose TS source you own — "build mode")
+  project that needs a generated agent skill, or whose skill scores below its
+  grade target.
+- Run after the project is set up with the right `@skillit/*` package (see
+  step 1).
+- **Third-party MCP servers you cannot edit** are out of scope here: with no
+  editable source, the skill is produced from an overlay ("runtime mode") via
+  `skillit refine`. This loop targets the build-mode (own-source) path. See
+  `references/surface-routing.md`.
+
+## Inputs
+
+```
+/skillit-bootstrap [--source cli|typedoc|config|mcp] [--program <file#export>]
+                   [--config-type <file#export>] [--mcp <path>] [--server <name>]
+                   [--out <dir>] [--grade A|B|C] [--max-iterations <n>]
+                   [--ground <glob>...]
+```
+
+- `--source` — override detection (`cli`, `typedoc`, `config`, or `mcp`).
+- `--program` — Commander program entry for the cli source (`./dist/cli.js#program`).
+- `--config-type` — config type entry for the config source (`./src/config.ts#MyConfig`).
+- `--mcp` — path to `mcp.json` / MCP config file (mcp source).
+- `--server` — MCP server entry to select when the config lists several (mcp source).
+- `--out` — skill output dir (default `skills`).
+- `--grade` — override the kind-aware target (below).
+- `--max-iterations` — hard cap on enrich/regenerate passes (default 5).
+- `--ground <glob>` — consumer/implementation code you MUST read before writing
+  any runtime-behavior pitfall, so your claims reflect real behavior, not guesses.
+
+## The loop
+
+1. **Set up once.** Determine the source kind (honor `--source`, else infer:
+   `commander`/`yargs` dep → cli; `@modelcontextprotocol/sdk` dep → mcp;
+   otherwise a TS library → typedoc). `config` is never auto-detected — select it
+   explicitly with `--config-type <file#export>`. Each kind has its own selector:
+   cli → `--program`, config → `--config-type`, mcp → `--mcp` (+ optional
+   `--server`); typedoc needs none. If the project has no `@skillit/*` package
+   installed yet, run `skillit init --source <kind>` once (it installs + wires
+   only; it does not generate).
+2. **Generate.** Run `skillit gen --source <kind> <selector> [--out …]` (the
+   selector is the kind's from step 1). This deterministically produces the skill
+   from current source. Never hand-edit its output. (For mcp, `gen` spins up the
+   server to introspect it, so the source skill is a function of a deterministic
+   server.)
+3. **Audit.** Run `skillit audit --source <kind> <selector> --json` and read
+   the JSON: `estimate.grade`, `estimate.dimensions` (D1–D8), and
+   `improvements[]`. Each improvement carries `suggestion`, `dimension`,
+   `targets: [{file, name, kind}]`, and (when resolvable) `resolvedLocations[]`
+   pointing at the exact file + declaration to edit. **These targets are your
+   work queue.**
+4. **Enrich the source.** For each addressable finding, open the cited source
+   file and write the missing content on the named symbol/section/key, choosing
+   the surface the suggestion names. The surface → audit-code map and the
+   edit-vs-create guidance are in `references/surface-routing.md`. Before writing
+   any _runtime-behavior_ pitfall, read the relevant implementation (`--ground`
+   globs) — do not invent semantics from a type signature.
+   - Prefer the `upsertJsDocTag` / `upsertPropertyJsDocTag` helpers (exported
+     from `@skillit/core`) for JSDoc-tag writeback rather than free-hand
+     splicing — they handle `*/` escaping and multi-line prefixing.
+   - You may also **create** a new parseable artifact when that is the better
+     home (a `docs/<guide>.md`, an `examples/<name>.ts`, a missing README
+     section) — but only of a type an existing parser already consumes, and
+     never a `SKILL.md`.
+5. **Regenerate + re-audit.** Re-run step 2 then step 3. Compare the new
+   `estimate` to the previous pass.
+6. **Decide convergence** (your judgment, using these signals):
+   - **Pass** — `estimate.grade` ≥ the target. Default target is _kind-aware_:
+     typedoc/library → **A** (every export is introspectable); cli adapter-model
+     → **B**, config → **B**, mcp → **B** — these surfaces structurally cap below
+     A (a cli command tree isn't enumerated per-symbol; a config type has no
+     functions/params, so per-option routing + one example file is its ceiling;
+     mcp reaches **A** only if every tool handler carries full JSDoc). `--grade`
+     overrides.
+   - **Plateau** — the score did not rise AND every remaining finding targets a
+     symbol that genuinely has nothing more to truthfully say. You can _see_ the
+     source, so distinguish "legitimately complete" from "stuck re-drafting" —
+     stop on the former.
+   - **Cap** — never exceed `--max-iterations` (default 5).
+7. **Report.** Print the final grade, the D1–D8 breakdown, the list of source
+   files you enriched, and any remaining findings you judged un-addressable with
+   a one-line rationale each. This is the human review surface; the user commits
+   the result.
+
+## After convergence
+
+Tell the user to review the enriched source diffs and the regenerated skill,
+then commit. Remind them the skill is reproducible: `skillit gen` on the same
+source yields byte-identical output, so the source diff is the real change.

package/skills/skillit-bootstrap/references/surface-routing.md

@@ -0,0 +1,108 @@
+# Enrichment surface routing
+
+For each audit finding, edit the **source surface** named here — never the
+generated `SKILL.md`. The audit `suggestion` text already names the surface;
+this table is the quick reference. (Source: skillit architecture spec §2.3/§4.)
+
+| Audit codes        | Enrichment surface (what you edit) | How                                                                        |
+| ------------------ | ---------------------------------- | -------------------------------------------------------------------------- |
+| F4                 | Symbol JSDoc summary               | `/** … */` on the function/class/type/enum/variable                        |
+| E1, E2             | `@param` / `@returns` prose        | on parameters and non-void returns                                         |
+| E3                 | Interface/type property JSDoc      | `/** … */` on each property                                                |
+| W7, W8, W9         | Routing tags                       | `@useWhen` / `@avoidWhen` / `@never` (render as pitfalls)                  |
+| W10, W11, W3       | Depth tags                         | `@remarks` (complex fns), `@category`, `@since`/`@throws`/`@see`           |
+| W1, W5             | Module docs                        | `@packageDocumentation` summary + `@remarks`                               |
+| E4, W2             | Examples                           | sibling `*.example.ts` / `examples/*`, or `@example` blocks on key exports |
+| F3, W5, W6, A4     | README sections                    | Features / Troubleshooting / Quick Start, intro blockquote                 |
+| F1, F2, E5, W4, A1 | package.json metadata              | `description`, `keywords` (≥5, ≥3 domain), `repository`                    |
+
+Use the `upsertJsDocTag` / `upsertPropertyJsDocTag` helpers (exported from
+`@skillit/core`) for tag writeback — they escape `*/` and prefix multi-line
+content correctly. Free-hand JSDoc splicing is error-prone.
+
+## Edit vs. create
+
+Editing an existing surface is the common move, but you may **create** a new
+artifact when it is the better home for missing content — e.g.:
+
+- a `docs/<guide>.md` page (consumed by skillit's docs scanner → `skill.documents`);
+- an `examples/<name>.ts` or sibling `*.example.ts` (consumed by the examples scanner);
+- a `## Troubleshooting` / `## Features` section a README lacks.
+
+Hard constraint: the new artifact must be a type an existing skillit parser
+already consumes — **no new parser**, and never a `SKILL.md`.
+
+## Finite vs. coverage-gated findings (size the work before you start)
+
+Audit improvements come in two shapes — tell them apart before deciding how far
+a finding can move the grade:
+
+- **Finite / complexity-gated** (e.g. `@remarks` on functions with 3+ params,
+  `@category` grouping): the target set is small and enumerable. The
+  `targets[]` list **is** the whole job — close it and the dimension moves.
+- **Coverage-gated / all-or-nothing** (the D8 `@param` / `@returns` / property
+  JSDoc checks E1/E2/E3): the check fails on the **first** undocumented member
+  across the _entire_ public surface, so the points only land at ~100%
+  coverage. Here `targets[]` is only a **sample** — closing the listed symbols
+  does **not** flip the gate. Before committing, get the true remaining count
+  (`audit … --json` issue list, grouped by code) and decide: either do the full
+  sweep, or stop and report the gap. Do **not** write filler prose on internal
+  helpers just to chase the gate — that is the anti-pattern this skill exists to
+  prevent.
+
+## Grounding runtime claims
+
+Before writing any pitfall or `@never`/`@avoidWhen` rule that asserts _runtime
+behavior_, read the implementation (the `--ground` globs, or the function body).
+A fluent, well-structured claim that is factually wrong is invisible to the
+deterministic audit — the safeguard is that you actually read the code.
+
+## Per-kind headline surface
+
+The table above is kind-independent (any project has README + package.json). The
+_headline judgment_ of the skill lives in a kind-specific surface:
+
+- **typedoc** — per-symbol JSDoc on exported functions/classes/types (the richest
+  surface; every export is introspectable). Writeback: `upsertJsDocTag`.
+- **cli** — JSDoc on the command's `<Command>Options` interface; `CliRefineSource`
+  correlates the option-interface tags onto the command surface.
+  - Targets have `kind: "command"` and map to `<PascalName>Options`
+    (e.g. `callHierarchy` → `CallHierarchyOptions`).
+  - **`resolvedLocations` null** → the interface doesn't exist yet. Create it in
+    any `.ts` file inside the source glob (e.g. `src/command-options.ts`). No
+    properties needed — only the JSDoc block:
+    ```ts
+    /** @useWhen - <scenario> @avoidWhen - <alt> @never - NEVER … Fix: … */
+    interface CallHierarchyOptions {}
+    ```
+    After `skillit gen` + re-audit, `resolveTargetLocation` will find the interface
+    and subsequent `skillit refine` passes can write tags into it directly.
+  - For an adapter-model CLI (no static command tree), enrich the stable exported
+    symbols together with `@packageDocumentation` instead.
+- **config** — **per-property** JSDoc on the config type's properties:
+  `@useWhen`/`@avoidWhen`/`@pitfalls`/`@remarks` on each option, plus a sibling
+  `<config>.example.ts` (written only if absent — never clobbered) for the
+  example finding. Findings carry a dot-path `configKey`; `resolveTargetLocation`
+  returns `{ file, declName, propertyPath }`. Writeback: `upsertPropertyJsDocTag`.
+  - **Tag note:** the config surface authors pitfalls as **`@pitfalls`** (what
+    `config-extract` reads), NOT `@never` (the typedoc/JSDoc surface's tag — see
+    spec §4.2 naming note). On a config option, `@never` is silently ignored.
+    `@category` is likewise not scored on config options — don't chase it there.
+- **mcp (build mode)** — JSDoc on the tool-handler symbols **plus**
+  `_meta.toSkills.{useWhen,avoidWhen,pitfalls}` annotations in your TS server
+  source. `resolveTargetLocation` resolves a tool to its `{ file, declName }`.
+  Writeback: `upsertJsDocTag`. (`gen`/`audit --source mcp --mode build`.)
+- **mcp (runtime mode)** — the server source is **not** editable, so the only
+  writable surface is the overlay JSON. This is handled by `skillit refine`'s
+  overlay path, **not** this loop — there is nothing to enrich in source.
+
+## Scope
+
+- **Supported:** `cli` (Commander), `typedoc` (TS library), `config` (a config
+  type via `--config-type`), and `mcp` **build mode** (an MCP server whose TS
+  source you own, via `--mcp` + optional `--server`).
+- **Runtime mode** (third-party MCP servers, no editable source) is served by
+  `skillit refine`'s overlay path, not this loop.
+- Kind-aware grade targets: typedoc → A; cli → B; config → B; mcp → B (A only if
+  every tool handler carries full JSDoc). A non-enumerated command tree, a
+  function-less config type, and a thinly-annotated tool set each cap below A.

package/CHANGELOG.md

@@ -1,32 +0,0 @@
-# @skillit/client
-
-## 0.2.0
-
-### Minor Changes
-
-- [#41](https://github.com/pradeepmouli/skillit/pull/41) [`989f899`](https://github.com/pradeepmouli/skillit/commit/989f899fd506f422d67c808bce8b5302f11986c6) Thanks [@pradeepmouli](https://github.com/pradeepmouli)! - - fix(client): guard msg.content[0] access — throw on empty or non-text response
-  - fix(typedoc/refine): fix JSDoc closer indentation + use async fs I/O in TypeDocRefineSource
-  - feat(client): add skillit bin with refine command
-  - feat(client): add AnthropicModelClient (Sonnet drafter, Opus reviewer)
-  - feat(client): scaffold @skillit/client package
-
-- [#53](https://github.com/pradeepmouli/skillit/pull/53) [`95caa9e`](https://github.com/pradeepmouli/skillit/commit/95caa9e1d0ed3e6562470940b857a83bc8e4a37a) Thanks [@pradeepmouli](https://github.com/pradeepmouli)! - `refine` and `init` gain `--model-client api|claude|codex|copilot`: drive the
-  audit→draft→review loop through an already-authenticated agent CLI instead of
-  the Anthropic API. Per-CLI adapters (claude maps the drafter/reviewer split to
-  Sonnet/Opus; codex/copilot use their default model) reuse the existing prompt
-  builders and verdict parser; `--model-cli-timeout` bounds each call. Default
-  remains `api`.
-
-- [#52](https://github.com/pradeepmouli/skillit/pull/52) [`30e9f03`](https://github.com/pradeepmouli/skillit/commit/30e9f03756bb3596e0cf90bb91beb37dd6bb9c18) Thanks [@pradeepmouli](https://github.com/pradeepmouli)! - Multi-source `refine` (CLI), `skillit init`, ast-grep-based JSDoc editing, and guidance injection.
-  - **core**: new `refine/ast-edit.ts` wrapping `@ast-grep/napi` — `upsertJsDocTag`/`readJsDocTags` replace the regex/offset JSDoc surgery; `insertJsDocTag` reimplemented on top of it. `RefineSource.guidance?()` and `guidance` on draft/review requests; `refineSkill` threads the source's bundled guidance skill into every draft/review. `audit-score` surfaces CLI command annotation gaps as work items.
-  - **cli**: `CliRefineSource` (extract → bundled `skillit-cli-docs` guidance → JSDoc write-back onto the correlated `*Options` interface); commander program loader (`--program file#export` + `bin` auto-find); `*Options` interface JSDoc reader for loop closure.
-  - **client**: `refine` is source-aware — `--source cli|mcp|typedoc` with detection from installed `@skillit/*` packages, plus `--program`; `--mcp` no longer globally required. New `skillit init` command: detect project nature → install the matching package → generate the initial skill into top-level `skills/` → refine (CLI path automated; mcp/typedoc print next-step guidance).
-
-### Patch Changes
-
-- [#54](https://github.com/pradeepmouli/skillit/pull/54) [`314f9b0`](https://github.com/pradeepmouli/skillit/commit/314f9b0218304e40d6fa6da628fcb112d2940912) Thanks [@pradeepmouli](https://github.com/pradeepmouli)! - Rebrand `@to-skills` → `@skillit`: package scope, a single `skillit` CLI (MCP commands now mounted as `skillit mcp …`), bundled skill names (`skillit-cli-docs`/`skillit-docs`/`skillit-mcp-docs`), and the `package.json` config key (`skillit.mcp`). No API or behavior changes.
-
-- Updated dependencies [[`989f899`](https://github.com/pradeepmouli/skillit/commit/989f899fd506f422d67c808bce8b5302f11986c6), [`9699e6f`](https://github.com/pradeepmouli/skillit/commit/9699e6f9896f4153ecdad6b1bbc87ead20e773ef), [`30e9f03`](https://github.com/pradeepmouli/skillit/commit/30e9f03756bb3596e0cf90bb91beb37dd6bb9c18), [`314f9b0`](https://github.com/pradeepmouli/skillit/commit/314f9b0218304e40d6fa6da628fcb112d2940912)]:
-  - @skillit/cli@0.4.0
-  - @skillit/core@1.5.0
-  - @skillit/mcp@0.3.0

package/scripts/gen-refine-cli-skill.mjs

@@ -1,48 +0,0 @@
-// Dogfood: generate a skill for the `skillit` CLI binary (the `refine` command)
-// using @skillit/cli's own commander introspection.
-//
-// Run via the package script (builds first):  pnpm --filter @skillit/client gen-cli-skill
-// Or directly, after building @skillit/client:  node packages/client/scripts/gen-refine-cli-skill.mjs
-import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
-import { Command } from 'commander';
-import { extractCliSkill, writeCliSkill } from '@skillit/cli';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const repoRoot = resolve(here, '../../..');
-
-// This script reads the refine command from build output. `dist/` is not in the
-// repo by default, so fail with an actionable message rather than a raw
-// ERR_MODULE_NOT_FOUND when it is missing or stale.
-const refineDist = resolve(here, '../dist/commands/refine.js');
-if (!existsSync(refineDist)) {
-  console.error(
-    `Cannot find ${refineDist}.\nBuild @skillit/client first:  pnpm --filter @skillit/client build`
-  );
-  process.exit(1);
-}
-const { buildRefineCommand } = await import(refineDist);
-
-// Reconstruct the same program shape that packages/client/src/bin.ts ships.
-const program = new Command('skillit').description('skillit CLI').version('0.1.0');
-program.addCommand(buildRefineCommand());
-
-const skill = await extractCliSkill({
-  program,
-  metadata: {
-    name: 'skillit-refine',
-    description:
-      'Autonomously improve an MCP skill via the skillit audit→draft→review loop (build or runtime mode)',
-    keywords: ['skillit', 'refine', 'mcp', 'skill-generation', 'cli', 'audit', 'overlay'],
-    repository: 'https://github.com/pradeepmouli/skillit'
-  }
-});
-
-writeCliSkill(skill, { outDir: resolve(repoRoot, 'skills') });
-
-const issues = skill.audit?.issues ?? [];
-console.log(`Generated skills/skillit-refine/ — ${issues.length} audit finding(s).`);
-for (const i of issues) {
-  console.log(`  [${i.severity ?? '?'}] ${i.code ?? ''} ${i.message ?? ''}`.trimEnd());
-}

package/src/__tests__/anthropic-model.test.ts

@@ -1,45 +0,0 @@
-// packages/client/src/__tests__/anthropic-model.test.ts
-import { describe, it, expect } from 'vitest';
-import { parseReviewVerdict } from '../model/anthropic.js';
-
-describe('parseReviewVerdict', () => {
-  it('parses accepted verdict', () => {
-    const text = 'Looks good. {"verdict":"accepted","feedback":""}';
-    expect(parseReviewVerdict(text)).toEqual({ verdict: 'accepted', feedback: '' });
-  });
-
-  it('parses revise verdict', () => {
-    const text = '{"verdict":"revise","feedback":"Be more specific about edge cases"}';
-    expect(parseReviewVerdict(text)).toEqual({
-      verdict: 'revise',
-      feedback: 'Be more specific about edge cases'
-    });
-  });
-
-  it('fails open on malformed JSON — returns accepted', () => {
-    expect(parseReviewVerdict('not json at all')).toEqual({ verdict: 'accepted', feedback: '' });
-  });
-
-  it('fails open on missing verdict field', () => {
-    expect(parseReviewVerdict('{"feedback":"ok"}')).toEqual({
-      verdict: 'accepted',
-      feedback: 'ok'
-    });
-  });
-
-  it('parses revise verdict when feedback contains balanced braces', () => {
-    const text = '{"verdict":"revise","feedback":"handle {edge-case} and {null} inputs"}';
-    expect(parseReviewVerdict(text)).toEqual({
-      verdict: 'revise',
-      feedback: 'handle {edge-case} and {null} inputs'
-    });
-  });
-
-  it('parses revise verdict when feedback contains an unbalanced open brace', () => {
-    const text = '{"verdict":"revise","feedback":"use {var in templates"}';
-    expect(parseReviewVerdict(text)).toEqual({
-      verdict: 'revise',
-      feedback: 'use {var in templates'
-    });
-  });
-});

package/src/__tests__/anthropic-prompt.test.ts

@@ -1,102 +0,0 @@
-// packages/client/src/__tests__/anthropic-prompt.test.ts
-import { describe, it, expect } from 'vitest';
-import { buildDraftPrompt, buildReviewPrompt } from '../model/anthropic.js';
-import type { DraftRequest, ReviewRequest, ExtractedSkill } from '@skillit/core';
-
-const baseSkill = (): ExtractedSkill =>
-  ({ name: 'my-tool', functions: [] }) as unknown as ExtractedSkill;
-
-const baseDraftReq = (overrides: Partial<DraftRequest> = {}): DraftRequest => ({
-  toolName: 'tool_a',
-  tag: 'useWhen',
-  suggestion: 'Add @useWhen annotation',
-  currentValue: undefined,
-  skill: baseSkill(),
-  ...overrides
-});
-
-const baseReviewReq = (overrides: Partial<ReviewRequest> = {}): ReviewRequest => ({
-  toolName: 'tool_a',
-  tag: 'useWhen',
-  draft: 'Use this tool when listing files',
-  suggestion: 'Add @useWhen annotation',
-  skill: baseSkill(),
-  ...overrides
-});
-
-describe('buildDraftPrompt', () => {
-  it('includes a Conventions section with guidance text when guidance is provided', () => {
-    const req = baseDraftReq({ guidance: 'Always use active voice.' });
-    const prompt = buildDraftPrompt(req);
-    expect(prompt).toContain('Conventions');
-    expect(prompt).toContain('Always use active voice.');
-  });
-
-  it('does NOT include a Conventions section when guidance is undefined', () => {
-    const req = baseDraftReq({ guidance: undefined });
-    const prompt = buildDraftPrompt(req);
-    expect(prompt).not.toContain('Conventions');
-  });
-
-  it('does NOT include a Conventions section when guidance is absent', () => {
-    const req = baseDraftReq();
-    const prompt = buildDraftPrompt(req);
-    expect(prompt).not.toContain('Conventions');
-  });
-
-  it('still includes core prompt content regardless of guidance', () => {
-    const req = baseDraftReq({ guidance: 'Some guidance.' });
-    const prompt = buildDraftPrompt(req);
-    expect(prompt).toContain('tool_a');
-    expect(prompt).toContain('@useWhen');
-  });
-
-  it('uses source-neutral framing (no hardcoded MCP) and keeps guidance', () => {
-    const req = baseDraftReq({ guidance: 'CLI conventions: use --flag syntax.' });
-    const prompt = buildDraftPrompt(req);
-    expect(prompt).not.toContain('MCP');
-    expect(prompt).toContain('skill annotations for "my-tool"');
-    expect(prompt).toContain('Conventions');
-    expect(prompt).toContain('CLI conventions: use --flag syntax.');
-  });
-});
-
-describe('buildReviewPrompt', () => {
-  it('includes a Conventions section with guidance text when guidance is provided', () => {
-    const req = baseReviewReq({ guidance: 'Always use active voice.' });
-    const prompt = buildReviewPrompt(req);
-    expect(prompt).toContain('Conventions');
-    expect(prompt).toContain('Always use active voice.');
-    expect(prompt.indexOf('Conventions')).toBeLessThan(prompt.indexOf('Respond with JSON only'));
-  });
-
-  it('does NOT include a Conventions section when guidance is undefined', () => {
-    const req = baseReviewReq({ guidance: undefined });
-    const prompt = buildReviewPrompt(req);
-    expect(prompt).not.toContain('Conventions');
-  });
-
-  it('does NOT include a Conventions section when guidance is absent', () => {
-    const req = baseReviewReq();
-    const prompt = buildReviewPrompt(req);
-    expect(prompt).not.toContain('Conventions');
-  });
-
-  it('still includes core prompt content regardless of guidance', () => {
-    const req = baseReviewReq({ guidance: 'Some guidance.' });
-    const prompt = buildReviewPrompt(req);
-    expect(prompt).toContain('tool_a');
-    expect(prompt).toContain('@useWhen');
-    expect(prompt).toContain('Use this tool when listing files');
-  });
-
-  it('uses source-neutral framing (no hardcoded MCP) and keeps guidance + JSON instruction', () => {
-    const req = baseReviewReq({ guidance: 'CLI conventions: use --flag syntax.' });
-    const prompt = buildReviewPrompt(req);
-    expect(prompt).not.toContain('MCP');
-    expect(prompt).toContain('skill annotation draft for "my-tool"');
-    expect(prompt).toContain('Conventions');
-    expect(prompt).toContain('CLI conventions: use --flag syntax.');
-    expect(prompt).toContain('Respond with JSON only');
-  });
-});

package/src/__tests__/cli-adapters.test.ts

@@ -1,119 +0,0 @@
-// packages/client/src/__tests__/cli-adapters.test.ts
-import { describe, it, expect } from 'vitest';
-import { claudeAdapter, codexAdapter, copilotAdapter, adapterFor } from '../model/cli/adapters.js';
-import { DRAFTER, REVIEWER } from '../model/models.js';
-
-describe('claudeAdapter', () => {
-  it('maps draft role to the drafter model and review role to the reviewer model', () => {
-    const draft = claudeAdapter.invocation('draft', 'PROMPT');
-    expect(draft.cmd).toBe('claude');
-    expect(draft.args).toEqual(['-p', '--output-format', 'json', '--model', DRAFTER]);
-    expect(draft.input).toBe('PROMPT');
-    const review = claudeAdapter.invocation('review', 'PROMPT');
-    expect(review.args).toContain(REVIEWER);
-  });
-
-  it('extracts result from the claude json envelope', () => {
-    const stdout = JSON.stringify({ type: 'result', is_error: false, result: 'the answer' });
-    expect(claudeAdapter.extractResult(stdout)).toBe('the answer');
-  });
-
-  it('throws when claude reports is_error', () => {
-    const stdout = JSON.stringify({ type: 'result', is_error: true, result: 'nope' });
-    expect(() => claudeAdapter.extractResult(stdout)).toThrow(/claude/i);
-  });
-
-  it('returns an empty result string (does not editorialize)', () => {
-    const stdout = JSON.stringify({ type: 'result', is_error: false, result: '' });
-    expect(claudeAdapter.extractResult(stdout)).toBe('');
-  });
-});
-
-describe('codexAdapter', () => {
-  it('invokes codex exec --json with the prompt on stdin and no per-role model', () => {
-    const inv = codexAdapter.invocation('draft', 'PROMPT');
-    expect(inv.cmd).toBe('codex');
-    expect(inv.args).toEqual(['exec', '--json']);
-    expect(inv.input).toBe('PROMPT');
-    // role-agnostic: review uses the same invocation
-    expect(codexAdapter.invocation('review', 'PROMPT').args).toEqual(['exec', '--json']);
-  });
-
-  it('extracts the last agent_message from the jsonl stream, skipping log/noise lines', () => {
-    const stdout = [
-      'some non-json log line',
-      JSON.stringify({ type: 'thread.started', thread_id: 'x' }),
-      JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'first' } }),
-      JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'final' } }),
-      JSON.stringify({ type: 'turn.completed' })
-    ].join('\n');
-    expect(codexAdapter.extractResult(stdout)).toBe('final');
-  });
-
-  it('returns an empty final agent_message, overriding an earlier non-empty one (last-wins on empty)', () => {
-    const stdout = [
-      JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'first' } }),
-      JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: '' } })
-    ].join('\n');
-    expect(codexAdapter.extractResult(stdout)).toBe('');
-  });
-
-  it('throws when no agent_message is present', () => {
-    expect(() => codexAdapter.extractResult('{"type":"turn.completed"}')).toThrow(/codex/i);
-  });
-
-  it('surfaces a turn.failed signal in the no-message error', () => {
-    const stdout = JSON.stringify({ type: 'turn.failed' });
-    expect(() => codexAdapter.extractResult(stdout)).toThrow(/turn\.failed/);
-  });
-});
-
-describe('copilotAdapter', () => {
-  it('pipes the prompt via stdin (not argv) so untrusted content stays out of argv', () => {
-    const inv = copilotAdapter.invocation('draft', 'PROMPT');
-    expect(inv.cmd).toBe('copilot');
-    expect(inv.args).toEqual(['--output-format', 'json', '--no-color']);
-    expect(inv.args).not.toContain('PROMPT');
-    expect(inv.input).toBe('PROMPT');
-  });
-
-  it('extracts the last assistant.message content from the jsonl stream, skipping deltas/result', () => {
-    const stdout = [
-      JSON.stringify({ type: 'assistant.message_delta', data: { deltaContent: 'the ' } }),
-      JSON.stringify({ type: 'assistant.message_delta', data: { deltaContent: 'answer' } }),
-      JSON.stringify({
-        type: 'assistant.message',
-        data: { content: 'the answer', toolRequests: [] }
-      }),
-      JSON.stringify({ type: 'result', exitCode: 0 })
-    ].join('\n');
-    expect(copilotAdapter.extractResult(stdout)).toBe('the answer');
-  });
-
-  it('returns an empty assistant.message content (does not editorialize)', () => {
-    const stdout = [
-      JSON.stringify({ type: 'assistant.message', data: { content: 'first', toolRequests: [] } }),
-      JSON.stringify({ type: 'assistant.message', data: { content: '', toolRequests: [] } })
-    ].join('\n');
-    expect(copilotAdapter.extractResult(stdout)).toBe('');
-  });
-
-  it('throws when no assistant.message is present', () => {
-    expect(() => copilotAdapter.extractResult('{"type":"result","exitCode":0}')).toThrow(
-      /copilot/i
-    );
-  });
-
-  it('surfaces a nonzero result exitCode in the no-message error', () => {
-    const stdout = JSON.stringify({ type: 'result', exitCode: 1 });
-    expect(() => copilotAdapter.extractResult(stdout)).toThrow(/exitCode 1/);
-  });
-});
-
-describe('adapterFor', () => {
-  it('returns the matching adapter', () => {
-    expect(adapterFor('claude')).toBe(claudeAdapter);
-    expect(adapterFor('codex')).toBe(codexAdapter);
-    expect(adapterFor('copilot')).toBe(copilotAdapter);
-  });
-});

package/src/__tests__/cli-client.test.ts

@@ -1,58 +0,0 @@
-// packages/client/src/__tests__/cli-client.test.ts
-import { describe, it, expect, vi } from 'vitest';
-import { CliModelClient } from '../model/cli/cli-client.js';
-import { claudeAdapter } from '../model/cli/adapters.js';
-import type { DraftRequest, ReviewRequest, ExtractedSkill } from '@skillit/core';
-
-const skill = { name: 'demo' } as unknown as ExtractedSkill;
-const draftReq: DraftRequest = {
-  toolName: 'gen',
-  tag: 'useWhen',
-  suggestion: 'say when',
-  currentValue: undefined,
-  skill
-};
-const reviewReq: ReviewRequest = {
-  toolName: 'gen',
-  tag: 'useWhen',
-  draft: 'When generating',
-  suggestion: 'say when',
-  skill
-};
-
-describe('CliModelClient', () => {
-  it('draft() returns the trimmed result extracted from the adapter envelope', async () => {
-    const runner = vi.fn(async () =>
-      JSON.stringify({ type: 'result', is_error: false, result: '  When generating output  ' })
-    );
-    const client = new CliModelClient(claudeAdapter, { runner });
-    const out = await client.draft(draftReq);
-    expect(out).toBe('When generating output');
-    // the adapter's invocation was forwarded to the runner
-    expect(runner).toHaveBeenCalledWith(
-      expect.objectContaining({ cmd: 'claude', args: expect.arrayContaining(['-p']) })
-    );
-  });
-
-  it('review() parses the verdict JSON out of the adapter result', async () => {
-    const runner = vi.fn(async () =>
-      JSON.stringify({
-        type: 'result',
-        is_error: false,
-        result: 'Sure: {"verdict":"revise","feedback":"too vague"}'
-      })
-    );
-    const client = new CliModelClient(claudeAdapter, { runner });
-    const res = await client.review(reviewReq);
-    expect(res).toEqual({ verdict: 'revise', feedback: 'too vague' });
-  });
-
-  it('passes the configured timeout through to the runner', async () => {
-    const runner = vi.fn(async () =>
-      JSON.stringify({ type: 'result', is_error: false, result: 'x' })
-    );
-    const client = new CliModelClient(claudeAdapter, { runner, timeoutMs: 5000 });
-    await client.draft(draftReq);
-    expect(runner).toHaveBeenCalledWith(expect.objectContaining({ timeoutMs: 5000 }));
-  });
-});