Extend - you know the basics, now build on them
Write a pack.
Point a host at it.
Once you can write a valid pack.json, the next step is making it do something - and making a host actually load it. This page is the hobbyist path: the two entry profiles, the deeper check that imports your entry, and the conformance harness that proves a loader honors the spec. Everything here is grounded in SPEC v1; nothing is invented.
Step 1 - pick a profile
A pack's entry is an ES module with a default export. What that default export is depends on the profile the host declares - a pack never changes its own semantics based on who loads it. Two profiles ship today.
◆scenario - attack the transport
Default export carries name, description, and an attacks[] array (kebab-case names, each with a run function or a steps chain). Hostile scenarios run against a transport; the host provides isolation (a fake transport, opt-out postures) and may use the armedByKey ceremony. Loaded by crashtest, vant, gistory, prestruct.
◆check - read files on disk
Default export is { checks: [Check] } - declarative, pure-reading verifiers over files. No transport, no network by default. Arming is just config enumeration: being listed in the host's packs: config is the arm. Loaded by poststruct, govstruct, eyestruct, monoforge.
The module-shape contract is host-owned in full - the profile page links to the host's reference rather than copying it, because doc drift is worse than indirection (SPEC §3).
Step 2 - check it deeper
The shallow lint checks the manifest. --deep goes further: it imports each declared entry in an isolated child and censuses the ids, so the spec's own load-time refusals surface at author time instead of at load.
# shallow: manifest + directory contract npx packstruct lint packs/ # deep: + import each entry in a child, census ids npx packstruct lint packs/ --deep # refuse id collisions against a host library npx packstruct lint packs/ --deep --against ./host-lib.mjs
| What --deep adds | Refusal it names |
|---|---|
| entry fails to import, or has no default export | entry-import / entry-default-export |
| duplicate id within one pack | id-duplicate |
| id collides across packs | id-collision |
| id collides with the host's library | id-library-collision |
A hostile entry is killed on a timeout or an output cap and refused nameably - it is never run in the linter's own process. These are the spec's own load-time refusals surfaced early, never new norms (SPEC §7).
Step 3 - prove a loader honors the spec
Writing packs is one half. The other half is a host that loads them correctly - and "correctly" should be provable, not asserted. The conformance harness materializes bundled case packs and runs your loader over each.
# {packs} = the materialized case pack's directory path npx packstruct audit-conformance . --loader "node loader.mjs {packs}"
What the harness checks
A conforming loader exits 0 on the clean bundle and exits non-zero and names the offending pack on every violation bundle. Bundled cases cover each §5 refusal norm, a name-collision pair, and an env-claims accept case.
The loader contract
{packs} substitutes the case pack's directory path. The loader runs with CWD = the audited repo root, no network, and no implicit host config. A loader that times out or crashes is a failure, never a pass.
The claims lane
--claims additionally requires the loader to echo a pack's declared env block on one stdout line - so a loader that silently ignores claims is named, not passed (packstruct#71).
Exit ladder, same as lint: 0 all cases honored / 1 any case failed / 2 usage.
Step 4 - add a new host (a "traveler")
Building a whole new engine that loads packs? You join the grammar by answering three questions the spec already structures - never by forking the manifest (SPEC §10).
env, plugins, package, implements). Nothing to fork or re-declare.packstruct lint and audit-conformance lanes. A new profile only extends the cases reported, never the manifest grammar.audit-conformance keyed to your profile id.A traveler inherits the standing refusals unchanged: no remote packs, no runs inside lint, no schemaVersion bump for additive rows, and exact-pin companion receipts.
House rules that keep packs honest
Four norms every pack and host follows. They are lifecycle rules, not manifest fields - so the schema never moves for them.
Self-audit fixtures
Every pack ships test/fixtures/ proving its contents do what they claim. A pack whose fixtures fail fails its own CI, host-first.
Pack version is the pack's own
A pack.json version bumps only when that pack's surface changes - never when the linter or a consumer ships. Frozen packs stay frozen.
Explicit loads only
A pack runs because the host's config names it. No remote or npm packs in v1, no auto-download - adding that would need an explicit spec bump.
Interop through the front door
If your pack needs a sibling tool, go through that tool's public CLI - never by importing its internals or guessing a path when an npx resolution exists (SPEC §8).
Building something with it?
Two things help most: tell us your use case (so the spec does not grow in the wrong direction), and file the rough edges you hit.