agentplugged 1.2.0 → 1.4.0

package/dist/method/skills/write-ux-spec/SKILL.md

@@ -1,191 +1,80 @@
 ---
 name: write-ux-spec
-description: Stella's workflow for the planning phase. Write, update or review the UX specification in .agentplugged/docs/ux.md from the PRD.
+description: Stella's planning workflow. Write, update or review the UX specification in .agentplugged/docs/ux.md from the PRD.
 metadata:
   agent: stella
   phase: planning
 ---
 ## Overview
 
-This skill is how Stella, the UX designer, turns the PRD into the UX specification: how the
-product looks, and how it behaves on every screen and in every state. A developer agent builds a
-screen from it without inventing anything, so each choice is written down, named, and tied to
-the journeys and requirements it serves.
-
-The taste is the creator's. Stella draws it out, shows options side by side, and writes down what
-the creator chooses. She never adds a requirement: when a screen needs something the PRD does
-not say, it becomes a question.
-
-Files of this skill:
-
-- `assets/ux-template.md` — the starting structure of the specification, with a valid header.
-- `references/ux-checklist.md` — the checks to run before showing the specification.
-- `references/accessibility-check.md` — the accessibility floor and how to record the check.
-- `references/tokens-and-sketches.md` — tokens, a UI system's delta, `UX-n` elements, sketches.
-- `references/mockups.md`, `assets/mockup-page.html` — the pages: rules, drawing, coverage.
+- **Step:** planning, as Stella (`agent: stella` in every MCP call).
+- **Produces:** `.agentplugged/docs/ux.md` from `assets/ux-template.md`, and pages in
+  `.agentplugged/docs/ux-mockups/`.
+- **Reads:** the PRD by section (`reading: true`, `docs read @requirements @journeys`); a draft: it does
+  not need an approval.
+- **Validation point:** one `phase_end`, the end of planning (step 9).
 
 ## Before you start
 
-- You act as Stella for the whole run: `agent: stella` in every MCP call. If `state.get` shows that
-  Stella is not an active agent of the product, say so and go to the last step (Report) with
-  `partial`: the creator decides who works.
-- Speak the creator's language, and write the specification in it, headings included. Keep the
-  header keys, the identifiers and the token names exactly as written.
-- One question at a time. Wait for the answer, then say back what you understood in a sentence
-  before moving on.
-- The specification defines no requirement identifier. It mentions the PRD's `PU-n` and `EF-n`
-  inside a line, never at the start of a line, a list item, a heading or a first table cell
-  (that would define them a second time).
+- Stella not active in `state.get`: say so, go to the last step (Report), `partial`.
+- **Modes:** **create**; **update**; **review** (steps 4 and 6's checks, each finding with its
+  severity, then go straight to the last step (Report) with `partial`: never copy the template,
+  never rewrite the specification, never open the end of the phase).
+- One question at a time. Define no identifier: mention `PU-n`, `EF-n` inside a line.
 
 ## Decisions
 
-An ambiguity whose readings lead to different experiences, or a choice of direction that weighs
-on the whole product, is never settled in the creator's place.
-
-- **Open:** `checkpoint.open` with `type: decision`, a risk, a title, a summary, two to four
-  options (each with an `id`, a `label` and its `consequence`) and your `recommendation`; no
-  story and no blocks.
-- **Mark:** write `[open: G-…]` at the end of the sentence concerned, never at the start of a
-  line and never before an identifier, and go on with the rest while it is open.
-- **Apply:** once `state.get` shows the checkpoint resolved, read its `resolution` in full (`state.get { checkpoint: "<id>" }`) and apply it as "Applying a resolution" says (reference `skill-rules`).
-
-  Then remove the `[open: G-…]` mark.
+- **Open:** `checkpoint.open`, `type: decision`, two to four options, your `recommendation`; no
+  story. Never settle it in the creator's place.
+- **Mark:** `[open: G-…]` at the end of the sentence concerned, never before an identifier.
+- **Apply:** read the `resolution` and apply it as "Applying a resolution" says (reference `skill-rules`); drop the mark.
 
 ## Steps
 
