agentplugged 0.0.1 → 1.0.1

package/dist/method/skills/write-spec/references/spec-guide.md

@@ -0,0 +1,47 @@
+# The spec: parts, scope and growth
+
+## Writing it
+
+Copy the template to `.agentplugged/docs/spec.md`; keep the header keys and the part markers;
+remove the guidance comments, the "Generated by agentplugged" line and every `<…>` placeholder.
+Each `EF-n` is testable, each `ENF-n` has a threshold, each `AD-n` states Binds, Prevents and Rule,
+every `EF-n` is in a story line. A choice between real options goes to a `decision` checkpoint,
+never settled in the creator's place. The header holds the scope and no status, cost or progress.
+
+## The four parts
+
+Each part opens with its marker (`part: brief`, `requirements`, `decisions` or `stories`, as an
+HTML comment on its own line, before the heading) and stays short: a spec that needs more than
+about 15 functional requirements or 8 stories is no longer a short spec.
+
+- **Brief:** the product, its users, the problem, what is out of scope. The creator's words.
+- **Requirements:** `EF-n` (one testable sentence), `ENF-n` (a threshold and how it is measured).
+  When the scope names personal data, a payment or accounts, write the security requirements it
+  calls for as `ENF-n` (who may read what, where secrets live, what is logged): the register of
+  requirements and the security reviews read them there.
+- **Decisions:** `AD-n`, only what binds every story, each with its three fields (Binds,
+  Prevents, Rule).
+- **Stories:** one line each, `1-1 : title (EF-1, ENF-2)`; the epic is the first number.
+
+## The scope in the header
+
+`size` (small, medium, large), `users` (a number, the first year), `sensitive` (a list among
+`personal_data`, `payment`, `accounts`; `[]` when none), `integrations` (external services),
+`platforms`. They are the creator's answers, never your estimate. A product with something in
+`sensitive` takes the short path only if the creator asked for it: `asked: short` in the header,
+and `docs check` refuses it otherwise (`SPEC_SCOPE`). Never lower a risk to keep the short path.
+
+## Growing
+
+`state.next` says `spec_path: grow` (with `spec_path_why`) when the scope or the size of the spec
+calls for the full path. Noah offers it in one line; the creator decides. When they accept, the
+full path is on again (`step_resume` of `full_path`) and `npx agentplugged docs grow` writes the
+brief, the PRD and the architecture from the spec's parts, word for word, identifiers kept, and
+removes the spec. Nothing is retyped; the new documents are validated like any others.
+
+## The readiness gate
+
+The spec passes the gate too, in its light form (`track: short`): the engine checks it is validated
+and unchanged, its identifiers known and each requirement carried by a story; Izzy reads the spec and
+the stories for contradictions and gaps, six findings at most (skill `check-readiness`). Noah
+proposes it from `state.next` `readiness`, before the stories are cut or built.

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

