A1: Set up design library for this repo

.agents/docs/card-context.md

@@ -0,0 +1,28 @@
+---
+workhorse-version: 0.1.0
+---
+
+# Establishing card context outside Workhorse
+
+Skills are discovered natively by Claude Code, so they can be invoked in an external tool with no Workhorse session around them. Inside Workhorse the system prompt injects the card's context — its title, identifier, and description. Outside it, that context is absent, and a skill that needs to know which card it is working on has to establish that context before doing its work.
+
+Follow this process whenever a skill directs you here.
+
+## When this applies
+
+- Apply it only when you do **not** already have the card's context — no title, identifier, or description available to you. This is the case when you are running outside Workhorse
+- Inside Workhorse the card's context is always present, so this process never runs there
+- If you already established the card's context earlier in this conversation, reuse it — do not ask again
+
+## Establishing context
+
+When you have no card context, ask the user to establish it before you start the skill's work. Offer two paths:
+
+1. **Linear card** — the user gives you a Linear card code and connects the Linear MCP, so you can read the card directly. Read whatever detail helps the task at hand — at minimum the card's title and description. If the Linear MCP is not connected, walk the user through connecting it
+2. **Paste** — the user pastes the card's title and description directly into the chat
+
+Also ask the user for the card's **identifier**. It is used for the file paths of mockups (`.workhorse/design/mockups/{card-id}/`), plans (`.workhorse/plans/{card-id}/`), and test cases (`.workhorse/test-cases/{card-id}/`). Every card has one — a Linear card code supplies it directly. If no Linear or Workhorse ticket backs the work, ask the user to create one so the work is tracked; you can offer to create it for them through the Linear MCP.
+
+## When context is incomplete
+
+If the user cannot or will not supply full context, do the best you can with what is available — ask them for whatever detail they can provide to work from, and proceed on that. Don't block on missing context you can reasonably work around.

.agents/docs/spec-format.md

