From 3a20eb60c3a83d8db9b3da15ec3d0fdd053510ed Mon Sep 17 00:00:00 2001 From: Ryan Dombrowski Date: Wed, 29 Jul 2026 00:01:09 -0500 Subject: [PATCH] The quickstart never ran this package, and one claim went stale Two documentation corrections, both found while running the commands rather than reading them. THE QUICKSTART DID NOT USE THIS REPOSITORY. "Try it in five minutes" installed ds-mcp and never mentioned dspack-validate, the binary this package ships. A reader arriving at the specification repository was sent to a different one before seeing anything this one does. The harness now runs first: one command, no install, and it compiles every schema and validates the bundled examples, so you can see the spec is self-consistent before you commit to anything. Stated carefully, because the obvious phrasing would be wrong: dspack-validate does NOT accept a file argument. It checks this package's own schemas and examples. Describing it as "point it at your contract" would have been a plausible sentence that fails the moment anyone tries it. The agent step keeps its curl, which it needs, and is now clearly the second step rather than the first. A STALE VERSION CLAIM. The Implementations section said dspack-export "generates a dspack v0.2 file". It has declared v0.4 snapshots since 0.3.0, and this repository's own spec section describes v0.4 as current two paragraphs earlier. It now says "spec-current", which stops the sentence needing an edit at every spec revision. Co-Authored-By: Claude Fable 5 --- README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6776028..e6fbb7d 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,19 @@ https://github.com/user-attachments/assets/510a781b-4214-49b3-b997-9cbecdc36961 ## Try it in five minutes -The fastest way to feel what a contract changes is to put one in front of an agent: +Start with the specification's own harness. It compiles every schema and +validates the bundled examples, so one command shows you the spec is +self-consistent and what a clean result reads like: + +```bash +npx -y -p @aestheticfunction/dspack-spec dspack-validate +``` + +Then put a real contract in front of an agent: ```bash -npm install -g @aestheticfunction/ds-mcp curl -L https://raw.githubusercontent.com/aestheticfunction/dspack/main/examples/shadcn-ui.dspack.json -o shadcn-ui.dspack.json +npm install -g @aestheticfunction/ds-mcp ds-mcp --dspack ./shadcn-ui.dspack.json ``` @@ -94,7 +102,7 @@ The spec evolves against evidence, not speculation. Every milestone runs 216-run ### Producing dspack files -[dspack-export](https://github.com/aestheticfunction/dspack-export) (experimental) generates a dspack v0.2 file from a React + Tailwind/shadcn or Vue 3 + Vuetify 3 codebase: components and props (including cva variant enums and their defaults, and Vue `defineProps`/emits/slots), semantic color and radius tokens from CSS custom properties or an imported DTCG design-token file, dark-theme overrides, layout breakpoints, and framework import bindings. It is a snapshot generator. Hand-authored sections such as `patterns`, `antiPatterns`, `whenToUse`, `accessibility`, and `constraints` remain yours to write; an exporter can extract facts, but the institutional knowledge that makes a dspack file valuable to agents comes from your team. +[dspack-export](https://github.com/aestheticfunction/dspack-export) (experimental) generates a spec-current dspack file from a React + Tailwind/shadcn or Vue 3 + Vuetify 3 codebase: components and props (including cva variant enums and their defaults, and Vue `defineProps`/emits/slots), semantic color and radius tokens from CSS custom properties or an imported DTCG design-token file, dark-theme overrides, layout breakpoints, and framework import bindings. It is a snapshot generator. Hand-authored sections such as `patterns`, `antiPatterns`, `whenToUse`, `accessibility`, and `constraints` remain yours to write; an exporter can extract facts, but the institutional knowledge that makes a dspack file valuable to agents comes from your team. dspack files can also simply be written by hand — the [shadcn/ui example](examples/shadcn-ui.dspack.json) in this repository was authored that way. A valid document needs only `dspack` and `name`.