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_SUFFIXandTERMINAL_EFFECT. They areRecord<EffectKind, …>precisely so the build breaks until "which capability licenses this?" and "does it end the dispatch?" are answered.EFFECT_KINDSderives from them; never restate the kind list anywhere else.packages/sdk/src/schemas.ts: theeffectSchemaunion 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.EffectForCapabilityin 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 (likeupdateShell), lower it in dispatch to an existing kind and mark the synthesized entry withloweredFrom, so the three adapterapply.tsreducers stay untouched. They each independently resolvekind === "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 indocs/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.tsmatrices; non-exact levels need a rationale (testkit-enforced, and rendered to users byinspect). - 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_CODESinpackages/core/src/diagnostics.ts; if the runtime can raise it, alsoRUNTIME_DIAGNOSTIC_CODESinpackages/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.mdanddocs/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:
dialecton itsShellShapesentry. 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
classifyToolapplies aReportedToolFacts.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).inspectand 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 todispatch()asshellDialect, or a view that a rewrite creates has none. - A new family:
SHELL_DIALECTSintools.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)
- Shims must never value-import
@hooknostic/core(packages/cli/src/package.test.tsenforces; it drags esbuild into every artifact). - Mutation-verify each new test against the defect it pins (AGENTS.md hard rule).
- Rebuild
examples/*/distfrom the repo root; the reproducibility gate byte-compares. - Full gates with explicit exit codes:
pnpm lint,pnpm build,pnpm test. - 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
sample
Explain the synthetic sample project.
sample
Explain the synthetic sample project.
sample
Explain the synthetic sample project.
sample
Explain the synthetic sample project.
greet
Greet the user by name and summarize the repo state.
where
Reports where this skill lives. Use when asked where the probe skill is.