voidmachine 0.0.0 → 4.0.0

package/core-assets/skills/void-decide/.source

@@ -0,0 +1,9 @@
+Sources for `void-decide` skill (see `docs/plans/skill-audits/void-decide.md` for full audit):
+
+- Michael Nygard, "Documenting Architecture Decisions" (2011) — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions — the original ADR format (Context / Decision / Consequences) and the immutable-record lifecycle.
+- adr.github.io / Markdown Architectural Decision Records (MADR) — https://adr.github.io/ — status and supersession lifecycle retained; sequential numbering rejected because it creates a parallel-writer coordination point.
+- joelparkerhenderson/architecture-decision-record — https://github.com/joelparkerhenderson/architecture-decision-record — templates surveyed; the terse ~50-line shape kept, heavier templates rejected.
+
+Strategy: native (no single source combines terse records, reversal-cost discipline and safe parallel authorship; retained the load-bearing format, added the rejected-alternative gate, UUID identity, exclusive one-file ownership and read-only projections).
+
+Promoted from pack-monorepo to core on 2026-06-04: ADRs are a universal craftsman concern, not monorepo-specific, and the repo meta-rule already mandates logging non-obvious decisions. Composes with plan, commit-discipline, source-driven-development (alternatives cite official docs), learn.

package/core-assets/skills/void-decide/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: void-decide
+description: Capture structural choices as one immutable ADR file with collision-free identity, explicit alternatives, reversal cost, and supersession. Use when future code depends on why.
+---
+
+# decide
+
+Use when a structural choice changes how future code is written and a future
+contributor would otherwise ask "why?". ADRs are codebase-scoped. Product or
+cross-organization strategy belongs in the product's decision system.
+
+This composes with `void-plan`: plans describe work; ADRs preserve
+the decisions behind it.
+
+## Write an ADR when
+
+- A library or platform choice creates material lock-in.
+- A naming, layout or dependency convention affects the codebase broadly.
+- Ownership, trust or deployment boundaries change.
+- A performance, availability, privacy or security trade-off is accepted.
+- A previous accepted ADR must be reversed or narrowed.
+
+Do not write one for bug fixes, preference, pure refactors or choices reversible
+in one small PR. If no credible alternative was rejected, the record is usually
+ceremony rather than a decision.
+
+## Storage contract
+
+One decision owns one Markdown file. Never append to, number from, or regenerate
+a shared index.
+
+Default location:
+
+```text
+docs/decisions/
+  2026-07-24-use-drizzle--018f43f4-3ac4-7c40-8000-000000000001.md
+```
+
+An existing project may keep an established equivalent such as
+`docs/decisions-log/` or `decisions/`.
+
+The filename contains:
+
+- an ISO date for scanning;
+- a readable slug describing the chosen direction;
+- a collision-resistant UUID used by the ADR identity.
+
+Prefer the project command when present:
+
+```sh
+void-machine decisions new \
+  --title "Adopt Server Actions for UI mutations" \
+  --slug adopt-server-actions \
+  --decider folpe
+```
+
+Without the CLI, generate a UUID locally and create the same standalone contract.
+Never inspect sibling files to allocate `NNNN`; parallel workers must not share a
+counter.
+
+## Format
+
+Keep the record terse, normally under 100 lines:
+
+```md
+---
+schemaVersion: 1
+id: "adr:018f43f4-3ac4-7c40-8000-000000000001"
+createdAt: "2026-07-24T10:15:00.000Z"
+title: "Adopt Server Actions for UI mutations"
+status: proposed
+deciders: [folpe]
+supersedes: []
+---
+
+# Adopt Server Actions for UI mutations
+
+## Context
+
+What forces, constraints and pain make the choice necessary?
+
+## Decision
+
+We will <one sentence>.
+
+## Consequences
+
+Positive:
+
+- ...
+
+Negative:
+
+- ...
+
+## Alternatives considered
+
+- **tRPC mutations**: rejected because ...
+- **REST endpoints**: rejected because ...
+
+## Reversal cost
+
+Low, Medium or High, with the concrete migration cost.
+```
+
+## Lifecycle
+
+- `proposed`: open for review and editable.
+- `accepted`: merged and binding for new work.
+- `deprecated`: retained for history but discouraged for new work.
+- `superseded`: replaced by a newer record.
+
+Accepted decision content is immutable. To reverse, clarify or partially replace
+one, create a new ADR whose `supersedes` contains the old `id`. Never delete or
+rename the accepted file. This preserves evidence and prevents parallel branches
+from rewriting the same history.
+
+One mechanical exception keeps references usable without diluting the journal:
+an accepted file may replace a bounded repository-local path when frontmatter,
+headings, Markdown structure and surrounding prose stay byte-for-byte stable and
+the new target exists inside the repository. `void-machine decisions check`
+proves that narrow shape and fails closed on a missing target, path escape or
+symlink escape. A change to wording, reasoning, scope, consequences or identity
+is not a reference migration; it requires supersession. Do not create a new ADR
+merely to record a proven file move or rename.
+
+## Workflow
+
+1. State the decision in one sentence before expanding it.
+2. Record forces and constraints, not a chronology of discussion.
+3. Name at least two credible alternatives and reject them with evidence.
+4. State negative consequences and concrete reversal cost.
+5. Let the accountable decider accept it through normal review.
+6. Run `void-machine decisions check` when available.
+7. Link foundational ADRs from project doctrine by their source file or stable
+   `adr:<uuid>` identity.
+
+Do not commit a rendered Markdown or JSON projection. Generate it on demand with
+`void-machine decisions render`; source files alone participate in merges.
+
+## Composition
+
+- `void-plan`: plans cover work; ADRs cover durable decisions.
+- `void-source-driven-development`: alternatives cite primary documentation.
+- `void-commit-discipline`: a long commit rationale can expose ADR-worthy work.
+- `void-learn`: recurring lessons become doctrine; structural
+  choices become ADRs.