@@ -0,0 +1,112 @@
+---
+workhorse-version: 0.1.0
+---
+
+# Spec format and information architecture
+
+Specs are the product-level source of truth for a workspace. The format serves three audiences: product owners and testers authoring them (via interview or direct edit), developers and AI agents implementing from them, and anyone browsing them as a knowledge base.
+
+## Information hierarchy
+
+Specs live in `.workhorse/specs/` as markdown files organised into directories. The directory structure is the hierarchy: **Product > Area > Subarea > ... > Spec**, with arbitrary nesting depth.
+
+```
+.workhorse/specs/
+├── patient/
+│   ├── registration.md
+│   ├── allergies.md
+│   ├── merge/
+│   │   ├── overview.md
+│   │   ├── field-resolution.md
+│   │   └── conflict-handling.md
+│   └── referrals.md
+├── scheduling/
+│   ├── appointments.md
+│   └── recurring-appointments.md
+└── labs/
+    ├── requests.md
+    └── results.md
+```
+
+Areas appear as they're needed — there's no predefined list. When drafting a new spec, the agent picks an area consistent with the existing structure. The spec explorer reads this structure from the main branch to build the navigable reference view.
+
+## File format
+
+Each spec is a markdown file with a single-line YAML frontmatter block and a structured body:
+
+```markdown
+---
+id: ALG
+---
+
+# Patient allergies
+
+Summary paragraph describing what this spec covers.
+
+## Section heading
+
+- [ ] Acceptance criterion one
+- [ ] Acceptance criterion two
+```
+
+The frontmatter carries exactly one field:
+
+- `id` — a short, stable identifier for the spec, used for code-to-spec traceability (see [Spec IDs and code references](#spec-ids-and-code-references))
+
+Nothing else goes in the frontmatter. The title comes from the H1. The area comes from the directory. The originating card isn't recorded on the spec — it's available via git history and doesn't stay tied to the spec after the card closes.
+
+Body structure:
+
+- **Title** — a single `#` H1 at the top, human-readable (e.g. "Patient allergies")
+- **Summary** — one or two plain paragraphs below the title, no heading
+- **Sections** — `##` headings group related criteria
+- **Acceptance criteria** — markdown checkbox items (`- [ ]`)
+
+## Spec IDs and code references
+
+The `id` in frontmatter is a short, stable handle. It lets code reference the spec it implements through inline comments, and survives the spec being renamed or moved.
+
+- IDs are 2–6 character alphanumeric codes, uppercase, chosen when the spec is first created (e.g. `ALG`, `AUTH`, `LAB1`). Use something memorable rather than sequential numbering
+- IDs are unique within a workspace. Workhorse checks for collisions on creation
+- Once assigned, an ID never changes. The filename or location can change freely — code references keep working
+- Code references an implementing spec with an inline comment of the form `// spec: ALG`. For a specific section within the spec, append a kebab-case slug of the heading text: `// spec: ALG#conflict-handling`
+- A single piece of code can reference multiple specs with multiple comments — don't try to combine them
+
+Code references are advisory, not load-bearing. They help a reader jump from an implementation detail to the product rule it answers to. Missing references are not a bug.
+
+## Writing conventions
+
+- **Describe the system as it should be, not the changes to make.** Each spec is a coherent snapshot — it reads as "this is how the system works" rather than "change X to Y" or "no longer does Z". No references to "current behaviour", "remains unchanged", "now does", or "rather than the old way". The implementation agent works from the diff to know what's changing.
+- **Acceptance criteria are facts about behaviour, not instructions to a developer.**
+- **Grade implementation detail by whether it constrains behaviour that must be preserved.** Product-owner-level language is the default: write "the system checks whether all parent cards have been committed" rather than naming the field that tracks commit state, and "Spec complete" rather than an all-caps status constant. But a technical choice belongs in the spec when the choice *is* the requirement — when a reimplementation should be held to it rather than free to pick its own approach. The decision test is: **"Would someone reimplementing this from scratch need to be constrained back to this technical choice?"** If yes, name the detail; the spec is where that constraint is recorded. If no, describe the behaviour and let the implementation choose its tools.
+  - **Keep the detail** when it is load-bearing. A sync engine that heals divergence by replaying from a known-good checkpoint must preserve that mechanism, so the spec names it — a different healing strategy would be a different product. Backend and platform specs often carry this kind of detail: data-integrity rules, concurrency and ordering guarantees, wire and storage formats, migration and healing strategies.
+  - **Leave it out** when the detail is one acceptable way among several to build the same behaviour. Choosing React hooks to manage state in a frontend workflow is an implementation choice — the user-visible behaviour is the requirement, so specify that and let the build pick its tools. Product-facing, CRUD, and frontend specs stay behavioural.
+  - File paths inside `.workhorse/specs/` are always acceptable because they're part of the product's information architecture.
+- **Stay within the spec's scope.** Each spec contains only sections that relate directly to its title and area. If content would make more sense in another spec, it belongs there — add a cross-reference (e.g. "see `editor/spec-editor.md`") rather than duplicating or misplacing it. When in doubt, ask: "would someone looking for this information expect to find it in a spec with this title?"
+- **Don't specify absences.** Document what the system does, not what it doesn't do. "We don't support X" or "X is not included" is not useful — if it's not in the spec, it's not in the system. If another spec needs updating because this feature changes its behaviour, update that spec declaratively.
+- **No point-in-time language.** Don't document transitions ("we used to do X, now we do Y", "this replaces Z"). Each spec is a snapshot of the desired system, not a changelog.
+- **No stacking adjectives.** Don't describe behaviour with chains of near-synonyms ("seamless, invisible, frictionless"). Use one precise word or describe the concrete behaviour.
+- **No exact measurements in prose.** Pixel widths, animation durations, and precise benchmarks belong in mockups or the design system, not in acceptance criteria. Describe the intent ("compact", "fast enough to feel instant") rather than the number.
+- **Open questions must be resolved before a spec is considered done.** A spec with open questions is a draft. Nail them down with the user before committing.
+- **Australian/NZ English spelling** (colour, organisation, finalise).
+
+## When a change warrants a spec update
+
+Specs describe product behaviour, so spec edits accompany changes that change product behaviour.
+
+- Product-behaviour changes — new features, removed behaviour, changed flows, revised edge-case handling — require spec edits
+- Bug fixes and implementation-detail changes do not require spec edits, unless the bug existed because the spec was unclear, incorrect, or missing. In that case, update the spec first so it reflects the intended behaviour, then fix the code to match
+- Refactors and cleanups that leave product behaviour unchanged do not touch specs
+
+## When to edit, fold, create, or split
+
+Default to editing the spec that already covers the concept. A new spec file appears only when the content cannot plausibly live as a section or set of criteria inside any existing spec in the same area.
+
+- **Fold into an existing spec** when the change is a section, criterion, or refinement on a concept the spec already covers. Most spec changes are folds
+- **Create a new sibling spec** when the content is a distinct concept within an existing area but does not belong in any current file there
+- **Split an existing spec** when it has grown long **and** contains one or more conceptually distinct sub-areas that could each stand alone
+
+When splitting, the parent topic becomes a folder and the sub-topics become files within it:
+
+- Add an `overview.md` when the folder has cross-cutting content (shared terminology, relationships between sub-specs, invariants that apply to all children), or when the folder has more than three siblings and a reader needs orientation
+- Skip `overview.md` when two or three well-named siblings speak for themselves

.agents/docs/working-doc-format.md

@@ -0,0 +1,36 @@
+# Working doc format
+
+A working doc is a per-card drafting space where spec-level and implementation thinking co-exist before the card is split into its long-lived artefacts (specs, plan, test cases). This doc defines its shape and voice. The artefact itself is specified in `.workhorse/specs/working-doc/overview.md`.
+
+## When to use one
+
+A working doc suits larger, epic-level cards where the shape of the work is still being found and behaviour and implementation need developing side by side. Most cards don't need one — for those, interview straight into specs and let Tech design write to the plan as usual.
+
+## Voice
+
+Unlike a spec, a working doc is written in working voice:
+
+- Open questions are welcome — track them explicitly as you go
+- Point-in-time reasoning is welcome ("we considered X but…")
+- Implementation detail, options, and trade-offs sit alongside behaviour
+- Nothing here has to be a clean declarative snapshot; that transformation happens at the split
+
+## Conventional shape
+
+The file starts minimal — frontmatter (`status: draft`), an H1 title, an overview line. Build the body up under these conventional sections as material accrues. Use only the sections a card needs, and add others when they help.
+
+- **Behaviour** — what the system should do, at spec level: happy paths, edge cases, interactions. This is the material the split rewrites into specs
+- **Implementation options** — approaches under consideration, with their shape and cost
+- **Open questions** — unresolved decisions, tracked as a checklist so they're easy to see and close off
+- **Trade-offs** — the reasoning behind choices, including rejected options and why
+- **Testing notes** — scenarios worth verifying, which the split lifts into test cases
+
+## Splitting
+
+When the shape is clear, Split working doc fans the material out:
+
+- Behaviour → the card's specs, rewritten into declarative spec voice per `.agents/docs/spec-format.md`
+- Implementation options and trade-offs → the plan
+- Testing notes → the test cases
+
+Resolve open questions before splitting where you can — specs can't carry them. Split working doc warns before proceeding if any remain, and reminds you which still need follow-up afterwards.

.agents/skills/acceptance-audit/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: acceptance-audit
+description: "Check whether this card's code meets the acceptance criteria"
+label: "Acceptance audit"
+pill-order:
+  implementing: 4
+  reviewing: 4
+  complete: 3
+workhorse-version: 0.1.0
+---
+
+## Your task: Acceptance audit
+
+Check whether the code on this card's branch meets the acceptance criteria. This is a compliance check against the specs, not a general code-quality review.
+
+1. Identify what this card was supposed to do: diff the spec changes on this branch against the upstream base (scoped to `.workhorse/specs/`) to see the card's own additions and edits. Also read the surrounding specs in the same area(s) — they describe existing behaviour that must still be met and not regressed
+2. Diff this card's branch against its upstream base to see the implementation (a card's base is usually `main`, but may be a parent card's branch)
+3. Walk the criteria one by one — both the card's new/changed criteria and the surrounding ones that should still hold. Does the code deliver each one? Has any existing behaviour regressed?
+4. Flag criteria that are not yet implemented, partially implemented, or implemented incorrectly — and flag regressions separately
+5. Flag any behaviour in the code that isn't covered by a criterion — that's either missing from the spec, or shouldn't be in the code
+
+Post findings grouped by spec, each finding tied to a specific criterion with file and line references.

.agents/skills/ascii-design/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ascii-design
+description: "Run a quick UX/UI workshop using ASCII-art sketches"
+label: "ASCII design chat"
+pill-order:
+  not-started: 5
+  specifying: 11
+workhorse-version: 0.1.0
+---
+
+## Your task: ASCII design chat
+
+If you don't already have this card's context (title, identifier, description) — for instance when running outside Workhorse — establish it first by following `.agents/docs/card-context.md`.
+
+A lightweight UX/UI workshop. Sketch the screen's skeleton as ASCII art directly in chat, get feedback, and iterate. Keep it fast and rough — the goal is to agree on shape and hierarchy before committing to HTML mockups.
+
+Once the skeleton is agreed, suggest moving to an HTML mockup as the next step.

.agents/skills/automate-test-cases/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: automate-test-cases
+description: "Write automated tests for unticked scenarios in this card's test cases"
+label: "Automate test cases"
+pill-order:
+  implementing: 6
+  reviewing: 5
+jockey-hint: "Surface once the card has a test-cases file with unticked scenarios and implementation is underway. Demote once all scenarios are ticked."
+workhorse-version: 0.1.0
+---
+
+## Your task: Automate test cases
+
+If you don't already have this card's context (title, identifier, description) — for instance when running outside Workhorse — establish it first by following `.agents/docs/card-context.md`.
+
+Write automated tests that match the unticked scenarios in this card's test-cases file, ticking each item as its matching test lands.
+
+1. Read the test-cases file at `.workhorse/test-cases/{card-id}/`. If no file exists, stop and ask the user whether to run `Draft test cases` first
+2. For each unticked scenario, locate the right place to put its automated test — follow the target repo's existing test conventions (framework, file layout, fixtures)
+3. Write the test so it exercises the scenario as stated. If the scenario cites a spec id, the test is the automation of that acceptance criterion — match its intent
+4. Tick the scenario (`- [ ]` → `- [x]`) once its test is written and passing locally. Update the test-cases file in place
+5. If a scenario is genuinely not automatable (manual feel, cross-browser visual), leave it unticked and note in the file why it's manual-only
+6. Summarise what you automated, which scenarios remain manual, and any scenarios you couldn't make sense of
+
+See `.workhorse/specs/test-cases/overview.md` for the file's shape.

.agents/skills/bug-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: bug-review
+description: "Review code changes on this card for likely bugs, regressions, and missed edges"
+label: "Bug review"
+pill-order:
+  implementing: 2
+  reviewing: 1
+  complete: 1
+workhorse-version: 0.1.0
+---
+
+## Your task: Bug review
+
+Review the code changes on this card's branch for likely bugs, regressions, and missed edges.
+
+1. Diff this card's branch against its upstream base to see what's changed (a card's base is usually `main`, but may be a parent card's branch)
+2. Read the specs to understand the intended behaviour
+3. Inspect the diff for anything that looks wrong — use your judgement about what matters for this code
+4. Post findings grouped by severity: real bugs first, then smells or likely issues, then nitpicks
+5. For each finding, reference the file and a short excerpt so the user can locate it
+
+Be specific and actionable. Don't flag stylistic preferences as bugs.

.agents/skills/cherry-pick-changes/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cherry-pick-changes
+description: "Cherry-pick post-merge commits onto a new follow-up branch"
+label: "Cherry-pick changes"
+workhorse-version: 0.1.0
+---
+
+## Your task: Cherry-pick post-merge changes
+
+The card just created a follow-up PR on a fresh branch from main. Your job is to cherry-pick the post-merge commits from the previous branch onto this new branch.
+
+The user message contains the previous branch name and the commit SHAs to cherry-pick.
+
+1. Cherry-pick each commit in order using `git cherry-pick <sha>`
+2. If a cherry-pick applies cleanly, move to the next one
+3. If a cherry-pick encounters conflicts:
+   - Examine the conflict markers to understand what diverged
+   - Use the card's specs, description, and conversation history to make informed resolution decisions
+   - Edit the conflicted files to resolve them
+   - `git add` the resolved files
+   - `git cherry-pick --continue` to proceed
+4. After all commits are applied, push the branch with `git push origin <branch>`
+5. Report what you cherry-picked, any conflicts you encountered, and how you resolved them