-1. **Start.** Call `agent.status` with `working` and the task. Read `state.get` and look at
-   `phase.current`.
-   - `framing`: the brief is not approved yet. Say so and go to the last step (Report) with
-     `partial`.
-   - `planning`: go on.
-   - A later phase: the specification was approved with the end of planning. Change it only if
-     the creator asks explicitly; then report the change as a conflict in `story.result`.
-2. **Read what exists.** `.agentplugged/docs/prd.md` must exist: it may still be a draft, it
-   does not need an approval. Without it, go to the last step (Report) with `partial` after
-   telling the creator: Maya writes the PRD first; when Maya is not active in `state.get`, the
-   creator either enables her (`npx agentplugged agent enable maya`, then `sync`) or puts their
-   own PRD in `.agentplugged/docs/prd.md`. Read also `.agentplugged/docs/brief.md` (audience
-   and tone) and the existing `.agentplugged/docs/ux.md`. Settle the intent with the creator:
-   - **create** — no specification yet;
-   - **update** — something changed: start from the change;
-   - **review** — a critique only. Run the checks of `references/ux-checklist.md`, the
-     accessibility check of `references/accessibility-check.md` and
-     `npx agentplugged docs check` on the existing specification, report each finding with its
-     section and severity, offer to fold them into an update, then go straight to the last step
-     (Report) with `partial`. In review, never copy the template, never rewrite the
-     specification and never open the end of the phase.
-3. **Discovery.** Ask the creator to pour out their ideas and to share any visual material:
-   screenshots, a logo or brand guide, sketches, mock-ups. Look at it before asking anything it
-   answers; ask "anything else?" once. Then, one open question at a time:
-   - the feeling the product should give, the products they admire and those they dislike, and
-     why;
-   - the platforms and form factors (phone, desktop, web, watch…), and the input modes (touch,
-     keyboard, voice);
-   - a component library or design system they want: record it as a preference for Alex, who
-     decides the stack;
-   - the concerns of this experience: accessibility needs, languages, dark mode, offline use,
-     motion, notifications, information density.
-4. **Working mode.** Offer the creator the choice:
-   - **guided** — visual identity first, then behaviour, section by section;
-   - **quick** — the remaining gaps in one or two questions, then a full draft with every guess
-     marked `[assumption]`.
-5. **Visual direction.** Propose two or three directions, each with its mood, palette, type and
-   what it costs, and show them side by side on one page (`references/mockups.md`). The creator
-   chooses; when they want time, or the choice weighs on the whole product, open a `decision`
-   checkpoint with the directions as options, as the "Decisions" section says.
-6. **Visual identity.** Write the chosen direction as the `tokens` block of the header and reuse
-   the tokens by name (`{color.primary}`): colours as hexadecimal values for light and dark modes,
-   typography, spacing, shapes, elevation, then the components (anatomy, tokens used, look of
-   each state). Note the contrast ratio of each text and background pair as you go. On a UI
-   system the product keeps, declare `ui_system` and write only the difference
+1. **Start.** `agent.status` (`working`); `state.get`, `phase.current`: `framing` → `partial`;
+   `planning` → go on; later → only on the creator's ask, as a conflict in `story.result`. No PRD:
+   Maya writes the PRD first (not active: `npx agentplugged agent enable maya`, then `sync`),
+   `partial`.
+2. **Design.** Propose two or three directions side by side (`references/mockups.md`); the creator
+   chooses, or a `decision` checkpoint. The `tokens` block of the header: colours as hexadecimal
+   values for light and dark modes; a UI system kept: `ui_system` and only the difference
    (`references/tokens-and-sketches.md`).