@@ -0,0 +1,191 @@
+---
+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.
+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.
+
+## 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).
+
+## 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.
+
+## 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
+   (`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`.
+
+    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`.
+
+## 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).

package/dist/method/skills/write-ux-spec/assets/mockup-page.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+<title>Screen name</title>
+<style>
+/* What this page shows of ux.md: the sketch, the components, the states. ux.md wins over the page. */
+:root {
+  --color-background: #ffffff;
+  --color-text: #1a1a1a;
+  --color-primary: #0f62fe;
+  --space-2: 8px;
+  --space-4: 16px;
+  --radius-md: 8px;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-background: #111111;
+    --color-text: #f2f2f2;
+  }
+}
+body { margin: 0; background: var(--color-background); color: var(--color-text); font: 16px/1.5 system-ui, sans-serif; }
+.frame { max-width: 390px; margin: var(--space-4) auto; border: 1px solid currentColor; border-radius: var(--radius-md); padding: var(--space-4); }
+button { background: var(--color-primary); color: var(--color-background); border: 0; border-radius: var(--radius-md); padding: var(--space-2) var(--space-4); font: inherit; }
+</style>
+</head>
+<body>
+<main class="frame" aria-label="Screen name">
+<h1>Screen name</h1>
+<p>Real content of the product goes here.</p>
+<button type="button">Action</button>
+</main>
+</body>
+</html>

package/dist/method/skills/write-ux-spec/assets/ux-template.md

@@ -0,0 +1,206 @@
+---
+id: ux
+kind: ux
+owner: stella
+links:
+  - prd
+  - PU-1
+  - EF-1
+# The design tokens, defined once, here. Groups: color, type, space, radius, shadow. A colour is a
+# hexadecimal value (or light/dark). Every value marked (sample) is replaced by the creator's choice.
+# On top of a UI system the product keeps, add `ui_system: <its name>` and write only the difference.
+tokens:
+  color:
+    background: { light: "#FFFFFF", dark: "#111111" } # (sample)
+    text: { light: "#1A1A1A", dark: "#F2F2F2" } # (sample)
+    primary: { light: "#0F62FE", dark: "#78A9FF" } # (sample)
+  type:
+    body: { family: "system-ui", size: 16px, weight: 400, line: 1.5 } # (sample)
+    title: { family: "system-ui", size: 24px, weight: 600, line: 1.25 } # (sample)
+  space:
+    "1": 4px # (sample)
+    "2": 8px # (sample)
+  radius:
+    md: 8px # (sample)
+  shadow:
+    "1": "0 1px 3px rgba(0, 0, 0, 0.2)" # (sample)
+---
+<!-- UX specification template (skill write-ux-spec). Copy it to .agentplugged/docs/ux.md, write it
+in the creator's language, and remove these guidance comments as each section is written, along with
+the "Generated by agentplugged" line, every <…> placeholder and every value marked (sample): they show
+the expected form only. `links` names the PRD and every journey and requirement the specification
+covers (PU-1 and EF-1 are placeholders). Never add a status, a cost or a progress to the header.
+
+This document defines no requirement identifier: it mentions those of the PRD inside a line, never at
+the start of a line, a list item, a heading or a first table cell. A token is defined in the header and
+written `{color.primary}` everywhere else. Its own elements are `UX-n`, defined in one table. -->
+
+# UX specification: <product name>
+
+## Foundation
+
+<!-- Platforms and form factors, input modes, the component library or UI system the creator keeps
+(a preference for the architect, not a decision), and the products that inspire or repel the creator. -->
+
+- Platforms: <phone, desktop, web…>
+- Input modes: <touch, keyboard, voice…>
+- Preferred component library: <none, or its name>
+- Inspiration: <product> — <what to take from it>
+- To avoid: <product or pattern> — <why>
+
+# Part 1 — Visual identity
+
+## Brand and style
+
+<!-- The feeling the product gives, the direction the creator chose, and what it rules out. Link the
+directions page if one was drawn: [directions](ux-mockups/directions.html). The specification wins
+over every page. -->
+
+## Colours
+
+<!-- The role of each colour token, where it is used and never used. Values live in the header. -->
+
+## Typography
+
+<!-- The type roles and the rules that use them. Values live in the header. -->
+
+## Spacing and layout
+
+<!-- How the spacing scale is used, the grid, margins, breakpoints. -->
+
+## Shapes and elevation
+
+<!-- Where radii and shadows apply. -->
+
+## Components
+
+<!-- Each component: its anatomy, the tokens it uses, the look of each state. The Element column names
+the UX-n of the table "Elements to build". -->
+
+| Component | Element | Anatomy | Tokens | States |
+| --- | --- | --- | --- | --- |
+| <button> | UX-1 | <label, icon> | `{color.primary}`, `{radius.md}` | <how each state looks> |
+
+## Do and don't
+
+- Do: <visual rule>
+- Don't: <visual rule>
+
+# Part 2 — Behaviour
+
+## Information architecture
+
+<!-- Every screen, what it holds, the journeys it serves, how it is reached. Each journey lands on
+screens; each screen serves a journey. Under the table, a small text map of the navigation in a code
+block (Home → List → Detail) when it helps. -->
+
+| Screen | Purpose | Journeys | Reached from |
+| --- | --- | --- | --- |
+| <screen> | <what it is for> | PU-1 | <screen or entry point> |
+
+## Key screens
+
+<!-- Two to four screens where the layout carries the behaviour. One row each, with its page in the
+second column. If the creator chooses to build a screen from the tables alone, write `none` there.
+Keep the titles "Key screens" and "Screen sketches" as they are (or "Écrans clés", "Croquis des écrans"):
+the checks find the sections by them. -->
+
+| Screen | Mock-up page | Why it is key |
+| --- | --- | --- |
+| <screen> | [<screen>](ux-mockups/screen-sample.html) (sample) | <what the layout decides> |
+
+## Screen sketches
+
+<!-- One block per screen of the architecture (the key ones first), titled with the screen's name:
+a drawing in a code block, each region marked [1], [2]…, then the list of what each region holds, in
+the same numbers, from 1. Stories of the screen take these regions as acceptance criteria. -->
+
+### <screen>
+
+```
++----------------------+
+| [1] <region>         |
+| [2] <region>         |
++----------------------+
+```
+
+1. <region>: <what it holds, its states>
+2. <region>: <what it holds, its states>
+
+## Key flows
+
+<!-- One flow per journey of the PRD. -->
+
+### <flow name>
+
+Covers: PU-1, EF-1.
+
+1. <what the user sees> — <what they do> — <what the product answers>
+2. <next step>
+
+- Moment of value: <when the user gets what they came for>
+- Failure path: <what can go wrong, what the user sees, how they recover>
+- States met: <empty, loading, error…>
+- Microcopy: <the exact texts of the steps>
+
+## Component behaviour
+
+<!-- How each component reacts: input, validation, feedback, focus, undo. -->
+
+## States
+
+<!-- For each screen, the states that apply and what the user sees: empty, loading, error, success,
+offline, permission denied. -->
+
+## Interactions
+
+<!-- Gestures, keyboard shortcuts, feedback, confirmations, undo, transitions. -->
+
+## Microcopy and voice
+
+<!-- The tone of the product's words, the terms used (those of the PRD's glossary), and the texts of
+buttons, errors and empty states. -->
+
+## Responsive and platforms
+
+<!-- How layouts adapt to each breakpoint and platform. -->
+
+## Accessibility floor
+
+<!-- The level the product commits to, and the rules every screen follows (see the check). -->
+
+## Accessibility check
+
+<!-- One row per check of the accessibility reference: passed, finding or not applicable. A finding
+carries its severity (blocking, major, minor) and its fix; a fix to build is an element below. -->
+
+| Check | Screens or components | Result | Severity | Fix |
+| --- | --- | --- | --- | --- |
+| Text contrast | <all> | <passed, finding, n/a> | <severity> | <fix> |
+
+## Elements to build
+
+<!-- What the stories must carry, one row each, numbered UX-1, UX-2… and never renumbered: the
+components, the states and the accessibility fixes. A story names it in its Context. An element that
+is no longer wanted stays, with (retired) at the start of its description. -->
+
+| Id | Kind | Description | Where |
+| --- | --- | --- | --- |
+| UX-1 | component | <button> | <screens> |
+| UX-2 | state | <empty list> | <screen> |
+
+## Traceability
+
+<!-- Which flow or screen covers which journey and requirement of the PRD. The first cell is always
+the flow or the screen. -->
+
+| Flow or screen | Journeys | Requirements |
+| --- | --- | --- |
+| <flow name> | PU-1 | EF-1 |
+
+## Open questions
+
+<!-- Needs the PRD does not cover (for the creator and Maya), choices waiting for a decision
+([open: G-…] in the text), and every [assumption] mark. -->
+
+- <question>

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

@@ -0,0 +1,74 @@
+# 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.

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

@@ -0,0 +1,71 @@
+# 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 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.