@lvlup-sw/axiom 0.2.6 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "axiom",
-  "version": "0.2.6",
-  "description": "Backend code quality skills for Claude Code. Seven skills that audit, critique, harden, simplify, and humanize your architecture — the backend half of impeccable.",
+  "version": "0.3.0",
+  "description": "Backend code quality skills for Claude Code. Nine skills that audit, critique, harden, simplify, humanize, and design-constrain your architecture — the backend half of impeccable.",
   "author": {
     "name": "LevelUp Software"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvlup-sw/axiom",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Backend code quality skills for Claude Code",
   "type": "module",
   "scripts": {
@@ -10,6 +10,7 @@
   "files": [
     ".claude-plugin",
     "skills",
+    "vendor",
     "CLAUDE.md"
   ],
   "keywords": [

package/skills/audit/SKILL.md

@@ -109,6 +109,29 @@ Output the structured report per the template in `@skills/backend-quality/refere
 [Top 3-5 prioritized action items]
 ```
 
+## Pairing Contract Check
+
+When the assessed scope contains a project-specific invariants skill (any loaded skill with frontmatter `pairs-with: axiom:design`), audit runs an advisory check against the pairing contract documented at `@skills/backend-quality/references/pairing-contract.md`.
+
+**Two checks, both LOW severity, both advisory only:**
+
+1. **Overlap declaration.** The paired skill must declare `axiom_overlap: DIM-N` for at least one of its invariants. A paired skill with zero overlap declarations is technically compliant (axiom_overlap is optional per the contract) but suggests the pairing isn't specializing axiom dimensions in any documented way — likely a documentation gap.
+2. **Overlap validity.** Each declared `axiom_overlap` value must reference a real dimension (`DIM-1` through `DIM-8`). Typos like `DIM-9` or `DIM-1A` are flagged.
+
+**Severity rationale.** Pairing-contract violations don't break functionality; they erode the design-time interleaving experience over time. LOW severity reflects that. These findings never escalate the audit verdict beyond `NEEDS_ATTENTION` and never produce HIGH/MEDIUM unless other findings independently warrant them.
+
+**Output format.** Findings carry `dimension: pairing-contract` (a meta dimension distinct from DIM-1..DIM-8) so reviewers can filter them when desired:
+
+```json
+{
+  "severity": "LOW",
+  "dimension": "pairing-contract",
+  "skill": "exarchos:design-invariants",
+  "description": "Paired skill declares pairs-with: axiom:design but no invariant has an axiom_overlap declaration.",
+  "required_fix": "Add axiom_overlap: DIM-N to at least one invariant, or update the pairing-contract declaration to reflect that this skill is project-specific without dimension overlap."
+}
+```
+
 ## Error Handling
 
 - **Empty scope (no files to assess):** Return "Nothing to assess — no files found in scope" with verdict CLEAN
@@ -125,3 +148,4 @@ For details on how audit discovers skills, handles deduplication, and formats re
 - Finding format: `@skills/backend-quality/references/findings-format.md`
 - Scoring model: `@skills/backend-quality/references/scoring-model.md`
 - Composition details: `@skills/audit/references/composition-guide.md`
+- Pairing contract: `@skills/backend-quality/references/pairing-contract.md`

package/skills/backend-quality/SKILL.md

@@ -39,3 +39,7 @@ Verdict computation and health thresholds: `@skills/backend-quality/references/s
 ## Deterministic Checks
 
 Grep patterns and structural checks per dimension: `@skills/backend-quality/references/deterministic-checks.md`
+
+## Pairing Contract
+
+How `axiom:design` composes with project-specific invariants skills via the `pairs-with` frontmatter slot: `@skills/backend-quality/references/pairing-contract.md`

package/skills/backend-quality/references/dimensions.md

@@ -27,6 +27,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: `getStore()` silently creates an in-memory store when the real store wasn't wired, causing events to be invisible across modules
 - Healthy: Constructor injection where the absence of a dependency is a startup error, not a silent fallback
 
+### Design questions
+
+- **Lifecycle ownership.** For every shared resource the design introduces, who creates it, who owns it, and where is the single source of truth?
+- **Dependency injection.** Are all dependencies passed as parameters or constructor arguments? If any are module globals, what justifies the ambient state?
+- **Fallback policy.** If a dependency isn't wired, does the system fail loud (startup error) or fall back silently? Loud is the default.
+- **Graph shape.** Sketch the dependency graph for the new code. Are there cycles? If so, justify or break them.
+
 ---
 
 ## DIM-2: Observability
@@ -54,6 +61,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: `catch { mutableState._events = [] }` — silently resets state on error, hiding the failure
 - Healthy: `catch (e) { throw new Error('Failed to load events from store', { cause: e }) }`
 
+### Design questions
+
+- **Catch posture.** For every catch block the design will introduce, what action does it take: re-throw, log with context, or document why it swallows? "Swallow silently" is never the answer.
+- **Error context.** When the new code raises an error, does the message include what failed, why, and what the caller should do? Generic messages are debt.
+- **Fallback visibility.** If the design has a fallback path, how does it announce itself (log, metric, event)? An undetectable fallback is a silent failure waiting to happen.
+- **Promise discipline.** For every `.catch()` or async error path, what's the recovery plan? Empty `.catch(() => {})` is forbidden.
+
 ---
 
 ## DIM-3: Contracts
@@ -81,6 +95,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: `_events` removed from Zod schema but guard code still reads `state._events`, silently getting `undefined`
 - Healthy: Schema changes accompanied by grep for all field references, with type system enforcing the change
 
+### Design questions
+
+- **Schema boundaries.** Where do the new types/schemas live? Is each runtime read of a field guaranteed by the schema, or is there a gap?
+- **Versioning posture.** Does this design make a breaking API change? If yes, what's the versioning or migration path? If no, what makes the change backward-compatible?
+- **Type assertions.** Will the implementation use `as` or `!` to bypass the type system? Each instance needs a documented runtime guard (`typeof`, `instanceof`, schema parse).
+- **Cross-boundary contracts.** For every interface across module/service boundaries, who validates the contract — caller, callee, or both?
+
 ---
 
 ## DIM-4: Test Fidelity
@@ -109,6 +130,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: All tests use the same EventStore instance for producer and consumer, but production has two separate instances that were never connected — 4192 tests pass, system is broken
 - Healthy: Test creates the same wiring as production startup, catching initialization bugs
 
+### Design questions
+
+- **Wiring parity.** Will the tests construct the new code's collaborators the same way production does? Where the tests diverge from production wiring, what's the rationale?
+- **Mock boundary.** What's the mocking boundary for this design — only true infrastructure (HTTP, DB, filesystem), or also internal collaborators? Internal mocking should be the exception, not the default.
+- **Integration coverage.** For every cross-cutting behavior in the design, is there at least one integration test that exercises the seam, not just unit tests on each side?
+- **Skip discipline.** Will any test be marked `.skip` during this work? If yes, what's the issue link and removal date?
+
 ---
 
 ## DIM-5: Hygiene
@@ -137,6 +165,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: `registerEventTools()` exists but is never called in production — vestigial from an earlier design that was refactored
 - Healthy: Unused code removed, version history preserves it if needed
 
+### Design questions
+
+- **Single implementation.** Does the design introduce a behavior that already exists elsewhere? If yes, is it consolidating or forking?
+- **Reachability.** For every export the new code adds, who calls it? Unused exports should be removed before the design is done.
+- **Comment policy.** Will any commented-out code be left behind? Use git history instead.
+- **Feature-flag horizon.** If the design introduces a flag, what's the removal date or condition? A flag without a sunset is debt.
+
 ---
 
 ## DIM-6: Architecture
@@ -165,6 +200,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: Event store module imports from CLI module, creating a circular dependency that constrains refactoring
 - Healthy: Event store depends on interfaces; CLI implements those interfaces
 
+### Design questions
+
+- **Dependency direction.** Do the new modules depend inward (toward the domain) or outward (toward infrastructure)? Outward dependencies in the core are a smell.
+- **Module responsibility.** Each new module: state its single responsibility in one sentence. If you need "and" or a list, split it.
+- **Interface placement.** Where do the interfaces live — at the domain boundary the consumer owns, or inside the producer's module? Domain-boundary placement is the default.
+- **Change surface.** For a representative change to this design, how many files would need editing? More than five suggests shotgun surgery.
+
 ---
 
 ## DIM-7: Resilience
@@ -194,6 +236,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: In-memory cache grows without limit as events are processed, eventually exhausting heap
 - Healthy: LRU cache with configurable max size, eviction logged for observability
 
+### Design questions
+
+- **Cache bounds.** Does the design introduce any cache, map, or buffer? What's its maximum size and eviction policy?
+- **Timeout coverage.** For every external call (HTTP, DB, file I/O), what's the timeout? "None" means hung-forever-on-failure.
+- **Retry shape.** If the design retries, what's the maximum attempt count and backoff strategy? Unbounded retry is a fork bomb.
+- **Resource lifecycle.** For every resource the design opens (file handle, connection, lock), where is the matching close, and does it run on the error path too?
+
 ---
 
 ## DIM-8: Prose Quality
@@ -222,6 +271,13 @@ Eight canonical dimensions for assessing backend architectural health. Each dime
 - Violation: "This crucial module serves as a testament to the team's commitment to fostering robust architecture. It delves into the intricate tapestry of event-sourced workflows."
 - Healthy: "This module handles event-sourced workflow state. It stores events in SQLite and rebuilds state on read."
 
+### Design questions
+
+- **Audience and tone.** Who reads the new docs/comments — domain experts, new hires, future maintainers? Calibrate language accordingly; avoid generic AI register.
+- **Specificity check.** Will the writing name concrete things (file paths, function names, exact behaviors) or hedge with abstractions ("various", "many", "robust")? Concrete wins.
+- **Voice ownership.** Does the prose sound like someone on this team wrote it, or like a chatbot summary? If a sentence could appear in any project's docs unchanged, rewrite it.
+- **Removal threshold.** For every comment the design adds, would a future reader be confused without it? If no, delete; rely on identifiers and types instead.
+
 ---
 
 ## Dimension Independence

package/skills/backend-quality/references/pairing-contract.md

@@ -0,0 +1,78 @@
+# Pairing Contract
+
+The protocol that lets `axiom:design` (the generic design-mode skill) compose with project-specific invariants skills (e.g., `exarchos:design-invariants`).
+
+This contract is the seam between the cross-domain dimension taxonomy and any one project's architectural specifics. It is documentation-and-frontmatter-only — there's no runtime registry. Skills self-describe via their frontmatter, and `axiom:design` discovers paired skills by enumerating loaded skills' frontmatter slots.
+
+## Frontmatter slots
+
+| Slot | Where (canonical position) | Type | Required | Meaning |
+|------|---------------------------|------|----------|---------|
+| `pairs-with` | project skill frontmatter, **nested under `metadata:`** | string | yes | Names the axiom skill this pairs with. Currently the only valid value is `axiom:design`. Future axiom skills may add their own pairing namespaces. Example: `metadata.pairs-with: axiom:design`. |
+| `pairs-with-pattern` | axiom skill frontmatter, **nested under `metadata:`** | glob | optional | Pattern axiom recognizes for paired project skills. Example: `metadata.pairs-with-pattern: <project>:*-invariants`. Documentation hint, not enforced. |
+| `axiom_overlap` | per-invariant in project skill body or per-finding in output | `DIM-N` (one of `DIM-1`..`DIM-8`) | optional | Names the axiom dimension this invariant specializes. Multiple overlaps are permitted (an INV may specialize both DIM-1 Topology and DIM-2 Observability). Omit when an invariant has no generic counterpart. |
+
+**Canonical position note.** All `pairs-with` and `pairs-with-pattern` slots live nested under `metadata:` in the frontmatter, matching the existing `exarchos:design-invariants` archetype. Top-level placement (`pairs-with:` directly under `---`) is **not** the canonical form and discovery implementations may not honor it.
+
+## Ordering rule
+
+When project-specific guidance and generic guidance conflict, **project-specific takes precedence semantically**.
+
+Example: DIM-1 Topology says "module-global mutable state requires documented rationale". A project's INV declares "module-global state is forbidden in this codebase". The project rule wins; the design surfaces the prohibition, not the conditional permission.
+
+This mirrors ESLint's `extends` array-order override (later entries win) and ATAM's utility-tree convention (leaves are authoritative for their scenarios).
+
+Visually, however, generic content renders first within each dimension. Generic is the broader frame; specific is the specialization. The visual order is generic → specific; the semantic order is the reverse.
+
+## Cross-reference convention
+
+Project invariants point *up* to axiom dimensions via `axiom_overlap: DIM-N`.
+
+Axiom dimensions do **not** point *down* to project invariants. The generic layer doesn't know which projects pair with it — that knowledge would be unbounded and brittle.
+
+This mirrors ATAM's utility tree: leaves reference the branch they specialize; branches don't enumerate their leaves.
+
+## Worked example
+
+`exarchos:design-invariants` is the canonical compliant project skill. Its frontmatter declares the pairing under `metadata`:
+
+```yaml
+---
+name: design-invariants
+description: "Audit a design proposal or diff against Exarchos's architectural invariants ..."
+metadata:
+  author: exarchos
+  version: 0.1.0
+  category: review
+  pairs-with: axiom:design
+---
+```
+
+> **Migration note (2026-05-09).** As of this contract's authoring, `exarchos:design-invariants` declares `metadata.pairs-with: axiom:backend-quality` (the foundation reference, pre-rename). The migration to `metadata.pairs-with: axiom:design` is tracked as a coordination PR against the exarchos repo (see this design's Definition of Done) and is **out of scope for axiom alone**. Until that PR lands, `axiom:design` discovery falls back to generic-only output for exarchos.
+
+Its complementarity matrix declares per-invariant overlap with axiom dimensions:
+
+| Finding | Axiom dimension | Design invariant |
+|---------|-----------------|------------------|
+| Lazy fallback that creates degraded EventStore | DIM-1 Topology | INV-1 (silent loss of event integrity) |
+| `console.log`-only catch in projection apply | DIM-2 Observability | INV-1 |
+| Adapter-local mutable cache for projection state | DIM-1 Topology | INV-1 + INV-2 |
+| Schema field removed but still read | DIM-3 Contracts | INV-1 if it's an event field |
+
+When `axiom:design` runs in a session with `exarchos:design-invariants` loaded, the discovered pairing causes the design conversation to interleave per-dimension generic questions with project-specific INV-N constraints — with project specifics taking precedence on conflict.
+
+## Compliance
+
+A project-specific invariants skill is **compliant** if:
+
+1. Its frontmatter declares `metadata.pairs-with: axiom:design` (nested under `metadata:`, per the canonical position above — top-level `pairs-with:` does not satisfy this rule).
+2. At least one of its invariants declares an `axiom_overlap: DIM-N` field referencing a real axiom dimension (DIM-1..DIM-8).
+3. Its structure follows the archetype: `SKILL.md` + `references/INV-N-<slug>.md` per invariant + `references/deterministic-checks.md` (per `axiom:scaffold-invariants` emit shape).
+
+`axiom:audit` may emit advisory LOW-severity findings against compliance violations. These never block the audit verdict — the contract is meant to detect drift, not enforce it.
+
+## See also
+
+- `axiom:design` skill: `@skills/design/SKILL.md`
+- `axiom:scaffold-invariants` skill: `@skills/scaffold-invariants/SKILL.md`
+- Exarchos's compliant archetype: `exarchos/.claude/skills/design-invariants/SKILL.md`

package/skills/design/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: design
+description: "Apply backend quality dimensions as design constraints during ideation. The design-mode counterpart to axiom:audit — surfaces DIM-1..DIM-8 as questions to ask while shaping a system, not as findings to report after. Pairs with project-specific invariants skills via the pairs-with frontmatter slot. Use when running /exarchos:ideate or any pre-implementation conversation. Triggers: 'apply axiom dimensions to design', 'constrain design space', 'design with quality in mind', or /axiom:design. Do NOT use for review of existing code — use axiom:audit instead."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: design
+  pairs-with-pattern: <project>:*-invariants
+  dimensions:
+    - all
+---
+
+# Design — Backend Quality as Design Constraint
+
+The design-mode entry point to axiom's dimension taxonomy. Where `axiom:audit` evaluates code that exists, `axiom:design` constrains code that's being shaped.
+
+## Triggers
+
+**Use when:**
+- Running `/exarchos:ideate` or any pre-implementation conversation
+- Sketching a new module, service, or subsystem
+- Reviewing a design proposal before commitment
+- Pairing with a project-specific invariants skill (e.g., `exarchos:design-invariants`)
+
+**Do NOT use when:**
+- Auditing existing code — use `axiom:audit` for that.
+- Targeting one specific dimension — use the specialized review skill (`axiom:critique`, `axiom:harden`, etc.).
+
+## Process
+
+1. **Read** the augmented dimension taxonomy: `@skills/backend-quality/references/dimensions.md`. Each dimension has a `### Design questions` block written for design-mode use.
+2. **Discover** any paired project-specific invariants skill loaded in this context (see Pairing Discovery below).
+3. **Render** the design conversation by walking the eight dimensions in order, surfacing the design questions and — if a paired skill is loaded — interleaving its project-specific invariants where they overlap.
+
+## Pairing Discovery
+
+`axiom:design` looks for any loaded skill whose frontmatter declares `pairs-with: axiom:design`. The lookup is by frontmatter slot, not by filename or convention path. The pairing contract is documented at: `@skills/backend-quality/references/pairing-contract.md`.
+
+Three operating modes:
+
+- **No paired skill loaded.** Run generic-only: present DIM-1..DIM-8 design questions. End with the line `No paired invariants skill detected. Run /axiom:scaffold-invariants to create one.` so the user knows the bootstrap path.
+- **One paired skill loaded.** Interleave. For each dimension, render the generic design questions first, then any project-specific invariants whose `axiom_overlap: DIM-N` matches the current dimension. Project invariants without `axiom_overlap` declarations render in a final "Project-specific only" section.
+- **Multiple paired skills loaded.** Render each under a named subsection (one per skill). The user can scope-narrow with an arg if needed.
+
+## Output Composition
+
+The dimension is the organizing axis. Within a dimension:
+
+1. Generic axiom design questions render first.
+2. Project-specific invariants (matched by `axiom_overlap`) render after.
+
+This ordering is *visual* — generic comes first because it's the broader frame. *Semantically* the precedence is reversed: when project-specific guidance and generic guidance conflict, the project-specific rule wins. This mirrors ESLint's array-order override (later `extends` entry wins) and ATAM's utility-tree convention (leaves are authoritative for their scenarios).
+
+The full ordering rule is documented in the pairing contract.
+
+## Failure Modes
+
+- **No paired skill loaded** → generic-only output, ends with: `No paired invariants skill detected. Run /axiom:scaffold-invariants to create one.`
+- **Multiple paired skills loaded** → render each under a named subsection.
+- **Paired skill declares `pairs-with: axiom:design` but has no invariants** → generic-only with: `Paired skill <name> declares pairing but has no invariants.`
+
+## References
+
+- Dimension taxonomy (dual-mode): `@skills/backend-quality/references/dimensions.md`
+- Pairing contract: `@skills/backend-quality/references/pairing-contract.md`
+- Foundation reference: `@skills/backend-quality/SKILL.md`
+- Project-specific archetype: `exarchos/.claude/skills/design-invariants/SKILL.md`

package/skills/scaffold-invariants/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: scaffold-invariants
+description: "Bootstrap a project-specific invariants skill that pairs with axiom:design. Interviews the user about the project's domain (one-line characterization, non-obvious commitments, dimension overlap, failure modes, mechanical checks) and emits a SKILL.md plus references files modeled on the design-invariants archetype. Use when starting a new project or formalizing existing architectural invariants. Triggers: 'scaffold invariants skill', 'bootstrap design skill', 'create invariants for this project', or /axiom:scaffold-invariants. Do NOT use to apply invariants — use axiom:design after scaffolding."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: meta-authoring
+  dimensions:
+    - all
+---
+
+# Scaffold Invariants — Project-Specific Skill Bootstrap
+
+Specialized skill scaffolder. Produces a project-specific invariants skill (`<project>:design-invariants` by convention) that pairs with `axiom:design` via the pairing contract.
+
+## Triggers
+
+**Use when:**
+- Starting a new project that needs its own architectural invariants formalized
+- Migrating from a verbal "we always do X" rule to a documented, testable invariant
+- Establishing the project-specific half of an `axiom:design` pairing for the first time
+
+**Do NOT use when:**
+- Updating an existing invariants skill — edit it directly.
+- Authoring a generic skill — use Anthropic's `skill-creator` (or its vendored copy if installed) for unconstrained skill creation.
+
+## Interview
+
+Five categories of questions, asked one at a time. The output of each shapes the generated skill.
+
+### 1. One-line characterization
+
+> "If you had to describe this project's runtime in one sentence, what would it be?"
+
+The answer becomes the skill's framing line. Example from Exarchos: *"a single-machine event-sourced process manager with cooperative agents."* This sentence governs every downstream invariant — if a candidate INV doesn't follow from this characterization, it doesn't belong.
+
+### 2. Non-obvious commitments
+
+> "What architectural decisions has this project committed to that aren't obvious from reading the code?"
+
+Each answer is an INV-N candidate. Examples: *"the event store is the source of truth, never state files"*, *"all phase transitions go through one HSM module"*, *"no MCP-second-class assumptions in any design"*. Aim for 3–7 invariants — fewer feels under-codified, more becomes hard to remember.
+
+### 3. Dimension overlap
+
+For each candidate INV, ask:
+
+> "Which of axiom's dimensions (DIM-1 Topology / DIM-2 Observability / DIM-3 Contracts / DIM-4 Test Fidelity / DIM-5 Hygiene / DIM-6 Architecture / DIM-7 Resilience / DIM-8 Prose) does this specialize?"
+
+The answer seeds the `axiom_overlap: DIM-N` field. An INV may overlap zero, one, or multiple dimensions. Zero means it's project-specific without a generic counterpart — valid but rarer.
+
+### 4. Failure mode
+
+For each candidate INV, ask:
+
+> "What's the failure mode if this is violated? What does the system look like when this rule breaks?"
+
+The answer seeds the severity guide. Map: *catastrophic / data-loss / silent corruption* → HIGH; *misleading / hard to debug* → MEDIUM; *cosmetic / mild* → LOW.
+
+### 5. Mechanical checks
+
+For each candidate INV, ask:
+
+> "Is there a mechanical way to detect a violation — a grep pattern, lint rule, type check, or static analysis?"
+
+The answer seeds `references/deterministic-checks.md`. If no mechanical check exists, that's fine — record "reasoning-driven; no automated check" so the human reviewer knows.
+
+## Emit
+
+After the interview completes, emit the project-specific skill structure. Default output path: `.claude/skills/<project>-design-invariants/`.
+
+Files emitted:
+
+- **`SKILL.md`** — frontmatter + body. Frontmatter includes `pairs-with: axiom:design`. Body lists the invariants with their severities, axiom-overlap declarations, and links to per-INV reference files.
+- **`references/INV-N-<slug>.md`** per invariant — one file per INV. Each file contains: framing, acceptance questions, repo-grounded checks, severity guide, worked example (violation + fix). Modeled on `exarchos/.claude/skills/design-invariants/references/INV-1-event-sourcing.md`.
+- **`references/deterministic-checks.md`** — the grep / structural / lint patterns, organized by INV-N. Modeled on `exarchos/.claude/skills/design-invariants/references/deterministic-checks.md`.
+
+Templates live at `templates/` in this skill's directory:
+- `templates/SKILL.template.md`
+- `templates/INV.template.md`
+- `templates/deterministic-checks.template.md`
+
+Each template uses `{{TOKEN}}` placeholders that are filled from interview answers.
+
+### Emit-correctness properties
+
+The generated skill must be well-formed:
+
+- Generated `SKILL.md` declares `pairs-with: axiom:design` in frontmatter (so `axiom:design` discovers it).
+- Each invariant entry declares `axiom_overlap: DIM-N` if the user named one in the interview (Q3); omits the field otherwise.
+- Generated structure mirrors `exarchos:design-invariants` exactly: `SKILL.md` + `references/INV-N-<slug>.md` per invariant + `references/deterministic-checks.md`.
+
+## Failure Modes
+
+- **Vendored skill-creator missing or stale** (`vendor/skill-creator/UPSTREAM.md` older than 30 days, or `vendor/skill-creator/` directory absent) → fall back to bundled templates only (no description tuning, no eval-prompt suggestions). Emit a one-line warning: `Vendored skill-creator not available; emitted scaffold uses bundled templates only. Sync vendor and re-run for description tuning.`
+- **Output directory already exists with content** → prompt before overwriting; default action is abort.
+- **Interview yields zero invariants** → emit a SKILL.md with empty INV section and a one-line note: `No invariants surfaced from interview. Re-run when project commitments are clearer.`
+
+## References
+
+- Pairing contract: `@skills/backend-quality/references/pairing-contract.md`
+- Project archetype: `exarchos/.claude/skills/design-invariants/SKILL.md`
+- Vendored upstream tooling: `vendor/skill-creator/SKILL.md` (full directory copy from `anthropics/skills`; reference only, not loaded as a triggerable skill)

package/skills/scaffold-invariants/templates/INV.template.md

@@ -0,0 +1,37 @@
+# {{INV_ID}}: {{INV_NAME}}
+
+{{INV_FRAMING}}
+
+## Acceptance questions
+
+{{ACCEPTANCE_QUESTIONS_LIST}}
+
+## Repo-grounded checks
+
+{{REPO_GROUNDED_CHECKS_LIST}}
+
+## Cross-cutting overlap
+
+**axiom_overlap:** `{{AXIOM_OVERLAP}}`
+
+This invariant specializes the named axiom dimension(s). When `axiom:design` runs in a paired session, this invariant renders alongside the dimension's generic Design questions.
+
+## External grounding
+
+{{EXTERNAL_GROUNDING_LIST}}
+
+## Severity guide
+
+- **HIGH:** {{SEVERITY_HIGH_DESCRIPTION}}
+- **MEDIUM:** {{SEVERITY_MEDIUM_DESCRIPTION}}
+- **LOW:** {{SEVERITY_LOW_DESCRIPTION}}
+
+## Worked example
+
+**Violation:**
+
+{{VIOLATION_EXAMPLE}}
+
+**Fix:**
+
+{{FIX_EXAMPLE}}

package/skills/scaffold-invariants/templates/SKILL.template.md

@@ -0,0 +1,65 @@
+---
+name: design-invariants
+description: "Audit a design proposal or diff against {{PROJECT_NAME}}'s architectural invariants — {{INVARIANT_SUMMARY_LINE}}. Pairs with /axiom:design — this skill is project-specific (axiom is generic). Triggers: 'check invariants', 'design conformance', or /design-invariants."
+metadata:
+  author: {{PROJECT_NAME}}
+  version: 0.1.0
+  category: review
+  pairs-with: axiom:design
+---
+
+# {{PROJECT_NAME}} Design Invariants
+
+Audits a design proposal or diff against {{PROJECT_NAME}}-specific architectural invariants. Project-scoped — these invariants govern {{PROJECT_NAME}} itself, not consumers of it.
+
+## Project framing
+
+> {{ONE_LINE_CHARACTERIZATION}}
+
+This sentence governs every invariant below. When a candidate constraint imports framework that doesn't follow from this characterization, the framing rejects it.
+
+## When to use
+
+- During design (`/exarchos:ideate`, RFC drafting), before committing.
+- During review (`/exarchos:review`), alongside `/axiom:audit`.
+- When reviewing a PR that touches {{LOAD_BEARING_SUBSYSTEMS}}.
+
+## When NOT to use
+
+- For generic backend quality — use `/axiom:*` skills.
+- For TDD / spec compliance — use the workflow's `review` skill.
+
+## Invariant references
+
+{{INVARIANT_REFERENCES_LIST}}
+
+## Finding format
+
+Match axiom's vocabulary (HIGH / MEDIUM / LOW) so reviewers don't context-switch:
+
+```json
+{
+  "verdict": "pass | conditional | fail",
+  "findings": [
+    {
+      "invariant": "INV-1",
+      "severity": "HIGH",
+      "file": "path/to/file.ts",
+      "line": 42,
+      "description": "...",
+      "required_fix": "...",
+      "axiom_overlap": "DIM-N"
+    }
+  ]
+}
+```
+
+## Pairing with axiom
+
+The seam: axiom asks *"is this code well-engineered?"*; this skill asks *"does this design respect {{PROJECT_NAME}}'s load-bearing invariants?"* A design can be axiom-clean and still violate a project invariant.
+
+For the full pairing protocol, see the axiom plugin's pairing contract at [`@skills/backend-quality/references/pairing-contract.md`](https://github.com/lvlup-sw/axiom/blob/main/skills/backend-quality/references/pairing-contract.md) (GitHub link; resolves regardless of where this generated skill is installed).
+
+## Source
+
+This skill was generated by `/axiom:scaffold-invariants` on {{GENERATION_DATE}}. Amend it directly when invariants change.

package/skills/scaffold-invariants/templates/deterministic-checks.template.md

@@ -0,0 +1,28 @@
+# Deterministic Checks
+
+Mechanical grep / structural patterns that this skill can run against the diff or working tree to surface candidate findings. These are starting points for human or agent reasoning, not verdicts. A pattern match is a *signal*, not a conclusion — confirm by reading context.
+
+Coverage is limited to invariants where mechanical detection adds value. The remaining invariants are reasoning-driven; their checks live in the corresponding `INV-N-*.md` reference files.
+
+{{DETERMINISTIC_CHECKS_PER_INV}}
+
+<!--
+Section template (per invariant with mechanical checks):
+
+## {{INV_ID}}: {{INV_NAME}}
+
+### Check {{INV_NUMBER}}.1: {{CHECK_NAME}}
+
+{{CHECK_DESCRIPTION}}
+
+```bash
+{{CHECK_COMMAND}}
+```
+
+(Add additional checks {{INV_NUMBER}}.2, {{INV_NUMBER}}.3, ... as needed.)
+-->
+
+<!--
+For invariants without mechanical checks, omit the section and rely on the
+reasoning-driven checks documented in `INV-N-*.md`.
+-->