package/core-assets/skills/void-decide/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-devex-audit/.source

@@ -0,0 +1,8 @@
+Sources for `void-devex-audit` skill (see `docs/plans/skill-audits/void-devex-audit.md` for the full distribution matrix):
+
+- gstack /devex-review (1263 LOC, "Live Developer Experience Audit") — VENDORED (DEV-398): the live DX audit methodology. Kept + distilled: the DX first principles (zero-friction T0, error = problem+cause+fix, decide-for-me-let-me-override, show-code-in-context, speed, magical moment), the measured-TTHW benchmark tiers (Champion <2min … Red Flag >10min), the gap-method scoring rubric (score + "what a 10 looks like for THIS surface"), the six evidence-tagged audit passes (getting-started, API/CLI/SDK ergonomics, error-message tracing, docs, upgrade path, dev environment), the TESTED/PARTIAL/INFERRED evidence discipline ("a guess is not a score"), and the plan-vs-reality boomerang concept.
+- REJECTED (gstack runtime, not doctrine): the review-log / review-readiness dashboard, the `gstack-*` bin machinery (gstack-review-log/read, gstack-slug), the boomerang tied to gstack bin files, the external hall-of-fame file dependency, telemetry + learnings-log, the plan-mode plumbing and plan-file review-report writer, gbrain context-load. These are gstack's operational surface, not the DX method.
+- DEFERRED (Vague 4, claude-in-chrome MCP): the live browser driver — screenshotting hosted docs, navigating an API playground, walking a signup/first-key flow, hitting 404/error pages. Same deferral as ui-review. Until then the skill tests the bash/file-accessible surface and marks web-only checks "requires live audit — out of scope".
+- The Seven DX Characteristics table + the ten "cognitive patterns" (chef-for-chefs, first-five-minutes, pit-of-success, progressive disclosure, upgrade fear) — folded into the first-principles list and the pass prose rather than transcribed as separate rosters (anti-bloat; "internalize, don't enumerate", per the source's own instruction).
+
+Strategy: distill + re-home. The plan-time DevEx checklist already lives in plan-review's DevEx lens (DEV-385); this skill is the audit-time ceiling for the SHIPPED surface. Mirrors the floor/ceiling split used for security (security-guidance/security-audit), plans+UI (plan-review Design lens / frontend-design / ui-review), and now DevEx (plan-review DevEx lens / api-and-interface-design / devex-audit). < 30% overlap is structural: plan-requirements in plan-review, contract-design in api-and-interface-design, measured-reality here.

package/core-assets/skills/void-devex-audit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: void-devex-audit
+description: "Audit an EXISTING dev-facing surface (API/CLI/SDK/docs): measured TTHW, real error-path tracing, evidence-backed DX scorecard, scoped refine. The audit ceiling to plan-review's DevEx-lens."
+---
+
+# devex-audit — voidcorp craftsman edition
+
+`void-plan-review`'s DevEx lens judges a *written plan*'s promises before code exists. This skill dogfoods the *shipped* developer-facing surface and measures what a developer actually hits. It is the audit-time ceiling: a deliberate pass over an existing API / CLI / SDK / docs product to measure its real time-to-value, trace its real error paths, score each dimension against evidence, and drive fixes.
+
+Invoke it to critique, score, or improve a deployed dev surface. It proposes findings and scoped edits; it does not design the contract (`void-api-and-interface-design` owns that) and it does not re-teach the plan-time DevEx checklist (`void-plan-review` owns that — this skill assumes it and checks the shipped reality against it).
+
+**Attribution**: see `.source`. Vendored from gstack `/devex-review` (the live DX audit methodology). The gstack runtime (review-log/dashboard, boomerang bin, hall-of-fame file, telemetry, plan-mode plumbing) is rejected. The live browser driver is deferred to Vague 4 (claude-in-chrome MCP).
+
+---
+
+## First principles (every finding traces to one)
+
+1. **Zero friction at T0.** The first five minutes decide adoption. Hello-world without reading docs, without a credit card, without a demo call.
+2. **Every error = problem + cause + fix.** An error that only says what, not why or how to recover, is a finding.
+3. **Decide for me, let me override.** Opinionated defaults are a feature; escape hatches are a requirement. A default with no override is a finding.
+4. **Show code in context.** Hello-world is a lie if it omits real auth, real error handling, real deployment. Solve 100% of the problem, not the toy.
+5. **Speed is a feature.** Iteration speed, response time, lines-to-accomplish, concepts-to-learn — measure them.
+6. **A magical moment.** The one thing that should feel like magic (Stripe's instant response, Vercel's push-to-deploy) should be the *first* thing a developer experiences.
+
+## Scope honesty: what you can test now vs Vague 4
+
+- **Testable now, via bash + files** — CLI `--help` ergonomics, README/getting-started step count, install command, error output on bad input/missing args, `CHANGELOG`/migration/deprecation quality, TS types + LSP inference, CI config, docs-as-code findability, package manifest.
+- **Deferred to Vague 4 (live browser)** — hosted docs search, API playground, signup / first-key flow, 404 and error pages, dashboard. Mark each **"requires live audit — out of scope (Vague 4)"**. Never guess a score for it.
+- **Evidence tag on every score**: `TESTED` (you ran it), `PARTIAL` (ran some, inferred the rest), `INFERRED` (read from files only). A guess is not a score. State the evidence source for each dimension.
+
+## The signature metric: measured TTHW (time to hello-world)
+
+Walk the journey `never-heard-of-it → working example`, counting the real steps and time. Score against the benchmark:
+
+| Tier | Time | Impact |
+|------|------|--------|
+| Champion | < 2 min | 3-4x higher adoption |
+| Competitive | 2-5 min | baseline |
+| Needs Work | 5-10 min | significant drop-off |
+| Red Flag | > 10 min | 50-70% abandon |
+
+TTHW > 10 min is a **blocking** finding.
+
+## The audit passes (each: evidence + score 0-10 + gap-to-10)
+
+These are the same six dimensions `void-plan-review`'s DevEx lens names as *plan requirements*; here each is measured on the shipped surface with an evidence tag, not promised on paper. Keep the two lists aligned if that lens reshapes a dimension.
+
+1. **Getting started** — step-by-step table (`step · time · friction low/med/high · evidence`), ending in the measured TTHW. Count what a first-timer actually does.
+2. **API/CLI/SDK ergonomics** — guessable naming, sensible defaults, escape hatches, progressive disclosure (simple case is production-ready, complex case uses the same surface), coverage vs. dropping to raw HTTP.
+3. **Error messages** — trigger three real error paths (bad input, missing arg, unauthenticated). Each must name the problem, the cause, the fix, and link docs (the Elm/Rust/Stripe three-tier bar).
+4. **Documentation** — findable in < 2 min, code examples copy-paste-complete (not fragments), version-matched to the installed release.
+5. **Upgrade path** — `CHANGELOG` clarity and user-facing framing, migration guides, codemods, deprecation warnings, semver honored, blast radius of a major bump.
+6. **Dev environment** — TS types + LSP autocomplete, non-interactive CI, hot reload, cross-platform, test utilities/fixtures.
+
+## Scoring: the gap method
+
+For each dimension, score 0-10 **and** write what a 10 looks like for *this* surface, then fix toward it. Rubric anchors: `9-10` best-in-class (Stripe/Vercel tier) · `7-8` usable, minor gaps · `5-6` works with friction · `3-4` developers complain · `1-2` abandoned after first try · `0` not addressed.
+
+## Evidence-backed scorecard
+
+```
+DX AUDIT — <surface>
+Dimension          Score  Method     Evidence
+Getting started    _/10   TESTED     <step count / cmd>
+API/CLI/SDK        _/10   PARTIAL    <--help output / naming>
+Error messages     _/10   PARTIAL    <3 traced paths>
+Documentation      _/10   INFERRED   <file refs>  (live search: Vague 4)
+Upgrade path       _/10   INFERRED   <CHANGELOG / migration>
+Dev environment    _/10   INFERRED   <types / CI>
+TTHW (measured)    _ min  TESTED     <journey>
+Overall            _/10
+```
+
+## Plan-vs-reality (optional)
+
+If a prior `void-plan-review` DevEx scorecard exists for this surface, compare its per-dimension plan score against the live score; flag any dimension where **live < plan − 2** (the plan over-promised). Re-homed from the gstack boomerang — the comparison concept is kept, its `gstack-*` bin machinery is not.
+
+## Refine modes
+
+Once findings exist, drive a scoped, finding-driven fix (not a rewrite):
+
+- `quickstart` — cut TTHW (fewer steps, working default, try-before-install).
+- `errors` — rewrite the traced error paths to problem + cause + fix + docs link.
+- `docs` — findability, copy-paste-completeness, version match.
+- `upgrade` — changelog framing, migration guide, codemods, deprecation warnings.
+- `types` — LSP autocomplete, inference, exported types at the boundary.
+
+## Composition & boundaries
+
+- **Not `void-plan-review`'s DevEx lens** — that judges a *written plan* before code (does the plan name a TTHW target, the error paths, the upgrade story?); this audits the *shipped* surface with measured evidence. Different artifact, different lifecycle stage. The < 30% overlap is structural: plan-requirements there, measured-reality here.
+- **Not `void-ui-review`** — that audits the *visual / interaction* UI (hierarchy, slop, states); this audits the *developer journey* (naming, errors, docs, upgrade). Different subject.
+- **With `void-api-and-interface-design`** — its build-time floor (designing a minimal, stable contract) is what this skill audits after the fact. Build there, judge here.
+- **Live browser audit** — deferred to Vague 4 (claude-in-chrome); until then test via bash/files and mark web-only checks as deferred.
+- **Supersedes** gstack `/devex-review` (methodology now harness-native).
+
+## Anti-rules
+
+- MUST NOT score a dimension without an evidence tag (`TESTED`/`PARTIAL`/`INFERRED`) — a guess is not a score.
+- MUST NOT re-judge a written plan — that is `void-plan-review`'s DevEx lens.
+- MUST NOT redesign the API/CLI/SDK contract — `void-api-and-interface-design` owns it; this proposes fixes, it does not re-architect the surface.
+- MUST NOT drive a browser or make live web requests — defer to Vague 4; test via bash/files and mark web-only checks out of scope.
+- MUST NOT trigger error paths against a production tenant or shared data — use a throwaway/local surface for the error pass.
+- MUST NOT vendor the gstack runtime (review-log, dashboard, boomerang bin, telemetry, hall-of-fame file).
+
+## Final rule
+
+```
+Existing dev surface → scope (testable now vs deferred) → measured TTHW → 6 audit passes with evidence →
+gap-method scorecard → scoped refine.
+Otherwise → it is not voidcorp devex-audit.
+```
+
+Anyone can ship an API. This skill is what tells you, with evidence, whether a developer can actually fall into the pit of success on it.

package/core-assets/skills/void-devex-audit/harness.yaml

@@ -0,0 +1,15 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+activation: on-demand
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-doctor/.source

@@ -0,0 +1,15 @@
+Sources for `void-doctor` (see `docs/plans/skill-audits/void-doctor.md` for the full audit).
+
+Original to void-machine. It wraps this repository's own CLI, so there is no upstream skill to
+distil: the subject did not exist anywhere else.
+
+Provenance rather than inspiration: it was a slash command under `packages/core/commands/`,
+shipped there on 2026-06-04 because the plugin carried no in-session ergonomics at the time and a
+skill was not invocable from the keyboard. Claude Code has since merged commands into skills, and
+neither Codex nor Kimi ever had the command format, so the command was Claude-only for a reason
+that had expired. Converted on 2026-08-19, keeping its name and its `allowed-tools`, gaining
+`disable-model-invocation: true` — the gesture is typed by a human, never guessed by the model.
+
+Rejected while converting: letting the model invoke it on its own. A health check, an audit or a
+graph report that fires unprompted arrives when nobody asked and nobody acts on it, and it spends
+a screen doing so.

package/core-assets/skills/void-doctor/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: void-doctor
+description: Run the harness health checks and report what is healthy, missing or stale, with the exact command that repairs each finding. Reports; never repairs on its own.
+allowed-tools: Bash(void-machine:*) Bash(npx:*)
+---
+
+# void-doctor
+
+Answer one question: is this project's harness actually wired, or does it only look wired.
+
+**Attribution**: see `.source`.
+
+---
+
+## When it fires
+
+Only when a human asks. `disable-model-invocation: true` is deliberate: a health check that
+fires on its own turns a session into a diagnostic, and its findings arrive when nobody asked
+for them and nobody acts on them.
+
+The moments worth running it: after an install or an update, when a rule that should have
+blocked something did not, when a skill you expected did not load, and when a session opens on a
+project you have not touched in a while.
+
+---
+
+## Run it
+
+```
+void-machine doctor
+```
+
+The CLI is public on npm as `voidmachine`, whose binary is `void-machine` (alias `vm`;
+the former command still works, with a deprecation notice). If it is not on PATH,
+`npx voidmachine doctor` is the same thing without an install.
+
+In the void-machine repository itself, `doctor` delegates to the self-host doctor, which asks a
+different question: do the current sources still compile into a working harness. Both are valid;
+say which one ran, because "healthy" means different things.
+
+---
+
+## Read it
+
+Give a one-screen summary, in this order:
+
+1. **What is broken**, and for each one the exact command that fixes it. A finding without its
+   repair command is a finding the reader has to research, which is how a doctor report becomes
+   something nobody runs twice.
+2. **What is stale** rather than broken: an artefact older than its sources, a version behind, a
+   marketplace unreachable. Stale degrades; it does not fail.
+3. **What is healthy**, in one line. Not a list.
+
+Do not paste the raw output back. It is written to be read by a human at a terminal, and
+repeating it costs the whole screen for no added meaning.
+
+---
+
+## What it must not do
+
+**Never repair automatically.** The report names the command; the human runs it. A check that
+silently rewrites a project's configuration removes the one moment where someone could have said
+"no, that file is mine".
+
+The exception is explicit and stays explicit: when a repair flag exists, it runs only because a
+human typed it, never as a follow-up this skill decides on.
+
+---
+
+## Red flags
+
+| Rationalization | Reality |
+|---|---|
+| "It reported stale, I'll just re-run init to clean it up" | init rewrites managed files. Report it and let the human choose. |
+| "The output is long, I'll paste it and let them read" | Then the skill added nothing. Summarise, or say it was already clear. |
+| "Everything is green, nothing to say" | Say it in one line, including which target ran: the repo doctor and the consumer doctor answer different questions. |
+
+---
+
+## Composition
+
+Adjacent: `void-verify` proves one unit of work; this proves the harness that guards every unit.
+Downstream: a finding about a missing doctrine rule is routed to `void-learn`, never fixed here.

package/core-assets/skills/void-doctor/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-domain-driven-design/.source

@@ -0,0 +1,13 @@
+Sources for `void-domain-driven-design` skill (see `docs/plans/skill-audits/void-domain-driven-design.md` for full audit):
+
+- Eric Evans "Domain-Driven Design: Tackling Complexity in the Heart of Software" 2003 — book — foundation, strategic DDD vocabulary
+- Vaughn Vernon "Implementing Domain-Driven Design" 2013 — book — tactical patterns, "small aggregates" rule
+- Scott Wlaschin "Domain Modeling Made Functional" — https://pragprog.com/titles/swdddf — DDD + FP synthesis, make illegal states unrepresentable
+- Khalil Stemmler practical DDD in TypeScript — https://khalilstemmler.com/articles/categories/domain-driven-design/ — TS-flavored tactical examples
+- Vlad Khorikov "Domain Modeling" course/blog — https://enterprisecraftsmanship.com — always-valid domain model, Result over exceptions
+- Vaughn Vernon "Domain-Driven Design Distilled" 2016 — book — shorter intro
+- citypaul/.dotfiles DDD notes — ubiquitous language enforcement
+
+Strategy: distill. Reject CQRS, event sourcing, mediator, generic Repository<T> as defaults (per docs/PHILOSOPHY.md Wing Chun). Sub-domain analysis (Core/Supporting/Generic) delegated upstream to brainstorm / plan-review (CEO lens).
+
+Companion hook: ubiquitous-language-lint (advisory).