jig-ui 0.8.2 → 0.10.0

package/templates/SKILL.md.tmpl

@@ -3,25 +3,51 @@ cite the number when you follow or deliberately break one.
 
 ## Before generating or reviewing any UI
 
-0. Check that `{{config_file}}` exists. If it does not, this project has no
-   token layer: run `init` and stop until it has been run. Do not proceed by
-   writing token definitions of your own — a `:root` block you author, however
-   clearly you label it, is an invented design system wearing this one's names,
-   and it will not be replaced when the real tokens arrive.
+0. **Two preconditions. Check both, and stop on either.**
+
+   a. `{{config_file}}` exists. If it does not, this project has no token layer:
+      run `init` and stop until it has been run. Do not proceed by writing token
+      definitions of your own — a `:root` block you author, however clearly you
+      label it, is an invented design system wearing this one's names, and it
+      will not be replaced when the real tokens arrive.
+
+   b. `DECISIONS.md` exists beside the token files — `jig/DECISIONS.md` by
+      default, or wherever `brand` in `{{config_file}}` puts them — and has
+      substance: not empty, no `[TODO]` markers left in it, more than a few
+      lines. If it does not, run `{{command_prefix}}decide` and stop until it has
+      been written. Do not write it yourself from this task's prompt — it records
+      decisions the project has made, and a file you author alone records
+      decisions *you* have made, which is the opposite thing wearing the same
+      name.
 1. Load `{{rules_path}}/00-anti-patterns.md` and `{{rules_path}}/01-modes.md`.
 2. Determine the mode from `{{config_file}}`, or infer it using the procedure in
    `{{rules_path}}/01-modes.md` and state the inference in one line before building.
-3. Load the relevant section of `{{rules_path}}/03-patterns.md` for the component you are building.
-4. Load `{{rules_path}}/05-copy.md` whenever you write a label, button, heading, error or empty state.
-5. Consume tokens by semantic name only. Never write a raw colour or pixel value
+3. **Building a page, feature or functionality?** Run it through
+   `{{command_prefix}}spec` → `{{command_prefix}}mockup` (low fidelity) →
+   `{{command_prefix}}make` (high fidelity) → `{{command_prefix}}critique`, one at a
+   time. Never design the whole product up front. Critique findings go back to
+   `make`, then `critique` again, until clean or accepted by the user — then the
+   next feature.
+   **Building a screen rather than a single component?** Read `L-01 · Layout
+   method` in `{{rules_path}}/03-patterns.md` and run its five steps before
+   writing any markup. It is a procedure, not a component, so step 4 never
+   selects it and nothing else will. (`explain L-01` prints it too, but the
+   file is the source — do not skip the step if the command is unavailable.)
+4. Load the relevant section of `{{rules_path}}/03-patterns.md` for the component you are building.
+5. Load `{{rules_path}}/05-copy.md` whenever you write a label, button, heading, error or empty state.
+6. Consume tokens by semantic name only. Never write a raw colour or pixel value
    at a call site, and never resolve a name yourself: if a token you need has no
    value, that is a finding to report, not a number to supply.
-6. Run `check` for the rules the CLI can detect, then run the self-check at the
+7. Run `check` for the rules the CLI can detect, then run the self-check `L-04` at the
    end of `{{rules_path}}/00-anti-patterns.md` for the rules it cannot. Both
    halves, every time — a clean `check` is not a clean review.
-7. Cite any rule you deliberately break, with the reason, in one line.
+8. Cite any rule you deliberately break, with the reason, in one line.
 
-Load `{{rules_path}}/04-principles.md` only when two rules conflict.
+When two rules conflict, fetch the tiebreaker rather than the file:
+`explain R-06`…`R-12` resolve one conflict each. When no rule covers the
+situation at all, the five frames `R-01`…`R-05` are the method for recognising
+what kind of failure it is. `{{rules_path}}/04-principles.md` holds them all if
+you would rather read the whole thing.
 
 ## If the project uses Tailwind v4
 
@@ -78,12 +104,25 @@ changed since, do not re-run it.
 Before you finish a task that generated or modified UI, emit this line:
 
 ```text
-JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> judgment=<ran|skipped> files=<n> styled=<n>
+JIG_CHECK: version=<version> mode=<mode> mechanical=<pass|fail|skipped>:<n> warnings=<n> judgment=<ran|skipped>:<n> files=<n> styled=<n>
 ```
 
+`warnings=` counts the findings `check` reported as warnings. `mechanical=pass`
+means no errors, and nothing more: a page that is not usable on a phone can
+carry `pass:0` with several warnings, because the mobile detectors warn rather
+than fail CI. A record that says `pass` with warnings above zero is not a clean
+page — say what the warnings were.
+
 `jig check` emits this same line for the half it can do, with
 `judgment=not-run`. Take `mechanical=` from its output rather than counting by
