@lemoncode/lemony 0.1.0 → 0.1.1-alpha.0

package/catalog/skills/grill-ui/ui-handoff-format.md

@@ -0,0 +1,148 @@
+# `ui-handoff.md` — the design contract
+
+The artifact the UI Designer produces in DEFINE and the implementer builds from when implementing. It lives at
+`.claude/state/tasks/<id>/spec/ui-handoff.md`, a sibling of the spec, owned by the UI Designer.
+
+**It captures DECISIONS and targets, not know-how.** How to apply tokens to a stack, avoid generic
+"AI slop", or meet WCAG lives in the implementer's and reviewer's skills. This file says _what to
+build_ and _how it should look and feel_, at a level the implementer can execute and the review can
+check.
+
+## Two principles that shape every section
+
+- **Graduated altitude.** Default to **decisions-altitude**: reference the design system, name the
+  variant, state the few things that matter. Drop to the full **component anatomy** (below) ONLY for
+  a genuinely novel or critical component. Don't freeze what the implementer's model already knows.
+- **Text-first.** Screens travel as a text inventory + a nav/flow map + per-screen structural intent.
+  The implementer generates the pixels from that + the tokens + the anti-slop know-how. A visual
+  tool, if the designer used one, is a private DEFINE aid — not a consumed contract.
+
+Every section is **N/A-able** per task: mark a section N/A rather than padding it.
+
+---
+
+## Template
+
+```markdown
+# UI handoff — #<id> <topic>
+
+**Status**: in_progress | completed
+
+> Owned by the UI Designer. Sibling of the spec. The implementer builds from this via the `build-ui`
+> skill; the design QA lens checks the built UI against it at REVIEW. Decisions-altitude; text-first;
+> tokens by reference.
+
+## 1. Personas / users served
+
+<!-- Who this serves and the context that shapes design. Consume docs/personas.md if present;
+     never restate it wholesale — capture only what drives a design decision here. -->
+
+## 2. Aesthetic direction
+
+**Tone preset**: controlled | impact | innovative | (none)
+**Dials**: variance = low|medium|high · motion = low|medium|high · density = low|medium|high
+**Brand references**: <sites/products admired, and what to take from each>
+**Voice / feel**: <a few words — e.g. "calm, precise, trustworthy">
+
+<!-- See "Direction language" below for what the presets and dials mean. The dials are the
+     verifiable contract; the review checks the built UI against them. -->
+
+## 3. Screen inventory + nav / flow
+
+<!-- The screens/surfaces this task adds or changes, and how the user moves between them.
+     Text or a mermaid flow diagram. No pixels. -->
+
+## 4. Per-screen layout
+
+<!-- For each screen: regions, hierarchy, what draws the eye first. Words, not mockups. -->
+
+## 5. Components
+
+<!-- Decisions-altitude by default: name the component, the variant, and the states that matter.
+     Use the full anatomy (below) ONLY for a novel or critical component. -->
+
+## 6. States
+
+<!-- Empty / loading / error / success / edge content for the task's surfaces. -->
+
+## 7. Responsive / breakpoints
+
+<!-- The behavior that actually changes across breakpoints for this task. -->
+
+## 8. Motion / interaction
+
+<!-- Motion appetite (from the dial) + the few interactions that carry meaning. -->
+
+## 9. Accessibility
+
+<!-- Target level (default WCAG 2.1 AA) + task-specific a11y decisions. The audit and the
+     how-to are skills; capture only decisions here. -->
+
+## 10. Microcopy
+
+<!-- The actual words for the task's key labels and messages, inline. Voice follows §2. -->
+
+## 11. Token reference
+
+Reference `docs/design-tokens.json` — the single, client-owned source of truth, a 3-tier
+W3C-DTCG model (`primitive` → `semantic` → `component`). **Never inline token values here; point at
+the file.** If the project has no token file yet, say so and capture it as an open question — never
+invent a token set. `lemony design-tokens validate` flags raw colours/dimensions in source that
+should reference a token.
+
+## Open questions
+
+<!-- Anything the interview left unresolved. If a fork has more than one valid answer and the user
+     can't resolve it, raise a discovery rather than guess. -->
+```
+
+---
+
+## Direction language (for §2)
+
+The aesthetic direction is expressed as three explicit **dials**, optionally seeded by a **tone
+preset**. Dials are reproducible and review-verifiable; they exist to fight the generic defaults a
+model reaches for unprompted.
+
+### Dials
+
+- **Variance** — _conventional ↔ expressive._ How far the design departs from safe, system-default
+  patterns.
+  - **low** — predictable, system-like, fast to build; risks looking generic.
+  - **medium** — distinctive but restrained; a clear point of view without flamboyance.
+  - **high** — bold, characterful, memorable; more build cost and more ways to get it wrong.
+- **Motion** — _still ↔ animated._ Appetite for transition and animation.
+  - **low** — minimal, functional transitions only.
+  - **medium** — purposeful motion on key interactions.
+  - **high** — rich, choreographed motion as part of the identity.
+- **Density** — _airy ↔ compact._ Information density and use of whitespace.
+  - **low** — spacious, generous whitespace, few elements per view.
+  - **medium** — balanced.
+  - **high** — dense, data-rich, efficient for expert/repeat use.
+
+### Tone presets (optional shorthand)
+
+A preset seeds default dial values as a starting point; the user can override any dial after.
+
+| Preset         | variance | motion | density | Feel                                               |
+| -------------- | -------- | ------ | ------- | -------------------------------------------------- |
+| **controlled** | low      | low    | medium  | Calm, trustworthy, enterprise; clarity over flair. |
+| **impact**     | high     | medium | low     | Bold, memorable, marketing-forward; few big moves. |
+| **innovative** | high     | high   | medium  | Novel, dynamic, cutting-edge; motion as identity.  |
+
+---
+
+## Component anatomy (for §5, novel/critical components only)
+
+Drop to this fuller shape ONLY when a component is genuinely new to the project or critical enough
+that the review needs a fixed reference. For everything else, decisions-altitude (name + variant +
+states-that-matter) is enough.
+
+1. **Description / when to use** — what it is and when to reach for it.
+2. **Variants** — the variants and when each applies.
+3. **Props / properties** — the inputs that change its appearance or behavior.
+4. **States** — default / hover / active / focus / disabled / loading / error, as applicable.
+5. **Anatomy / layout** — the internal regions and their arrangement (text).
+6. **Behavior / interaction** — what it does on interaction, including motion.
+7. **Accessibility** — role, keyboard interaction, focus handling, screen-reader announcement.
+8. **Do's and Don'ts** — the traps specific to this component.

