forge-pack
Forge a pack for one technology or business domain of this repo: skills, playbooks, references and adapters built from evidence, enabled only when every eval passes. Use when onboarding proposes a pack or the user asks for one.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- forge-pack
- metadata
- { "layer": "L3", "source": "EveryInc/compound-engineering-plugin@7a68002:skills/ce-setup/references/pack-scaffold.md + garrytan/gstack@47d639a:skillify/SKILL.md.tmpl", "license": "MIT" }
- description
- Forge a pack for one technology or business domain of this repo: skills, playbooks, references and adapters built from evidence, enabled only when every eval passes. Use when onboarding proposes a pack or the user asks for one.
02 资源文件 1
- 参考文档references/pack-layout.md5.6 KB
03 SKILL.md 正文
Forge a pack
A pack makes ven specific to one technology or one domain of this repo while core stays generic. It is a directory under $(ven-profile path)/packs/ that the router reads when a task touches its files, registered only after its whole eval suite passes. The tree, pack.json, placeholders, the eval runner and the registration commands are in references/pack-layout.md.
Input: a tech or domain name. Read the profile first (ven-profile show). A fact the evidence needs that the profile lacks, read from the repo; a command, record with ven-profile learn.
Writes: only the state directory. Nothing is committed to the repo. A pack below 100% is never registered.
1. Resolve the target
- Id: the name in kebab-case.
<pack dir>below means$(ven-profile path)/packs/<pack>/;<ven root>means$(ven-profile root), the directory holding ven's skills. - Kind:
techwhen the name is a dependency in the lockfiles the profile lists (ven-profile get stack.sources);domainwhen it is a business area (ven-profile get domain_nouns,$(ven-profile path)/GLOSSARY.md). Neither: ask. - No
$(ven-profile path)/packs/: runven-profile init. <pack dir>already has apack.json: the pack exists. Skip step 4 and send each new item to its forge skill. A<pack dir>withoutpack.json: stop and report it.
2. Mine the evidence
delegate read-only worker briefs, one per source. Each returns instances: source, date, file:line or link, what went wrong or was needed, and what fixed it.
- Corrections:
ven-decisions list --step correctionfirst, kept to the pack's terms; thenven-transcripts --kind corrections --since 90and--kind routesas the fallback. - Solutions: entries in
$(ven-profile path)/solutions/whose symptoms orfiles:touch the area. - Merged PRs: the code host CLI named by
ven-profile get repo.forge.cli, read-only subcommands only, plusgit log --grep. Review comments that repeat count; one-off typos don't. - Code: where the tech or domain lives (imports, domain nouns) gives
applies_when.paths, with a match count per glob; dependency names and locked versions giveapplies_when.deps; heavily used libraries are reference candidates.
Cluster the instances into items:
| Item | Bar | Forged by |
|---|---|---|
| reference | a library whose misuse shows up in the instances | forge-reference |
| adapter | a capability a skill needs that ven-profile adapters lacks |
forge-adapter |
| skill | one idea that meets the pack bar | forge-skill |
| playbook | a task shape that meets the pack bar and no core playbook fits | forge-playbook |
The pack bar is the promotion rule in encode-lessons-in-structure: 3 real instances.
- A correction a type, import rule, lint rule or hook can catch is not a skill. List it as a ratchet candidate; once the pack is registered, the ratchet skill places it in the pack's
rules/. - A cluster under the bar becomes a proposed compound entry, not pack content.
- No item clears the bar: forge nothing; report the instances and the proposed entries.
3. Preview and ask once
Show the whole plan in one message. Each skill carries its settled scope, so the approval also settles forge-skill's steps 1 and 2.
Pack <pack> (<kind>)
applies_when paths: <glob> (<n> files), ... deps: <name> <locked version>, ...
references <library> <version>
adapters <capability> via <existing tool | script>
skills <name> (L2|L3): <one idea>
trigger: <words a task uses> boundary: <what it never does> cites: ven:<name>
evidence: <n> instances, one line each
playbooks <name>: <task shape> (<n> instances)
deferred ratchet: <corrections>; compound: <clusters under the bar>
evals <cases planned>; at most $15 per suite run
writes <pack dir>, the profile's packs
Ask with a multiple-choice question when your agent has one: forge it, change the plan, or stop. Write nothing before "forge it". As a subagent, return VEN-RESULT: BLOCKED: approve the pack plan with the preview.
4. Scaffold
- Copy
<ven root>/setup/assets/templates/pack/to<pack dir>, rename itscases/toevals/, and fill every placeholder. Done whengrep -rn '{{' <pack dir>prints nothing. <pack dir>/pack.jsonparses and names the pack, its version and owner.
5. Forge the items
In this order, since each kind uses the ones before it:
- Each reference: forge-reference.
- Each adapter: forge-adapter.
- Each skill: forge-skill, from its step 3; the approved plan is its evidence and scope.
- Each playbook: forge-playbook.
Each forge skill writes its own entry into pack.json and runs its own cases. An item that cannot be proven is dropped and reported, never shipped half-done.
6. Prove the pack
ven-lint-skills --pack <pack dir>passes.- The whole suite scores 1.00 on every case, through the runner in the reference, at
--runs 3 --max-cost-usd 15. A failing case goes back to its item's forge skill; rerun the suite after each fix. Never lower--threshold.
7. Register
- Follow "Register" in the reference.
- Record it:
ven-decisions add --step forge-pack --decision "registered <pack>: <n> skills, <n> playbooks" --evidence "suite <n>/<n> at 3 runs". - Tell the user which files now bring in which skills.
Promote
A pack with nothing specific to this repo or to a business domain (kind tech, generic globs, no glossary terms) can serve other repos. Offer it; promote only on the user's yes, following "Promote" in the reference.
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.