AGENT SKILL

extend-vocabulary

Checklist for growing the portable vocabulary — adding or changing an Effect, capability id, diagnostic code (HNxxx), hook event, ToolKind, ShellShapes or FileShapes entry, a shell dialect (ShellDialect, tool.shell.dialect, a shape's dialect, a stated shell name), a normalized tool view (tool.shell, tool.file), or anything in packages/sdk/src/{effects,capabilities,schemas,tools,result,hook}.ts, packages/runtime/src/dispatch.ts, or an adapter's profile.ts/toolmap.ts/apply.ts.

License 许可
Apache-2.0
最近更新
2026-11-15
Stars
★ 2
Forks
0

01 前言 Front Matter

name
extend-vocabulary
description
Checklist for growing the portable vocabulary — adding or changing an Effect, capability id, diagnostic code (HNxxx), hook event, ToolKind, ShellShapes or FileShapes entry, a shell dialect (ShellDialect, tool.shell.dialect, a shape's dialect, a stated shell name), a normalized tool view (tool.shell, tool.file), or anything in packages/sdk/src/{effects,capabilities,schemas,tools,result,hook}.ts, packages/runtime/src/dispatch.ts, or an adapter's profile.ts/toolmap.ts/apply.ts.

03 SKILL.md 正文

Extending the vocabulary

The SDK's types are the portable contract; every extension has a set of twin surfaces that must move together, and each has silently shipped an inert or wrong feature when edited alone. Work through the checklist for what you're adding; finish with the shared tail.

First: does this need an ADR?

A new effect, capability semantics change, or normalization decision is a semantic-model change — write or extend docs/decisions/ (see ADR-0001, 0005, 0007 for the register). A mechanical addition inside an existing decision does not.

New or changed Effect kind

  • packages/sdk/src/effects.ts: interface + constructor + union member, and the two total records — EFFECT_CAPABILITY_SUFFIX and TERMINAL_EFFECT. They are Record<EffectKind, …> precisely so the build breaks until "which capability licenses this?" and "does it end the dispatch?" are answered. EFFECT_KINDS derives from them; never restate the kind list anywhere else.
  • packages/sdk/src/schemas.ts: the effectSchema union member, in the same edit — the schemas are .strict(), so a field added to an interface but not its zod twin is rejected at dispatch as HN401 while compiling clean. This trap has bitten four separate times.
  • EffectForCapability in effects.ts (longest-suffix-first ordering).
  • packages/runtime/src/dispatch.ts: an apply case in the effect switch. If the effect is portable-but-lowered (like updateShell), lower it in dispatch to an existing kind and mark the synthesized entry with loweredFrom, so the three adapter apply.ts reducers stay untouched. They each independently resolve kind === "replaceInput" and each suppresses a recorded rewrite on a terminal deny (denial precedence) — a new effect kind slipping past those reducers, or a reducer missing the precedence rule, diverges per adapter; both have happened.
  • Docs: effect list in docs/design.md §7, table in docs/concepts.md, composition rule 4 if terminality changed.

New capability id

  • Append to ALL_CAPABILITY_IDS (packages/sdk/src/capabilities.ts).
  • Rate it in all three packages/adapter-*/src/profile.ts matrices; non-exact levels need a rationale (testkit-enforced, and rendered to users by inspect).
  • Ask first whether the real gate is per-target at all: per-invocation knowledge (like tool shape coverage) cannot live in a build-time matrix — reuse the existing capability and document a runtime feature-detect instead (ADR-0007's reasoning).

New diagnostic code

  • DIAGNOSTIC_CODES in packages/core/src/diagnostics.ts; if the runtime can raise it, also RUNTIME_DIAGNOSTIC_CODES in packages/sdk/src/result.ts (deliberate duplication — the SDK cannot import core; core asserts the subset matches, so drift is a compile error).
  • Code table in docs/design.md and docs/glossary.md. Codes are stable: never renumber (the misfamilied HN502 is documented, not renumbered).

Shell or file shape / toolmap entry

Capture first — load the harness-capture skill. Then: one ShellShapes entry per captured tool; both codec directions derive from it, and the testkit round-trips every shell-bearing fixture. File tools go in FileShapes ({ pathKey } or { patchKey }, read side only, ADR-0026); the testkit re-classifies every file-bearing fixture and requires a fixture per entry. Uncaptured tools stay absent. A new or renamed tool name also needs its ToolKind entry — capture found OpenCode's patch tools misclassified because only the shape had been considered.

Shell dialect

ADR-0029 is the decision; this is what moves. A payload capture is not evidence for a dialect: only the interpreter that ran is, observed across the host configurations that could change it (.capture/shell-dialects).

  • A tool that pins one: dialect on its ShellShapes entry. The codec emits it, and the contract suite then requires the tool's fixtures to record it.
  • A harness that states its shell: the shim listens, the decoder receives the name as enrichment and maps it, and classifyTool applies a ReportedToolFacts.shellDialect. Map a name only after a capture saw it stated and run. Promote an enrichment fixture for a mapped name and for an unmapped one, and keep the playback assertion that a real shell call carries a dialect: it is what notices reworded prose.
  • Neither: leave it absent. Never derive it from the platform or an environment variable.
  • Always: declare which of the three it is in the adapter's shellDialect (tool, statement, none, with a rationale). inspect and the generated support page print it and the contract suite holds the table and classifier to it. A shim that hears a statement also passes the dialect to dispatch() as shellDialect, or a view that a rewrite creates has none.
  • A new family: SHELL_DIALECTS in tools.ts (the schema twin derives from it), the name map, and the three places docs list the values (design.md §6.3, concepts.md, writing-hooks-safely.md).

New normalized tool view

A view like tool.shell/tool.file moves together across: the SDK type and codec (tools.ts), the strict toolInvocationSchema twin (schemas.ts), the adapter interface (core/src/adapter.ts), each adapter's toolmap classifier, index and shim, cli/src/dispatch.ts, dispatch's setToolInput re-derive (a rewrite must never leave a view stale), the testkit contract obligations, and regenerated canonicals. It is a normalization decision, so it gets an ADR.

New adapter

docs/adding-an-adapter.md is the authoritative workflow (capture → fixtures → profile → decode/apply → shim → describeAdapterContract + packages/cli/src/coverage.test.ts SUBJECTS row). For the planning, surface inventory, probe budget and completeness gates, load harness-integration.

Shared tail (every extension)

  1. Shims must never value-import @hooknostic/core (packages/cli/src/package.test.ts enforces; it drags esbuild into every artifact).
  2. Mutation-verify each new test against the defect it pins (AGENTS.md hard rule).
  3. Rebuild examples/*/dist from the repo root; the reproducibility gate byte-compares.
  4. Full gates with explicit exit codes: pnpm lint, pnpm build, pnpm test.
  5. Update tutorials/README snippets that teach the old surface — the front page and tutorials 01–03 all carry live hook bodies that have drifted before.

04 同仓库更多 Skills