package/catalog/skills/grill-with-docs/SKILL.md

@@ -4,6 +4,13 @@ description: Relentlessly interview the user about a plan or design until shared
 origin: vendor
 vendor_version: '{{vendor_version}}'
 invoked-by: [orchestrator, architect]
+attribution:
+  - source: mattpocock/skills
+    author: Matt Pocock
+    url: https://github.com/mattpocock/skills
+    license: MIT
+    relationship: derived-from
+    note: grill workflow and decision-by-decision interview structure
 ---
 
 # Grill With Docs
@@ -41,7 +48,7 @@ If ambiguous, ask whether the user wants the plan challenged or built together.
     the grill against it so proposals don't contradict existing boundaries/seams. Trust it
     for the big picture; verify against code where a decision actually turns on it. It is
     **absent by default and that is fine** — grill as today, and never push the user to
-    create it (decision #8; it is **not** one of the files this skill creates lazily below).
+    create it (it is **not** one of the files this skill creates lazily below).
   - `docs/adr/` if present
   - The project's playbooks — `docs/playbooks/<topic>.md` (then the global layer),
     discovered by topic filename
@@ -117,7 +124,7 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma
 │       └── docs/adr/
 ```
 
-Create files and directories lazily — only when there's something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. Same for `docs/prds/` when the first PRD lands. **`docs/architecture.md` is the exception — never create it here.** It is client-owned (decision #8); only the Architect's `update-architecture` skill ever edits it (and only when the file already exists).
+Create files and directories lazily — only when there's something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. Same for `docs/prds/` when the first PRD lands. **`docs/architecture.md` is the exception — never create it here.** It is client-owned; only the Architect's `update-architecture` skill ever edits it (and only when the file already exists).
 
 #### Challenge against the glossary
 

package/catalog/skills/mutation-testing/SKILL.md

@@ -26,7 +26,7 @@ slow.
 ## Precondition (capability-gated)
 
 This skill is only installed when the project declares a **`test:mutation`** script in
-`package.json` (the `has-mutation-testing` capability, #155). If you are reading it, the
+`package.json` (the `has-mutation-testing` capability). If you are reading it, the
 script exists — run it. The harness stays tool-agnostic: the script may drive Stryker or
 any mutation tool. Delegate to it exactly as `verify` delegates to the project's
 declared scripts; never assume a specific tool's CLI.

package/catalog/skills/note-side-finding/SKILL.md

@@ -39,7 +39,7 @@ discovery (pause and stop). When genuinely unsure whether it blocks you, prefer
 `raise-discovery` — a wrong pause is cheaper than coding past a real contradiction.
 
 The same channel covers **architecturally-significant drift in `docs/architecture.md`**
-(ADR 0011) — when you read the map to orient and find it states a boundary/seam the code no
+— when you read the map to orient and find it states a boundary/seam the code no
 longer matches, in an area your task doesn't touch. That is a defect of the _map_, not the
 code: non-blocking and out of your scope, so it rides here. Tag such a bullet `kind: drift`
 (see the contract below) so the Orchestrator routes it to the Architect's

package/catalog/skills/playbook-iterate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playbook-iterate
-description: Propose changes to a client playbook — or extract a new one from the codebase — when the spec collides with a documented pattern (a T6 PLAYBOOK_CONFLICT) or the client asks. Playbooks are client-owned (decision #8); the Architect proposes and the human decides. Use when the Orchestrator routes a T6 discovery resolution to the Architect, or on an explicit "capture how we do X" request.
+description: Propose changes to a client playbook — or extract a new one from the codebase — when the spec collides with a documented pattern (a T6 PLAYBOOK_CONFLICT) or the client asks. Playbooks are client-owned; the Architect proposes and the human decides. Use when the Orchestrator routes a T6 discovery resolution to the Architect, or on an explicit "capture how we do X" request.
 origin: vendor
 vendor_version: '{{vendor_version}}'
 invoked-by: [architect]
@@ -13,7 +13,7 @@ trigger-condition: a T6 PLAYBOOK_CONFLICT needs the playbook changed, or the cli
 
 A **playbook** describes _how to build_ a category of software (a backend service, an
 SPA, a testing strategy) in **project-agnostic** terms — placeholder names, never a real
-codebase's symbols. Playbooks are **client-owned** (decision #8): the vendor ships the
+codebase's symbols. Playbooks are **client-owned**: the vendor ships the
 _format_ and the _lookup convention_, never the content. So this skill **proposes**; the
 human **decides**. The Architect never rewrites a client playbook unilaterally.
 

package/catalog/skills/review-pr/SKILL.md

@@ -20,8 +20,8 @@ heavier tool, deliberately not this one.
 
 ### 0. Resolve the PR
 
-- **URL** (`https://github.com/<org>/<repo>/pull/123`): extract `<org>/<repo>` + number.
-- **Number** (`#834`, `834`): resolve the repo with `gh repo view --json nameWithOwner`.
+- **URL** (`https://github.com/<org>/<repo>/pull/<n>`): extract `<org>/<repo>` + number.
+- **Number** (`#<n>`, `<n>`): resolve the repo with `gh repo view --json nameWithOwner`.
 - **No argument**: detect the open PR on the current branch with `gh pr view`.
 
 Run in parallel:
@@ -37,7 +37,7 @@ Read the repo's `CLAUDE.md` (and `CONTEXT.md` if present). Summarize in ≤ 50 l
 code-style rules, comment conventions, naming, architecture constraints. This is what
 the analysis judges "against project convention" by.
 
-### 2. Analyze (single sub-agent, the #43 lenses as a checklist)
+### 2. Analyze (single sub-agent, the review lenses as a checklist)
 
 Spawn **one** `Explore` sub-agent with the full diff, the changed-files list, and the
 project context. Its prompt walks the five review lenses as a checklist — **not** five

package/catalog/skills/task-closeout/SKILL.md

@@ -10,7 +10,7 @@ invoked-by: [orchestrator]
 
 ## Core Principle
 
-Closeout is **archive-on-done through a dedicated PR** (ADR 0009). The durable memory of
+Closeout is **archive-on-done through a dedicated PR**. The durable memory of
 a finished task — its spec and its resolved discoveries — is **archived live**, not
 deleted, so a future agent reads the decisions instead of doing git archaeology. The
 genuinely architectural decisions rise further, to ADRs. And the closeout record reaches
@@ -19,7 +19,7 @@ every other change obeys.
 
 Three moves, in this order:
 
-1. **Activate the Architect** — closeout is its reliable end-of-task checkpoint (#138).
+1. **Activate the Architect** — closeout is its reliable end-of-task checkpoint.
    In cold blood, no resume pressure, it drives durable capture: `write-adr` (HITL offer
    per resolved discovery), `update-architecture` (automatic, when the map exists), and
    `playbook-iterate` (HITL offer, once per task). The canon outlives any task folder.
@@ -56,7 +56,7 @@ merge, then records it.
 
 Archival is **destructive** and must wait until the task PR is merged. Until that merge,
 the task can re-enter iteration — a Reviewer rejection, or human review comments at the
-gate (#111) — and that re-work needs the spec **live** in `tasks/<id>/spec/`. Archiving
+gate — and that re-work needs the spec **live** in `tasks/<id>/spec/`. Archiving
 pre-merge would pull the spec out from under an in-flight fix. So every step below runs
 **after** the merge is confirmed.
 
@@ -68,12 +68,12 @@ merged base: `git checkout <default> && git pull`.
 
 ### 1. Activate the Architect for durable capture
 
-Closeout is the Architect's **reliable activation point** (#138): in cold blood, after
+Closeout is the Architect's **reliable activation point**: in cold blood, after
 the merge, with no paused sub-agent pulling toward "just unblock me", it drives the three
 durable-capture skills the on-demand triggers otherwise lose. Each one **no-ops cleanly
 when its skill isn't installed**, so this step is safe everywhere.
 
-The three differ in **who decides** — and the asymmetry is deliberate (ADR 0010):
+The three differ in **who decides** — and the asymmetry is deliberate:
 
 - **`write-adr` — HITL offer, per resolved discovery.** Walk the **resolved** entries in
   `discoveries.md` and **offer** the ones that settled a real decision (not a trivial
@@ -153,7 +153,9 @@ git rm -r .claude/state/tasks/<id>/
 
 `spec/` and `discoveries.md` survive **live** under `_archive/<id>/` (grep-able), plus in
 git history and the GitHub issue. `progress.md` (the pause-point bitácora) and any other
-working scratch are gone.
+working scratch are gone. A UI task's **`ui-handoff.md`** is a sibling **inside**
+`spec/`, so the single `git mv` of `spec/` archives it with the rest — no special
+handling.
 
 ### 5. Open the closeout PR and auto-merge
 
@@ -204,8 +206,7 @@ Then flip the issue to `harness:status:done` and **emit `task_done`** — both h
 in finalize, exactly once (the parked → `/resume` path also lands here, so it is the
 single emit point for either path). You compute the envelope (cycle time, review
 rejections, level) as the Orchestrator running this skill; the fields and the `emit`
-command line are in `orchestrator.md` §Closeout. `events.jsonl` is local-only/gitignored
-(ADR 0008), so the emit never dirties the base.
+command line are in `orchestrator.md` §Closeout. `events.jsonl` is local-only/gitignored, so the emit never dirties the base.
 
 ### 7. Report
 

package/catalog/skills/update-architecture/SKILL.md

@@ -18,13 +18,13 @@ updated. This skill keeps it true to reality after an architecturally significan
 
 The trigger is usually a change in hand, but the job is the same when **drift is surfaced
 without a change** — an orientation or review finds the map already diverged from the code
-(a `code-explorer` Notes flag, a Reviewer side-finding; ADR 0011). Reconcile it the same
+(a `code-explorer` Notes flag, a Reviewer side-finding). Reconcile it the same
 way, applying the same significance bar below: only shape-level divergence is worth an edit.
 
 It is gated on `applies-when: has-architecture-doc`: it only installs when the project
 already keeps `docs/architecture.md`. The harness **never creates** an architecture doc
-where the client chose not to have one (decision #8 — the vendor gives the framework,
-not the architecture). If a project has no such doc and one is wanted, that's a client
+where the client chose not to have one — the vendor gives the framework,
+not the architecture. If a project has no such doc and one is wanted, that's a client
 decision, not an automatic harness action.
 
 ## What counts as architecturally significant

package/catalog/templates/claude-code/agents.md.tpl

@@ -5,9 +5,9 @@
 
 This file is the **dispatcher** the Orchestrator follows on every session. The
 Orchestrator is the single human-facing hat; it invokes sub-agents (Spec Author,
-Implementer, Reviewer) with fresh context via the Task tool. Full role rules live
-in `.claude/agents/<role>.md`; skills in `.claude/skills/`; task state in
-`.claude/state/`.
+Implementer, Reviewer, and the on-demand Architect / UI Designer) with fresh context
+via the Task tool. Full role rules live in `.claude/agents/<role>.md`; skills in
+`.claude/skills/`; task state in `.claude/state/`.
 
 ## Mode dispatcher
 
@@ -40,7 +40,7 @@ surface the menu.
 
 ## Task-fit dial
 
-The harness is a dial, not on/off (decisions #57–#61):
+The harness is a dial, not on/off:
 
 - **L1 — full SDD**: real features. Grill → spec → human gate → implement → review.
 - **L2 — lightweight**: small bugs. Issue + state + implement (TDD) + light review.
@@ -60,10 +60,14 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
 3. **Spec** — Spec Author sub-agent (given the `<id>` + branch): `prd-to-spec` (→
    `requirements.md` EARS + `design.md` + `tasks.md` under `tasks/<id>/spec/`) then
    `spec-to-issue` (fills the issue body — it creates nothing and moves no labels).
-4. **Spec-ready + handoff** — flip to `harness:status:spec-ready`, commit and push the
-   task state to the branch. DEFINE can stop here: the spec-ready queue
-   (`gh issue list -l harness:status:spec-ready`) is the handoff. Ask: implement now or
-   hand off?
+   **UI design gate** (§UI design in `orchestrator.md`): if the repo has a frontend AND
+   the task touches UI, put `harness:needs-design`, offer the design-stop, and on
+   "continue" dispatch the **UI Designer** to author `ui-handoff.md` alongside the spec.
+4. **Spec-ready + handoff** — remove `harness:needs-design` once `ui-handoff.md` is
+   complete (a spec-ready task never carries it), flip to `harness:status:spec-ready`,
+   commit and push the task state to the branch. DEFINE can stop here: the spec-ready
+   queue (`gh issue list -l harness:status:spec-ready`) is the handoff. Ask: implement
+   now or hand off?
 5. **Approval gate** — run by whoever implements (a RESUME of a spec-ready issue runs
    it). Present the spec; the human approves (or asks for changes → Spec Author
    revises). On approval, flip to `harness:status:in-progress`. The spec, not the code,
@@ -71,7 +75,9 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
 6. **Implement** — Implementer sub-agent, `tdd` skill, on the branch, keeping
    `.claude/state/tasks/<id>/progress.md` live.
 7. **Review** — flip to `harness:status:in-review`, open the PR (`gh pr create`,
-   branch → default), Reviewer sub-agent reviews it (`senior-review`, fresh context).
+   branch → default), Reviewer sub-agent reviews it (`senior-review`, fresh context). If
+   the task touched UI, the **UI Designer** reviews as a distinct design + a11y lens too
+   — either lens rejecting routes back to the Implementer.
 8. **Merge gate** — never auto-merge. Surface the approved PR; the human merges (or
    authorizes you to). The task stays at `in-review` until merged.
 9. **Closeout** — `task-closeout`: confirm the merge via `gh`, offer durable discoveries
@@ -97,7 +103,7 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
    `harness/closeout-<id>` PR (`gh pr merge --auto`); park at `closeout-pending` if it
    needs approval. Then close the issue and delete the branch. Same as L1.
 
-## Discovery interrupts (decision #30)
+## Discovery interrupts
 
 At any step, a sub-agent that hits a T1–T6 case (contradiction, unspecified decision,
 scope drift, existing solution, infeasibility, playbook conflict) **pauses instead of

package/catalog/templates/claude-code/docs/playbooks/README.md.tpl

@@ -75,9 +75,7 @@ status: active
 - `keywords` (optional) — case-insensitive regexes (Oniguruma). **Prompts matching any regex suggest this playbook.**
 
 `applies_to` and `keywords` are independently optional: a playbook can be require-only,
-suggest-only, both, or neither. The full spec lives in
-[`catalog/playbook-format.md`](https://github.com/{{task_storage_repo}}/blob/main/catalog/playbook-format.md)
-(packaged with the vendor — referenced here for convenience).
+suggest-only, both, or neither.
 
 ## What belongs here (and what doesn't)
 

package/catalog/templates/claude-code/harness.config.yml.tpl

@@ -24,7 +24,7 @@ agents:
   - implementer
   - reviewer
   - architect      # always installed; invoked on-demand, outside the linear flow
-  # - ui-designer  # catalog slot, inactive by default (decision #11)
+  # - ui-designer  # catalog slot, inactive by default
 
 # Paths (relative; defaults shown — declare only overrides).
 paths:
@@ -57,3 +57,11 @@ rollback:
 # Uncomment to opt the team out:
 # telemetry:
 #   enabled: false
+
+# Design tokens (`design-tokens validate`). The anti-hardcode scan inspects a built-in
+# set of UI/style extensions (.css/.scss/.ts/.tsx/.vue/.svelte/.astro/.js/.mdx/.html/…).
+# Add extra suffixes here for a stack the built-ins don't cover — additive, never a
+# replacement. Default none.
+# design_tokens:
+#   scan_extensions:
+#     - .foo