forge-adapter
Write a capability adapter (import graph, boundaries, schema, search, symbols, workspaces, custom rules) as a script with a fixture test, register it in adapters.json and prove it. Use when a skill reports a missing or unproven adapter, or a pack needs a capability.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- forge-adapter
- metadata
- { "layer": "L3", "source": "cursor/plugins@1e5c90a:pstack/skills/create-verification-skill/SKILL.md", "license": "MIT" }
- description
- Write a capability adapter (import graph, boundaries, schema, search, symbols, workspaces, custom rules) as a script with a fixture test, register it in adapters.json and prove it. Use when a skill reports a missing or unproven adapter, or a pack needs a capability.
03 SKILL.md 正文
Forge an adapter
Visual and conventions skills ask for a capability with ven-profile adapter <capability>; the adapter is the repo-specific command behind it. An adapter that was never executed is a draft: it counts only once its fixture test and ven-profile prove-adapters both pass.
Input: a capability and the pack that will hold the script. The usual trigger is ven-profile adapter <capability> exiting 3 with "no adapter" or "prove it first". Here <pack dir> is $(ven-profile path)/packs/<pack>/, <ven root> is $(ven-profile root), and <slug> is the capability with . replaced by -.
Capabilities
| Capability | Prints | Exits 1 when |
|---|---|---|
graph.imports |
module import edges, JSON [{from,to}] |
never |
graph.boundaries |
boundary violations, JSON [{from,to,rule}] |
never |
schema.read |
entities, JSON {entities:[{name,fields,relations}]} |
never |
code.search |
path:line:text lines matching {pattern} |
never |
symbols.list |
name kind line for the symbols in {file} |
never |
workspace.list |
workspaces or containers, JSON | never |
lint.custom, rules.structural |
path:line: rule: message per violation |
it finds a violation |
The template's FORMAT map prints these shapes; collect() only gathers the data.
1. Pick the source
Look before writing: ven-profile adapters (an unproven entry may only need a fix), the repo's dev dependencies and scripts, and tools on the PATH (command -v <tool>). Prefer, in order:
- A tool the repo already has, wrapped so its output takes the capability's shape.
- A script that reads the files itself, using only the runtime ven's own tools need.
- A new tool, only with the user's consent. Ask the user: what it is, where it installs, and the script you would write instead. Never install without a yes.
2. Fixture first
- Build
<pack dir>/adapters/fixtures/<slug>/repo/: the smallest copy of real repo files that exercises the capability, including one awkward case the repo really has. - Write
<pack dir>/adapters/fixtures/<slug>/expected.txtby hand, from reading those files: the exact output, ending in a newline. - Copy
<ven root>/setup/assets/templates/adapter/adapter.test.mjsto<pack dir>/adapters/<slug>.test.mjsand fill its placeholders. node --test <pack dir>/adapters/<slug>.test.mjsfails: there is no script yet. That is the red run.
3. Write the script
Copy <ven root>/setup/assets/templates/adapter/adapter.mjs to <pack dir>/adapters/<slug>.mjs and write collect():
- Read-only: it never writes to the repo and never calls the network.
- Deterministic: sorted output and repo-relative paths, so two runs diff clean.
- Scoped: it honors
--rootand takes its file list fromgit ls-files, so ignored and generated files stay out. - Baseline-aware: a rule capability reports only violations missing from
$(ven-profile path)/baseline/<capability>.txt, so today's tree exits 0.
Done when the fixture test passes.
4. Run it on the real repo
Run node <pack dir>/adapters/<slug>.mjs --root=<repo root> with the arguments a skill would pass. Check three entries against the files they name, and one fact you know must appear. A wrong entry is a missing fixture case: add it to the fixture (red), fix collect() (green), run again. Apply prove-it-works: the output you read is the proof, not the passing test alone.
5. Register and prove
-
Add the command under the capability in
$(ven-profile path)/adapters.json, keeping only the flags the capability uses:"<capability>": { "run": "node '<pack dir>/adapters/<slug>.mjs' --root=. --file={file} --pattern={pattern}", "status": "unverified", "cwd": ".", "timeout_s": 120, "evidence": "<pack dir>/adapters/<slug>.test.mjs" }Replacing an entry whose status is
verifiedneeds the user's yes. -
Prove it with the arguments a skill would pass:
ven-profile prove-adapters <capability> --file <path>(or--var pattern=<a word that exists>) printsokand records the result underproof. A bareven-profile prove-adaptersmust pass too; the template treats an unfilled{file}or{pattern}as absent. -
ven-profile adapter <capability>with the same arguments prints what step 4 printed. -
Add
{ "capability", "script": "adapters/<slug>.mjs", "test": "adapters/<slug>.test.mjs" }toadaptersin<pack dir>/pack.json, and bump its patchversion.
Then rerun the skill that asked for the capability.
04 同仓库更多 Skills
yeet
Take every local change green through the repo's own checks, slice it into conventional commits, push, and with --pr open a pull request on the code host. Use only when the user explicitly asks to yeet, or to commit and push everything; never on your own initiative.
write-docs
Write or update documentation from the code: gather facts, pick the shape for the reader, write it plain, and prove every command and path in it. Use when asked to document a repo, module or feature, or to bring stale docs up to date.
why
Find why code is shaped the way it is (design rationale, trade-offs, regressions, odd thresholds) from history, tickets, docs and chat, citing every claim and stating its confidence. Use for 'why does X work this way', 'why did we pick Y', or before changing code whose purpose is unclear.
verify
Prove a change works with the check that matches its type, do the read-back, and log the pass against the exact tree. Use when a change is ready to call done, before review, commit or stopping, and whenever ven-decisions end refuses an unverified tree.
unslop
Cut AI writing tells (filler, model vocabulary, metaphor nouns, hedging, formatting tics) from text while keeping every fact. Use when editing or checking any prose before it ships: docs, PR bodies, reports, skill text.
type-discipline
Apply when designing types or data shapes, reviewing a signature, or handling outside data, in any language. Make wrong states fail early: in the compiler for typed languages, in validated runtime contracts for untyped ones.