@lemoncode/lemony 0.1.1-alpha.0 → 0.1.1-alpha.2

package/catalog/skills/grill-ui/SKILL.md

@@ -1,30 +1,49 @@
 ---
 name: grill-ui
-description: Design-direction interview for the UI Designer. Reuses the grill-with-docs engine (one question at a time, recommend-don't-impose, never auto-decide) with a DESIGN script — personas, aesthetic dials + tone preset, brand references, density, motion appetite, screens and flows — and produces the `ui-handoff.md` design contract (not a PRD). Inherits the task's PRD and consumes `docs/personas.md` if present. Use when a task touches UI and the design must be defined alongside the spec.
+description: Design-direction interview run by the Orchestrator. Reuses the grill-with-docs engine (one question at a time, recommend-don't-impose, never auto-decide) with a DESIGN script — personas, aesthetic dials + tone preset, brand references, density, motion appetite, screens and flows — and produces the `ui-handoff.md` design contract (not a PRD). Inherits the task's PRD and consumes `docs/personas.md` if present. Use when a task touches UI and the design must be defined alongside the spec.
 origin: vendor
 vendor_version: '{{vendor_version}}'
-invoked-by: [ui-designer]
+invoked-by: [orchestrator]
 attribution:
   - source: mattpocock/skills
     author: Matt Pocock
     url: https://github.com/mattpocock/skills
     license: MIT
+    copyright: Copyright (c) 2026 Matt Pocock
     relationship: derived-from
     note: grill interview engine — one question at a time, decision-by-decision interrogation
 ---
 
 # Grill UI
 
-The UI Designer's **DEFINE** method: a design-direction interview that turns a task into a
+The Orchestrator's **DEFINE** design method: a design-direction interview that turns a task into a
 `ui-handoff.md` design contract the implementer can build from. It is the design sibling of
-`grill-with-docs` — the same interrogation engine, a different script and a different output.
-
-## Core Principle
-
-You are a design director with taste. Push for **deliberate, distinctive** direction, not the
-generic defaults a model reaches for unprompted. Drill every design branch. Present concrete
-options with trade-offs — never just open questions. The goal is a design the user could not have
-articulated alone, captured as decisions the implementer can execute and the review can verify.
+`grill-with-docs` — the same interrogation engine, a different script and a different output. You
+run it yourself, on your human-facing surface, and you author the handoff it produces.
+
+## Identity & taste
+
+Run this interview as a **design director with real taste** — the kind a solo dev without a
+designer wishes they had on call. Hold a high bar and bring conviction:
+
+- **Default to deliberate, distinctive design.** The failure mode to avoid is generic "AI slop" —
+  the overused font, the predictable purple gradient, the cookie-cutter card grid, the layout with
+  no point of view. When the user has no opinion, propose a direction, don't reach for the safe
+  average.
+- **Have a point of view, hold it lightly.** Recommend boldly and explain _why_, then let the user
+  decide. It is their product; your job is to make the tasteful choice the obvious one, not to
+  impose it.
+- **Decisions, not know-how.** You set direction — tone, dials, layout, component and state
+  decisions, motion appetite, accessibility targets, microcopy. _How_ to apply tokens to a stack,
+  _how_ to avoid slop in code, _how_ to meet WCAG — that is the implementer's and reviewer's craft,
+  delivered through their skills. Never restate it.
+- **Ground taste in craft, not vibes.** Characterful typography, intentional colour driven by
+  semantic tokens, deliberate spacing and hierarchy, motion that carries meaning, accessible by
+  construction. Cite the reason a choice is good.
+
+Drill every design branch. Present concrete options with trade-offs — never just open questions.
+The goal is a design the user could not have articulated alone, captured as decisions the
+implementer can execute and the review can verify.
 
 ## Hard rules
 
@@ -42,18 +61,19 @@ articulated alone, captured as decisions the implementer can execute and the rev
 
 ## Inheritance — don't re-ask the need
 
-This interview runs **after** the general grill and the spec. Before the first question:
+This interview runs **after** the general grill and **before** the Spec Author writes the spec — so
+the design direction it settles can inform the spec. Before the first question:
 
-- **Read the task's PRD** (`docs/prds/<topic>-*.md`) and the spec
-  (`.claude/state/tasks/<id>/spec/requirements.md` / `design.md`). The _what_ and _why_ are already
-  settled — do NOT re-ask them. You are defining the _how it looks and feels_.
+- **Read the task's PRD** (`docs/prds/<topic>-*.md`). The _what_ and _why_ are already settled there
+  — do NOT re-ask them. You are defining the _how it looks and feels_. (The spec doesn't exist yet;
+  don't look for it.)
 - **Consume `docs/personas.md` if it exists** — the project's user models. Treat it as input; do not
   re-derive personas the file already states. **If it is absent, ask inline** (the persona branch
-  below) and capture the answer in the handoff's §1 — **never create `docs/personas.md`** here (it is
-  client-owned; the harness only consumes it). When you captured personas inline **because the file
-  was absent**, say so in your return so the Orchestrator can offer to persist them to
-  `docs/personas.md` for future tasks (see [Persisting personas](#persisting-personas-when-absent)).
-  The offer is the Orchestrator's — a human-facing surface — never yours mid-interview.
+  below) and capture the answer in the handoff's §1 — **don't write `docs/personas.md` mid-interview**
+  (it is client-owned; the harness only consumes it). When you captured personas inline **because the
+  file was absent**, offer at the end to persist them to `docs/personas.md` for future tasks (see
+  [Persisting personas](#persisting-personas-when-absent)) — an opt-in offer on your human-facing
+  surface, never an unasked write.
 - **Consume `docs/design-tokens.json` if it exists** — the single source of truth for tokens. The
   handoff §11 points at it; you never inline token values.
 - **Read `docs/architecture.md` if it exists** — orient against the system's shape so design
@@ -67,8 +87,8 @@ section of [ui-handoff-format.md](./ui-handoff-format.md).
 
 1. **Personas / who it serves** (→ §1). Consume `docs/personas.md` if present; else ask: who uses
    this, in what context, with what constraints (device, expertise, frequency)? Capture only what
-   shapes design decisions. If you asked inline because the file was absent, flag it in your return
-   so the Orchestrator can offer to persist them ([Persisting personas](#persisting-personas-when-absent)).
+   shapes design decisions. If you asked inline because the file was absent, offer to persist them at
+   the end ([Persisting personas](#persisting-personas-when-absent)).
 2. **Aesthetic direction** (→ §2). The heart of the interview. Start from an optional **tone
    preset** (`controlled` / `impact` / `innovative`) as shorthand that seeds defaults, then set the
    three explicit **dials** — **variance** (conventional ↔ expressive), **motion** (still ↔
@@ -91,7 +111,9 @@ section of [ui-handoff-format.md](./ui-handoff-format.md).
 10. **Microcopy** (→ §10). The actual words for the task's key labels/messages, **inline**. Voice
     follows §2; no separate copy artifact.
 11. **Tokens** (→ §11). Point at `docs/design-tokens.json`. If the project has no token file yet,
-    say so and capture it as an open question — never invent a token set.
+    don't invent one mid-interview — surface it at the end as an opt-in offer
+    ([Design-tokens & design-tool on-ramp](#design-tokens--design-tool-on-ramp-when-absent)); if the
+    human declines, capture it as an open question.
 
 After important branches, offer a checkpoint:
 
@@ -123,37 +145,77 @@ Spec Author's `requirements.md` / `design.md` / `tasks.md`. You **own** it. Use
 ## Persisting personas (when absent)
 
 `docs/personas.md` is **client-owned**: the harness consumes it, never imposes it. So when the
-file was **absent** and you gathered personas inline (§1 above), you do **not** write it
-yourself mid-interview — a sub-agent must not interrupt the human, and the choice to keep a
-persistent user-model doc is the human's.
-
-Instead:
-
-1. **Flag it in your return.** State plainly that `docs/personas.md` was absent and you captured
-   personas inline in the handoff's §1. That is the signal the Orchestrator needs.
-2. **The Orchestrator makes the offer** — on its own human-facing surface, after you return —
-   asking whether to persist those personas to `docs/personas.md` for future tasks.
-3. **You author it only if re-dispatched** with the human's yes. Write a **minimal
-   `docs/personas.md`** from the personas already captured in §1 — the client's own words, not an
-   invented cast. Keep it a skeleton the client can grow: one short block per persona (who they
-   are, their context/device, expertise, frequency, the goals and constraints that shape design).
-   Create `docs/` if absent. This is the client's real content, surfaced from their own answers —
-   never a vendor template, never personas the harness guessed.
-
-If the human declines, write nothing: the inline personas live on in the handoff's §1 for this
-task, and the next UI task will simply ask again.
+file was **absent** and you gathered personas inline (§1 above), don't write it mid-interview — the
+choice to keep a persistent user-model doc is the human's. Make it an explicit offer instead:
+
+1. **Offer at the end.** Once the design is defined, ask on your human-facing surface whether to
+   persist the inline personas to `docs/personas.md` for future tasks. Opt-in, never unasked.
+2. **On yes, write a minimal `docs/personas.md`** from the personas already captured in §1 — the
+   client's own words, not an invented cast. Keep it a skeleton the client can grow: one short block
+   per persona (who they are, their context/device, expertise, frequency, the goals and constraints
+   that shape design). Create `docs/` if absent. This is the client's real content, surfaced from
+   their own answers — never a vendor template, never personas the harness guessed.
+3. **On no, write nothing:** the inline personas live on in the handoff's §1 for this task, and the
+   next UI task will simply ask again.
+
+## Design-tokens & design-tool on-ramp (when absent)
+
+`docs/design-tokens.json` and a design-tool connection are **client-owned inputs** — the harness
+consumes them if present and otherwise leaves them alone, the same regime as personas. For a repo
+adopting the harness fresh, that silence is a dead end: no tokens, no way in. So when either is
+**absent**, don't dead-end at a silent open question — make an explicit, opt-in offer at the end, on
+your human-facing surface. Never scaffold or connect unasked.
+
+### Tokens absent → offer to scaffold
+
+When the project has **no `docs/design-tokens.json`**, offer once, after the design is defined:
+
+1. **Offer at the end.** Ask whether to scaffold a starter `docs/design-tokens.json` from the
+   direction just defined, or keep it as an open question in §11.
+2. **On yes, derive from the answers.** Build a minimal 3-tier DTCG file (`primitive` → `semantic`
+   → `component`) from what the human actually stated — the colours, type, spacing and radii that
+   came out of the aesthetic-direction branch (§2) and the components branch (§5). This is the
+   client's own direction, surfaced as tokens — **never a vendor template**, never a palette the
+   harness guessed.
+3. **Offer to cover the gaps too.** The interview rarely names every token. Ask a follow-up: for the
+   aspects the conversation **did not cover**, do they want a sensible **starter** set generated (a
+   neutral scale, default spacing and radii) so the file is usable from day one, or only the tokens
+   the answers implied? Opt-in — the human chooses how far to go, and you never pad the file unasked.
+4. **Validate before closing.** After writing, run `lemony design-tokens validate` and fix anything
+   it flags, so the scaffolded file is well-formed (3-tier, aliases resolve) — a scaffold that fails
+   the validator is worse than none.
+5. **On no, write nothing:** capture the missing token file as an open question in §11, exactly as
+   before. The next UI task simply asks again.
+
+### No design tool → offer to connect
+
+When `docs/design-tokens.json` carries no `com.lemony.design-tool` binding — or there is no tokens
+file at all — offer to **connect a design tool** (e.g. a Figma or Pencil bridge) so tokens can
+round-trip between the repo and the tool:
+
+1. **Offer, opt-in.** Ask whether to connect a design tool now, or **stay pure-code** (tokens live
+   only in the repo). Most repos are happy pure-code — recommend that unless the human wants a
+   visual tool in the loop.
+2. **On yes,** write the `com.lemony.design-tool` binding (the provider) into `docs/design-tokens.json`
+   and run the first import to bootstrap tokens from the tool. The `design-tool-sync` skill and the
+   `sync-design-tokens` command own the mechanics — you point the human at them; you don't
+   re-implement the bridge here.
+3. **Skip gracefully.** If the tool's MCP bridge isn't connected, say so and fall back to the open
+   question — never block the interview on an unavailable tool.
+4. **On no, stay pure-code:** write no binding. The design tool is only ever a projection of
+   `docs/design-tokens.json`, never a peer source of truth — declining costs nothing.
 
 ## Pause & Resume
 
 Design definition is part of completing the spec, not a separate state. Pausing and resuming use
-the lifecycle the Orchestrator already owns — don't invent a parallel mechanism:
+the lifecycle you already own — don't invent a parallel mechanism:
 
-- **Pausing**: write `ui-handoff.md` with `Status: in_progress` and the sections closed so far. The
-  Orchestrator records the sub-state `awaiting design definition` in the task's `progress.md` and
-  parks the task. Confirm with the user before ending the turn.
+- **Pausing**: write `ui-handoff.md` with `Status: in_progress` and the sections closed so far,
+  record the sub-state `awaiting design definition` in the task's `progress.md`, and park the task.
+  Confirm with the user before ending the turn.
 - **Resuming**: `/resume <id>` re-enters via that sub-state. Read the in-progress `ui-handoff.md`,
   confirm which sections are closed and which branch comes next, then continue.
-- **Completing**: flip `Status: in_progress` → `Status: completed`. The Orchestrator removes the
+- **Completing**: flip `Status: in_progress` → `Status: completed`, then remove the
   `harness:needs-design` flag at/before `spec-ready`.
 
 ## Tone
@@ -165,9 +227,9 @@ and conviction — push for a real direction, but the user decides.
 ## When the design is underspecified
 
 If a design decision needs input the PRD left open with more than one valid answer and the user
-can't resolve it in the interview, **raise it as a discovery** rather than guess — the Orchestrator
-mediates and re-invokes you with the decision. For an independent defect unrelated to the design,
-note it as a side finding and keep going.
+can't resolve it in the interview, **capture it as an open question** in the handoff rather than
+guess, and mark the handoff `Status: in_progress` until it is settled — never close a design on a
+guessed fork.
 
 ## Cross-references
 

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

@@ -1,7 +1,7 @@
 # `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.
+The artifact the Orchestrator authors at DEFINE (via the `grill-ui` interview) 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 Orchestrator; the UI Designer critiques it at DEFINE and reviews the built UI against it at REVIEW.
 
 **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
@@ -28,9 +28,9 @@ Every section is **N/A-able** per task: mark a section N/A rather than padding i
 
 **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.
+> Owned by the Orchestrator (authored via `grill-ui`). 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
 
@@ -86,9 +86,10 @@ Every section is **N/A-able** per task: mark a section N/A rather than padding i
 
 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.
+the file.** If the project has no token file yet, the interview offers to scaffold one (derived from
+the answers) or to connect a design tool; if the human declines both, say so and capture it as an
+open question — never invent a token set silently. `lemony design-tokens validate` flags raw
+colours/dimensions in source that should reference a token.
 
 ## Open questions
 

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

@@ -9,6 +9,7 @@ attribution:
     author: Matt Pocock
     url: https://github.com/mattpocock/skills
     license: MIT
+    copyright: Copyright (c) 2026 Matt Pocock
     relationship: derived-from
     note: grill workflow and decision-by-decision interview structure
 ---

package/catalog/skills/tdd/SKILL.md

@@ -5,6 +5,14 @@ origin: vendor
 vendor_version: '{{vendor_version}}'
 phase: during-implementation
 invoked-by: [implementer]
+attribution:
+  - source: mattpocock/skills
+    author: Matt Pocock
+    url: https://github.com/mattpocock/skills
+    license: MIT
+    copyright: Copyright (c) 2026 Matt Pocock
+    relationship: derived-from
+    note: the red-green cycle, the behavior-over-implementation core principle, the vertical-slice ("tracer bullet") framing, mock-at-system-boundaries guidance, and the ADR three-tests nudge
 ---
 
 # Test-Driven Development

package/catalog/skills/write-adr/SKILL.md

@@ -5,6 +5,14 @@ origin: vendor
 vendor_version: '{{vendor_version}}'
 invoked-by: [architect]
 trigger-condition: a resolved decision is worth recording (a discovery resolution, or an explicit request)
+attribution:
+  - source: mattpocock/skills
+    author: Matt Pocock
+    url: https://github.com/mattpocock/skills
+    license: MIT
+    copyright: Copyright (c) 2026 Matt Pocock
+    relationship: derived-from
+    note: ADR format — the three-tests rubric (hard to reverse / surprising / real trade-off), the record template, and the "what qualifies" guidance
 ---
 
 # Write ADR

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

@@ -57,30 +57,33 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
    `harness:sdd` + `harness:status:spec-in-progress`) and the branch
    `harness/<id>-<slug>`. `<id>` is the GitHub issue number in this build; spec and code
    both live on that branch — nothing touches the default branch until the merge gate.
-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).
-   **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
+3. **UI design (if it touches UI)** — **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" **run `grill-ui` yourself** (the interactive design
+   interview) to author `ui-handoff.md` under `tasks/<id>/spec/`, then dispatch the **UI
+   Designer** to **critique** it — resolve its findings before the Spec Author runs.
+4. **Spec** — Spec Author sub-agent (given the `<id>` + branch, and the `ui-handoff.md` if
+   one was authored): `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).
+5. **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
+6. **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,
    is the source of intent — never self-approve.
-6. **Implement** — Implementer sub-agent, `tdd` skill, on the branch, keeping
+7. **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`,
+8. **Review** — flip to `harness:status:in-review`, open the PR (`gh pr create`,
    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
+9. **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
+10. **Closeout** — `task-closeout`: confirm the merge via `gh`, offer durable discoveries
    to the Architect (`write-adr`, HITL), archive the spec + discoveries to `_archive/<id>/` (drop
    `progress.md`), and land `history.md` + the archival via a dedicated
    `harness/closeout-<id>` PR (`gh pr merge --auto`) — never a direct push to the base.

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

@@ -17,20 +17,8 @@ task_storage:
   type: github
   repo: {{task_storage_repo}}
 
-# Active agents (one `.claude/agents/<role>.md` per entry).
-agents:
-  - orchestrator
-  - spec-author
-  - implementer
-  - reviewer
-  - architect      # always installed; invoked on-demand, outside the linear flow
-  # - ui-designer  # catalog slot, inactive by default
-
 # Paths (relative; defaults shown — declare only overrides).
 paths:
-  state: .claude/state
-  skills: .claude/skills
-  agents: .claude/agents
   # Project-local playbooks (how-to-build patterns). Looked up by convention
   # `<topic>.md`, local then global; the local entry overrides the global one.
   # The require/suggest hooks read these two keys directly on every fire, so a