-hand; fill `judgment=` yourself. If `check` could not run at all, that is
+hand; fill `judgment=` yourself.
+
+**The line you emit is your own, not a copy of the CLI's.** `judgment=not-run` is
+the CLI truthfully describing itself — it cannot judge. If you did the judgment
+work, your line says `ran:` with the number of rules you gave a verdict. A live run
+copied the CLI's line verbatim after doing the work, and dropped `files=` and
+`styled=` as well, so its record claimed less than it had done and could not be
+compared with any other. If `check` could not run at all, that is
 `mechanical=skipped:0` — never `pass`, which would report a clean result for a
 check that never inspected anything.
 

package/templates/command-metadata.json

@@ -1,7 +1,7 @@
 {
   "install": {
     "description": "Install Jig rules and the agent skill file into a repository.",
-    "argumentHint": "--agent <name> [--scope project|global]",
+    "argumentHint": "--agent <name> [--scope project|global] [--hook]",
     "status": "available"
   },
   "update": {
@@ -14,14 +14,54 @@
     "argumentHint": "[--yes]",
     "status": "available"
   },
+  "decide": {
+    "description": "Write the project-wide design decisions to DECISIONS.md beside the token layer — the choices that need a reason, which the tokens hold the values for but cannot explain. Runs once per project, by interviewing you. spec, mockup, make and critique need it; nothing else does. No CLI — the agent does this.",
+    "argumentHint": "",
+    "status": "agent"
+  },
   "check": {
     "description": "Check the repo against the mechanical and hybrid rules the CLI can detect. Reports findings by rule id; the judgment rules remain yours to apply.",
     "argumentHint": "[--all] [--ci] [--json]",
     "status": "available"
   },
+  "verdicts": {
+    "description": "Verify a critique's verdict files: every rule in each pass judged once, no id that does not exist, no rule in the wrong arm, rendered only with a screenshot. Computes the counts the critique reports, so the agent never writes them.",
+    "argumentHint": "<surface>",
+    "status": "available"
+  },
+  "probe": {
+    "description": "Print the render probe: a script the critique runs in a browser at 360, 768 and 1280px. It opens the phone menu, presses Escape, measures sideways scroll and whether styles and tokens applied; `verdicts` refuses verdicts it contradicts.",
+    "argumentHint": "",
+    "status": "available"
+  },
+  "gate": {
+    "description": "Run by the Claude Code Stop hook that `install` adds: blocks finishing while `check` fails on changed files or a critique's verdict files fail. Not run by hand.",
+    "argumentHint": "",
+    "status": "available"
+  },
   "explain": {
-    "description": "Explain a rule, or find the rules you cannot name. Given an id, prints the rule's full text, its correction, the version it arrived in and who checks it — including the P-/M- pattern and mode specs, which no rule index contains. Given a word instead, searches every title and body and lists what matches. `--list` prints every id, or one section's.",
-    "argumentHint": "<rule-id | search term> [--list]",
+    "description": "Explain a rule, or find the rules you cannot name. Given an id, prints the rule's full text, its correction, the version it arrived in and who checks it — including the P-/M- pattern and mode specs, which no rule index contains. Given a word instead, searches every title and body and lists what matches. `--list` prints every id, or one section's. `--layer` names the six layers — principles, anti-patterns, tokens, components, layout, patterns — and lists one by name, which is how to find a rule when you know what you are trying to do but not its number.",
+    "argumentHint": "<rule-id | search term | layer name> [--list] [--layer]",
     "status": "available"
+  },
+  "spec": {
+    "description": "Say exactly what is being built — a page, feature or functionality — scoped to its smallest useful version and specified at every screen size, then confirmed. Writes .jig/specs/<surface>.spec.md. No CLI — the agent does this.",
+    "argumentHint": "<page, feature or functionality, in your own words>",
+    "status": "agent"
+  },
+  "mockup": {
+    "description": "Low-fidelity design: a grayscale drawing of the confirmed spec at every screen size, reviewed before any code. Asks whether to draw it in HTML, Figma or Google Stitch, and tells you to connect that tool's MCP server if needed. No CLI — the agent does this.",
+    "argumentHint": "<page, feature or functionality, in your own words>",
+    "status": "agent"
+  },
+  "make": {
+    "description": "High-fidelity: build the actual page or feature from its confirmed spec and approved mockup — matching the mockup's structure, never copying its markup — recording any deviation back into the spec. No CLI — the agent does this.",
+    "argumentHint": "<page, feature or functionality, in your own words>",
+    "status": "agent"
+  },
+  "critique": {
+    "description": "Scrutinise what was built against the rules, its spec and its mockup: render it, judge what check cannot, and report by rule id. Needs DECISIONS.md. No CLI — the agent does this.",
+    "argumentHint": "<page, feature or functionality, in your own words>",
+    "status": "agent"
   }
 }