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.

Profile: scenario →

◆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.

Profile: check →

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 addsRefusal it names
entry fails to import, or has no default exportentry-import / entry-default-export
duplicate id within one packid-duplicate
id collides across packsid-collision
id collides with the host's libraryid-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).

01What does the manifest see?The frozen v1 field table plus the host-owned acknowledged keys (env, plugins, package, implements). Nothing to fork or re-declare.
02What does the lint see?The same packstruct lint and audit-conformance lanes. A new profile only extends the cases reported, never the manifest grammar.
03What does "run" mean?The only new thing you own: a profile row (your execution semantics), an engine receipt per adopted behavior, and cases in 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.