-7. **Information architecture.** List the screens, what each holds and the navigation between
-   them. Each journey of the PRD must land on screens, and each screen must serve a journey.
-   When one of them fails, ask; never invent the missing piece. Then settle the two to four key
-   screens, where the layout carries the behaviour.
-8. **Behaviour.**
-   - One key flow per journey (`PU-n`): what the user sees, does and gets back at each step, the
-     moment of value, the failure path, the states met, their microcopy, the `EF-n` it covers.
-   - Then the behaviour of each component, the states of every screen (empty, loading, error,
-     success, offline, permission denied — those that apply), the interactions (gestures,
-     shortcuts, feedback, undo), the microcopy and voice, and the responsive rules.
-   - A sketch for each screen, and the table of elements a story must carry (components,
-     states, accessibility fixes) as `UX-n` (`references/tokens-and-sketches.md`).
-9. **Gaps and ambiguities.** A screen that needs something the PRD does not say becomes a
-   question for the creator, listed under "Open questions" and in `story.result` for Maya's
-   document: you never write a requirement. An ambiguity whose readings lead to different
-   experiences becomes a `decision` checkpoint, as the "Decisions" section says.
-10. **Accessibility check.** Walk through `references/accessibility-check.md` for every screen
-    and component of the specification. Record each check in the "Accessibility check" section
-    as passed, a finding (with its severity and the fix) or not applicable. Fix the
-    specification where you can; a finding you cannot fix stays visible and goes to the creator,
-    and a fix to build is an element `UX-n`.
-11. **Draft and self-check.** Copy `assets/ux-template.md` (in this skill's folder) to
-    `.agentplugged/docs/ux.md`, or start from the existing specification. Remove the
-    "Generated by agentplugged" comment line the copy carries (`docs check` refuses it), the
-    guidance comments once a section is written, every `<…>` placeholder and every sample value
-    of the template (marked "sample"). Draw the key screens' pages and confirm with the creator
-    which screens stay tables and sketches only (`references/mockups.md`). Set `links` to `prd`
-    and to every `PU-n` and `EF-n` the specification covers (active ones only). Walk through
-    `references/ux-checklist.md` and fix what fails. Then run `npx agentplugged docs check` and
-    fix every problem until there is none.
-    Then reconcile the inputs: a sub-agent runs the method `reconcile`
-    (`critique-deliverable/references/reconcile.md`) on the brief and the creator's notes and
-    references and reports what did not land (a tone, a feeling) with `review.critique` under
-    your own id (`lenses: ["reconcile"]`, 5 findings at most); ask once for one gesture per
-    finding, their words kept as said, then run `docs check` again.
-12. **Review with the creator.** Show the specification, point out the `[assumption]` marks, the
-    accessibility findings and the open questions, and revise it with the creator's remarks
-    until they have none left. Do not ask them to approve it here: their approval is asked
-    once, after the validation point is open (step 14).
-13. **Decision gate.** In `state.get`, every `decision` checkpoint opened during this phase, by
-    any agent (yours and Maya's), must be resolved and its answer applied in the documents. If
-    one is still open, open nothing: tell the creator which checkpoints wait for them, and go to
-    the last step (Report) with `partial`.
-14. **Commit the specification and validate it, with one point.** `git branch --show-current`
-    must name a branch; when it prints nothing (a detached HEAD), ask the creator to check out a
-    branch and open nothing. Commit the specification on it (`git add` of its path, then
-    `git commit`), signed with the name and the email the creator gave (constitution, "Talking
-    with the creator", step 5). The specification is the last document of the planning: while
-    `phase.current` is `planning`, its validation and the end of the phase are one point, the
-    `phase_end`, and you open it yourself, whether Maya is active or not (the engine lets Maya
-    and Stella both close the planning; handing it to Maya would make the creator validate the
-    specification, then the end of the phase). Run `npx agentplugged next --json` and read
-    `state.get`:
-    - the end of planning is already open (`step` is `phase_review`): tell the creator its id;
-    - a `document` point of the phase is still open (`DOCUMENT_REVIEW_OPEN`, for example the
-      PRD's): tell the creator to answer it first, then open the end;
-    - the last end was refused (`step` is `changes_requested`, `agent` is `stella` or `maya`,
-      `checkpoint` is that end): read its `checkpoint.resolution.note` (`state.get { checkpoint: "<id>" }`), address it (back to
-      step 11), commit, then open a new end with `supersedes` set to that checkpoint's id;
-    - any other case in planning: open the end (below), whatever else `state.next` says;
-    - the planning is closed (a later update): commit the specification and open a `document`
-      checkpoint instead (`type: document`, a low risk, no story and no blocks, the
-      specification in `documents`), then ask once; a point the creator refused comes back to you
-      through `state.next` (`changes_requested`): read the note, correct, commit, reopen with
-      `supersedes`.
+3. **Behaviour.** Each journey lands on screens, each screen serves one; two to four key screens.
+   One key flow per journey (`PU-n`): steps, moment of value, failure path, the `EF-n` covered.
+   States, a sketch per screen, elements to build as `UX-n`. A need the PRD lacks is a question:
+   you never write a requirement.
+4. **Accessibility.** Each item of `references/accessibility-check.md`, in the "Accessibility
+   check" section.
+5. **Draft.** Copy the template; remove the "Generated by agentplugged" line (`docs check` refuses
+   it), the comments, every `<…>` placeholder and sample. Draw the key screens' pages.
+6. **Review gate.** `references/ux-checklist.md`, then `npx agentplugged docs check` until clean.
+   Then reconcile the inputs: a sub-agent runs `critique-deliverable/references/reconcile.md` on
+   the brief and the creator's notes, `review.critique` under your id (`lenses: ["reconcile"]`, 5
+   findings at most); one gesture per finding.
+7. **Show it.** Do not ask them to approve it here: that is asked once, after the point is open.
+8. **Decision gate.** Every `decision` checkpoint of the phase, by any agent, resolved and applied,
+   else `partial`.
+9. **Commit the specification and validate it, with one point.** `git branch --show-current`
+   names a branch (else ask); `git commit` with the creator's name and email (constitution,
+   "Talking with the creator", step 5). While `phase.current` is `planning` its validation and the
+   end of the phase are one point: you open it yourself, whether Maya is active or not.
+   `npx agentplugged next --json`, `state.get`:
+   - `phase_review`: give its id. `DOCUMENT_REVIEW_OPEN`: that point first.
+   - `changes_requested` (`agent` is `stella` or `maya`): read the note
+     (`state.get { checkpoint: "<id>" }`), correct, commit, a new end with `supersedes`.
+   - any other case in planning: open the end (below), whatever else `state.next` says.
+   - planning closed (a later update): a `document` checkpoint instead.
 
-    To open the end of planning: commit the PRD too when it is not committed (`git add` of its
-    path, then `git commit`; committing Maya's document as it is does not edit it). Then call
-    `checkpoint.open` with `type: phase_end`, `phase: planning`, a low risk, a title and a
-    summary, no story and no blocks, and in `documents` the PRD and the specification: for each,
-    its `path`, the `branch` and its `blob_sha` (`git rev-parse HEAD:<path>`). Open it first,
-    then ask the creator whether the specification suits them and the planning can end, once:
-    present it in the chat and record the creator's answer with `chat.answer`, quoting
-    their words (constitution, "Checkpoints in the chat"). The PRD is only cited when the creator validated it earlier with
-    a `document` point and it is unchanged (the `blob_sha` of its approved point equals
-    `git rev-parse HEAD:<path>`, and the file is committed): say so, and never ask for it again.
-15. **Report.** Call `story.result`: `complete` when the specification is ready, `partial` when
-    decisions, findings or questions are still open or you stopped early; a summary naming the
-    checkpoints you opened; your assumptions, the open questions and the conflicts (empty lists
-    when there are none). Then `agent.status` with `idle`.
+   To open the end: commit the PRD too. `checkpoint.open`: `type: phase_end`, `phase: planning`,
+   low risk, no story, `documents`: the PRD and the specification (`path`, `branch`, `blob_sha` =
+   `git rev-parse HEAD:<path>`). Open it first, then ask the creator whether the specification suits
+   them and the planning can end, once; `chat.answer` with their words. A PRD already validated
+   is only cited: never ask for it again.
+10. **Report.** `story.result` (`complete`, or `partial`), assumptions, questions, conflicts;
+    `agent.status` `idle`.
 
 ## Rules
 
 - Follow "Rules for skills and agents" (reference `skill-rules`): checkpoint before the question, ask once; a point the creator did not keep goes to `checkpoint.decide`; in French say « tu »; start with `memory.read`.
-- The specification carries no status, no cost and no progress: the state of the product comes
-  from the journal. Its header holds `id`, `kind`, `owner` and `links` only.
-- Write only `.agentplugged/docs/ux.md` and the pages of `.agentplugged/docs/ux-mockups/`. Never edit the PRD, the brief or any other agent's
-  document, the method's files or a generated file.
-- Never choose the front-end stack nor write code, and never call another agent: hand back
-  to Noah, who proposes what comes next; the creator decides (without Noah, the creator picks the next agent).
+- Header: `id`, `kind`, `owner`, `links` only. Write only `ux.md` and `.agentplugged/docs/ux-mockups/`.
+- Never choose the stack, never call another agent: hand back to Noah.

package/dist/method/skills/write-ux-spec/references/accessibility-check.md

@@ -1,74 +1,15 @@
 # Accessibility check
 
-The floor every screen of the specification meets, based on the level AA of the Web Content
-Accessibility Guidelines 2.2. A product may commit to more (in the PRD's non-functional
-requirements); never to less. Check each item against every screen and component, and record the
-result in the specification's "Accessibility check" section: passed, a finding (severity and
-fix), or not applicable.
-
-Severity: **blocking** — some users cannot complete a journey; **major** — they complete it with
-real difficulty; **minor** — an annoyance or an inconsistency.
-
-## Perceive
-
-- **Text contrast.** At least 4.5:1 between text and its background; 3:1 for large text (24px
-  regular, or 18.66px — 14pt — bold). Check every pair of colour tokens used together, in light
-  and dark modes.
-- **Non-text contrast.** At least 3:1 for icons that carry meaning, field borders, focus
-  indicators and the parts of a control needed to see it.
-- **Colour never alone.** An error, a status or a selection is also shown by text, an icon or a
-  shape.
-- **Text size and zoom.** Body text of 16px or more; the layout still works with text enlarged
-  to 200% and at a width of 320px without horizontal scrolling.
-- **Text spacing.** Nothing is cut off or overlaps when the user sets line height to 1.5, space
-  after paragraphs to 2 times the font size, letter spacing to 0.12 and word spacing to 0.16
-  times the font size.
-- **Content on hover or focus.** A tooltip or popover that appears on hover or focus can be
-  dismissed without moving the pointer or focus, stays while the pointer is over it, and stays
-  until dismissed or no longer relevant.
-- **Orientation.** Every screen works in portrait and landscape, unless one orientation is
-  essential.
-- **Structure.** Each page has a title that says what it is; headings name the sections in
-  order; lists and tables are marked as such.
-- **Images and icons.** Each one that carries meaning has a text alternative; decorative ones are
-  hidden from screen readers.
-- **Media.** Video has captions; audio has a transcript.
-
-## Operate
-
-- **Keyboard.** Every action can be done with a keyboard alone, with no trap.
-- **Bypass blocks.** A way to skip repeated content (a "skip to content" link, landmarks or
-  headings) on every page that repeats navigation.
-- **Focus order and visibility.** The focus moves in reading order and is always visible, never
-  hidden behind a sticky element.
-- **Target size.** Touch and click targets of at least 24 by 24px, 44 by 44px for the main
-  actions on touch screens.
-- **Gestures.** Every path or multi-finger gesture and every drag has a single-tap alternative.
-- **Motion.** Animations respect the "reduce motion" setting; nothing flashes more than three
-  times per second.
-- **Timing.** No time limit, or a way to extend or turn it off; moving content can be paused.
-
-## Understand
-
-- **Labels and instructions.** Every field has a visible label; required fields and formats are
-  stated before input.
-- **Errors.** An error says what went wrong and how to fix it, next to the field, and the input
-  is kept.
-- **Redundant entry.** Information the user already gave in the same process is filled in for
-  them or offered to pick, not asked again (unless re-entering it is essential, as for a
-  password confirmation or security).
-- **Accessible authentication.** Signing in never requires a cognitive test (remembering,
-  transcribing or solving something) without an alternative: password managers and pasting are
-  allowed, and a passkey, a link by e-mail or another method is offered.
-- **Consistency.** The same component looks and behaves the same everywhere; navigation stays in
-  the same place.
-- **Language.** The language of each page is declared; plain words, no unexplained jargon.
-- **Undo and confirmation.** An action that deletes, pays or sends can be undone or asks for a
-  confirmation first.
-
-## Robust
-
-- **Names, roles and states.** Each control exposes its name, role and state (selected,
-  expanded, disabled) to assistive technology.
-- **Status messages.** A change announced on screen (saved, error, new item) is also announced to
-  screen readers without moving the focus.
+Floor for every screen (WCAG 2.2 AA). Record each in "Accessibility check": passed, finding
+(**blocking**, **major**, **minor**; the fix) or not applicable.
+
+- **Text contrast** 4.5:1; 3:1 for large text (24px, or 18.66px — 14pt — bold), light and dark;
+  3:1 for icons, borders, focus. **Colour never alone.** Body 16px or more; works at 200% and 320px.
+- **Text spacing**: nothing cut off. **Content on hover or focus**: dismissible. **Orientation**:
+  both. Each page has a title; ordered headings; text alternatives.
+- **Keyboard**: all actions, no trap. **Bypass blocks**: skip link. **Focus order**: reading
+  order, visible. **Target size** 24px (44 on touch). Single-tap alternative to gestures.
+- **Motion**: respects "reduce motion"; no flash. Timing extendable.
+- Visible labels; errors say what and how to fix. **Redundant entry**: not asked again.
+  **Accessible authentication**: no cognitive test without alternative.
+- Consistency, language, undo; names, roles, states; status messages announced.

package/dist/method/skills/write-ux-spec/references/mockups.md

@@ -1,71 +1,9 @@
 # Mock-up pages
 
-Read this when you draw the directions or the key screens. A page shows what the tables say;
-the specification always wins over a page, and `ux.md` says so once, in "Brand and style".
+The specification wins over a page; `ux.md` says so once in "Brand and style".
 
-## The rules of a page (checked by `docs check`)
-
-- A file of `.agentplugged/docs/ux-mockups/`, flat, lowercase letters, digits and hyphens:
-  `directions.html`, `screen-home.html`. Eight pages at most, 30 000 bytes each. Nothing else
-  lives in the folder: another kind of file, or a link, is refused.
-- Start from `assets/mockup-page.html` (in this skill's folder). Its head carries a policy meta
-  that makes a browser load nothing; it comes before any tag of the body, after the charset and
-  viewport metas at most.
-- Self-contained: one inline `<style>`, no script, no image, no font, no `<link>`, no form, no
-  address, no character reference (`&#…;`) in a style. A link is `#anchor` only. Icons are a
-  few inline `<svg>` shapes, whose values are numbers, paths and colours.
-- Plain tags: text, lists, tables, buttons, inputs, `div`/`section`, `svg`. Anything else is
-  refused with its name.
-- Every word comes from the conversation or the specification, never lorem. Text that comes
-  from outside (a pasted brief, a product the creator admires) goes in as plain text with
-  `<`, `>`, `&` written `&lt;`, `&gt;`, `&amp;`: never as markup.
-- Colours, type and spacing are the tokens of the header, copied once as CSS custom properties
-  in `:root` (`--color-primary`), light and dark when the product has both.
-
-## Directions (step "Visual direction")
-
-One page, `directions.html`, two or three directions side by side, each applied to the same
-main screen. A direction is a whole look and feel, not a recoloured copy: two that differ only
-by hue are one direction. They differ by density, weight of type, motion and tone. Each shows
-its name and a line on its mood, its palette as chips with hex values, its type, the screen in
-one awkward state (empty, error…), and dark beside light when the product has both. When only
-the colours are undecided, the page may instead hold up to four palettes on one screen. Say in
-the chat what the creator is looking at; do not paste the page. The creator chooses; the page
-stays and is linked from "Brand and style".
-
-## Key screens (step "Key screens")
-
-Choose two to four screens whose layout decides how the product behaves: where the user starts,
-the busiest step of the longest flow, a layer that asks for a decision. One page each,
-`screen-<slug>.html`, at 1:1: one resting state plus, if it matters, one other (focus, error,
-empty) in the same file. Draw from the tokens, the sketch and the microcopy. A component the
-specification does not name is a question for the creator before it is drawn.
-
-Let a sub-agent in a clean context draw each page: it answers with the path and a one-line
-caption, and the HTML never enters your context. Do not read a page back to check it:
-`docs check` does, and the creator opens it in a browser. A story that builds the screen cites
-its page in its Context; the developer opens it for visual detail only.
-
-## Coverage, asked once
-
-When the pages are drawn, list the screens of the architecture: drawn, or "tables and sketch
-only". Ask: "these will be built from the tables and sketches alone; does any need a visual
-reference?" Draw what the creator names. A screen they choose to leave has `none` in the
-"Mock-up page" cell of its row; `docs check` then only warns.
-
-## Navigation and flows stay in text
-
-The architecture table and a small text map under it (`Home → List → Detail`), the numbered
-steps of each flow and the sketches say what a diagram would. Do not make diagram files: the
-folder holds pages, and an agent can neither read nor check a drawing.
-
-## A change after
-
-A change of a token or of a sketch makes the pages that show it stale. Redraw the key ones or
-say which are old; never let a page contradict the specification without saying so.
-
-## A design tool of the creator's
-
-If the creator draws elsewhere, assemble one prompt from the tokens, the sketches, the flows
-and the microcopy; they run it and bring back what it gave. Look at it, take its decisions into
-the tokens and sketches, and keep nothing but those in the specification.
+- Flat files of `.agentplugged/docs/ux-mockups/`, eight at most, from `assets/mockup-page.html`
+  (no script or link; tokens as CSS custom properties). `docs check` reports faults.
+- `directions.html`: two or three whole looks on one screen.
+- `screen-<slug>.html`, drawn by a sub-agent that returns the path. Ask once which screens need
+  one; `none` in the "Mock-up page" cell for the rest.

package/dist/method/skills/write-ux-spec/references/tokens-and-sketches.md

@@ -1,83 +1,10 @@
 # Tokens, elements and sketches
 
-Read this when you write the visual identity, the screen sketches or the table of elements.
-`npx agentplugged docs check` reads all three; run it after each.
-
-## Tokens: in the header, once
-
-When the product has a brand identity (`launch/identity.md`, skill `write-brand`), its tokens are the
-source: use them by name (`{color.accent}`) and do not define them again; a token given another value
-here is a problem. Its fixed rules also apply to the mock-ups.
-
-The header of `ux.md` carries a `tokens` block. Groups: `color`, `type`, `space`, `radius`,
-`shadow`. Each is a map of named values; a name is letters, digits, `-` or `_`.
-
-```yaml
-tokens:
-  color:
-    background: { light: "#FFFFFF", dark: "#101114" }
-    primary: "#0F62FE"
-    on-primary: "{color.background.light}"   # an alias to another token
-  type:
-    body: { family: "system-ui", size: 16px, weight: 400, line: 1.5 }
-  space: { "1": 4px, "2": 8px, "4": 16px }
-  radius: { md: 8px }
-```
-
-- A colour is a hexadecimal value, or `light` and `dark` hexadecimal values. Nothing else
-  (`blue`, `rgb(…)`) passes.
-- Anywhere else in the specification a token is written `{color.primary}`; the path follows the
-  block (`{type.body.size}`). `docs check` refuses a `{token}` the block does not define, and
-  an alias to nothing. Sizes, colours and durations written inline where a token exists are
-  an excess (see the checklist).
-- Native platforms: a type role may be a phrase (`body: "platform body style"`) when the
-  platform owns the real value. Say it once in Foundation.
-- A specification written before this block may keep its tables of `` `color.primary` ``
-  names; moving them to the header is a good update, never a condition.
-
-## On top of a UI system the product keeps
-
-When the creator keeps a component library or a UI system (their own, or one the product
-adopts), do not specify again what it gives:
-
-1. Foundation names it; the header says `ui_system: <name>`.
-2. `tokens` holds only the difference: the brand colours, the type swaps, the radii that
-   override the system's.
-3. A thing the system already gives is written `{ui.button}` or `{ui.focus-ring}`: with
-   `ui_system` declared these always resolve, without a token. Components then hold only
-   what differs (a state, a variant, a rule of behaviour).
-4. The choice of the library is Alex's. Note the preference in Foundation and stay with
-   whatever the architecture decides; when it changes, update the delta.
-
-## Elements to build: `UX-n`
-
-The table "Elements to build" numbers what the stories must carry: each component, each state
-worth a story's attention, each accessibility fix the check found. One row each (`UX-1`,
-`UX-2`…), kind, description, where. Never renumber; a thing no longer wanted stays, its
-description beginning `(retired)`.
-
-Once stories exist, `docs check` and the readiness gate refuse an element no story names in
-its Context or acceptance criteria. That is the way a state or a fix is not forgotten between
-the specification and the build. Number what a developer would otherwise reinvent, not every
-label.
-
-## Sketches: one per screen
-
-Under "Screen sketches" (keep that title, and "Key screens": the checks find the sections by
-them, in English or as « Croquis des écrans », « Écrans clés »), one `### <screen name>` per screen of the architecture (the key
-screens first). Each holds a drawing in a code block, every region marked `[1]`, `[2]`…, and
-the list `1.`, `2.`… saying what each region holds and its states. The numbers match in both
-places, start at 1, have no gap; two regions at least.
-
-```
-+------------------------+
-| [1] date, count        |
-| [2] task rows          |
-|            [3] add     |
-+------------------------+
-```
-
-A story of the interface takes the sketch of its screen as an acceptance criterion: "given
-the screen, when it opens, then its regions 1 to 3 are those of the sketch in `ux.md`". The
-sketch is not pixels: the layout order, the grouping and what each region does. Pixels and
-colours are tokens or the page.
+- **Tokens**, in the header: `color`, `type`, `space`, `radius`, `shadow`; a colour is hexadecimal
+  (or `light` and `dark`); elsewhere `{color.primary}`, undefined is refused. A brand identity
+  (`launch/identity.md`, skill `write-brand`) is the source: use its tokens by name.
+- **UI system kept:** `ui_system: <name>`; `tokens` only the difference; `{ui.button}` resolves.
+- **Elements to build:** one `UX-n` row per component, state or fix a story must carry; never
+  renumbered, a dropped one starts `(retired)`.
+- **Sketches:** under "Screen sketches", `### <screen>`: a code-block drawing with regions `[1]`,
+  `[2]`… and a list `1.`, `2.`… saying what each holds.

package/dist/method/skills/write-ux-spec/references/ux-checklist.md

@@ -1,74 +1,19 @@
 # UX specification checklist
 
-Run every check before showing the specification to the creator. Fix what fails; when a fix
-needs the creator, ask them, one question at a time, or open a `decision` checkpoint.
+Run before showing it.
 
-## Header and identifiers
-
-- The header is the first thing in the file and holds `id: ux`, `kind: ux`, `owner: stella` and
-  `links`: `prd` and every `PU-n` and `EF-n` the specification covers, all active in the PRD.
-- No `status`, `state`, `cost`, `spent`, `budget_spent` or `progress` key.
-- No requirement identifier is defined: none opens a line, a list item, a heading or a first
-  table cell.
-- No `<…>` placeholder is left from the template, no value marked `(sample)` (the sample
-  colours `#FFFFFF`, `#111111`, `#1A1A1A`, `#F2F2F2`, `#0F62FE`, `#78A9FF`, sizes `16px`, `24px`, `400`, `600`, `1.5`, `1.25`, spacings
-  `4px`, `8px`, radius `8px`) unless the creator chose that exact value, no sample link (`PU-1`,
-  `EF-1`) the specification does not cover, and no `screen-sample.html`.
-- No `[open: G-…]` mark remains for a decision the creator already answered, and none sits at
-  the start of a line or before an identifier.
-- `npx agentplugged docs check` reports no problem.
-
-## Coverage
-
-- Every journey of the PRD has a key flow, with its moment of value and its failure path.
-- Every screen serves at least one journey, and every journey lands on screens.
-- Every flow names the requirements it covers; the "Traceability" table agrees with the flows.
-- Every screen lists the states that apply (empty, loading, error, success, offline, permission
-  denied), with what the user sees.
-- Nothing in the specification asks for a capability the PRD does not state: such a need is an
-  open question.
-
-## Visual identity
-
-- Every colour token has a hexadecimal value for each mode the product supports.
-- Every token used in the text (`{…}`) is defined once, in the `tokens` block of the header
-  (`docs check` refuses one that is not); on a UI system the product keeps, `ui_system` is
-  declared and the tokens hold only the difference.
-- Every component used in a flow has a visual specification and a behaviour.
-- The visual direction is the one the creator chose; every guess is marked `[assumption]`.
-
-## Screens, sketches and pages
-
-- Every screen of the architecture has a sketch whose regions are numbered the same in the
-  drawing and in the list; the key screens (two to four) each have a page, or `none` by the
-  creator's choice.
-- Each page was drawn from the tokens and the sketch, shows the product's own words, and
-  `ux.md` states once that the specification wins over any page.
-- Every component, state and accessibility fix a story must carry is a `UX-n` of "Elements to
-  build", none renumbered.
-
-## Accessibility
-
-- Every item of `references/accessibility-check.md` has a result in "Accessibility check".
-- No blocking finding is left without a fix or the creator's explicit acceptance.
+- Header `id: ux`, `kind: ux`, `owner: stella`, `links`; no `status`, `cost`, `progress`; no
+  identifier defined; no placeholder, comment, answered `[open: G-…]` or template sample
+  (`#FFFFFF`, `#0F62FE`, `16px`…) unless chosen. `docs check` clean.
+- Every journey has a key flow; every screen serves one, lists its states, has a numbered sketch;
+  nothing asks for what the PRD does not state; every `{…}` is defined.
+- Every accessibility item has a result; no blocking finding unfixed.
 
 ## Excess (over-specification)
 
-A specification says each thing once, at the level a builder needs. Each excess is a finding,
-minor unless it hides a decision; for an independent verdict, ask a sub-agent for the method
-`judgment` (skill `critique-deliverable`), reported in its closed form.
-
-- **One home per value.** A size, colour or duration written inline that a token already names,
-  or that a rule would give.
-- **One home per fact.** Content copied from the PRD that its identifier would carry.
-- **A reader per section.** Ask who would miss it; a section nobody builds from, or a story
-  about the brand that settles no choice, goes.
-- **Reachable.** A screen or a state that no journey of the PRD reaches.
-
-## Form
+Each a finding; for a verdict, a sub-agent runs `judgment` (skill `critique-deliverable`).
 
-- The terms are those of the PRD's glossary.
-- Tables are used where they read better than prose; no section is padded.
-- No guidance comment and no "Generated by agentplugged" line is left.
-- The stack and the code are left to Alex and the developers: a preference is noted, never
-  decided.
+- **One home per value.** An inline value a token names.
+- **One home per fact.** PRD content its identifier carries.
+- **A reader per section.** A section nobody builds from goes.
+- **Reachable.** A screen or state that no journey of the PRD reaches.