@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.21

package/content/skills/timetrack/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: timetrack
+description: How to reach Jira from any repo through the running Timetrack app - look up an issue, search for one, ask which project a repo logs into, file a ticket, add a worklog row, read the user's own Tempo worklogs, read their Google Calendar, read the evidence a day holds, or list the work that still waits for a ticket. Read whenever a task needs Jira data, a Jira write, or the day's own events, and never put a Jira token in a repo.
+kind: skill
+scope: both
+---
+
+# Reaching Jira through Timetrack
+
+**No repository holds a Jira token.** The Timetrack desktop app holds one set of credentials
+in this machine's keychain, and every repository asks it:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack status                 # is the app reachable, and what does it hold?
+{%packageRunner%} ethlete-agents timetrack issue FIP-2177         # one issue: summary, type, parent, subject
+{%packageRunner%} ethlete-agents timetrack search "password"      # open issues of the picked projects
+{%packageRunner%} ethlete-agents timetrack project                # which project does this repo log into?
+{%packageRunner%} ethlete-agents timetrack instance               # the instance's own levels and custom fields
+{%packageRunner%} ethlete-agents timetrack standins               # work the user named that Jira does not hold yet
+```
+
+Add `--json` to any of them when you need to read a field rather than a line.
+
+**Every write waits for the user's approval in the app.** `create`, `log`, `edit`, `standins
+--remove | --rename | --merge | --resolve | --split --force`, `sync --write`, `worklog --delete` and `resync` answer at
+once with an approval id and write nothing yet. The user approves or rejects the request in
+Timetrack; `approval <id>` reads the outcome:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack approval <id>          # queued, approved (with the result), rejected or expired
+{%packageRunner%} ethlete-agents timetrack approvals              # every write that waits now: id, asker, op, asked at, what it writes
+{%packageRunner%} ethlete-agents timetrack approval <id> --reject # reject one that waits, as the app's Reject button does
+```
+
+A reject answers at once and writes nothing to Jira or Tempo; an item that no longer waits is
+refused and stays as it is. Reject only what the user asked you to, or a write you queued by
+mistake. **There is no approve command and never will be: only the user approves, in the app.**
+
+`ask` does what the app's "Ask auto mode again" does, on any day, without moving the day on
+screen. It answers at once with what it queued; the model runs on the user's machine, and its new
+answer replaces the stored one. It writes nothing to Jira or Tempo itself: a ticket or a name the
+answer proposes waits for the user's approval as auto mode's own does.
+
+```bash
+{%packageRunner%} ethlete-agents timetrack ask --stand-in <id> [--day YYYY-MM-DD]       # an open stand-in, ids from `standins`
+{%packageRunner%} ethlete-agents timetrack ask --context <context-id> [--day YYYY-MM-DD] # an unnamed band, ids from `rows`
+```
+
+A subject the app does not offer the press on is refused: an unknown or resolved stand-in, one
+the day holds no time of, a context a rule names or the user named by hand.
+
+Tell the user a request waits in Timetrack, then read `approval` once they say they decided -
+do not poll in a loop. A request that is still waiting at the end of the day it was asked on
+expires; ask again rather than assuming it landed. Set `TIMETRACK_CLIENT` to name yourself in the
+queue (Claude Code is named without it).
+
+**Never ask the user for a Jira token, and never write one into a file.** If a command reports
+that the app is not running, say so and ask the user to start it. That is the whole fix -
+there is no per-repo fallback, by design: a secret copied into every checkout is a secret
+nobody can rotate.
+
+## What each command is for
+
+| Command                                    | Use it when                                                                 |
+| ------------------------------------------ | --------------------------------------------------------------------------- |
+| `status`                                   | Before anything else, when a Jira command failed and you need the cause     |
+| `instance`                                 | A setup step needs the instance's levels or its branch-subject field        |
+| `issue <KEY>`                              | The user names a key and you need its summary, type or parent               |
+| `search [text]`                            | The user describes work but names no key                                    |
+| `project [path]`                           | You need the project a repository files into                                |
+| `create --summary "…"`                     | The work has no ticket and the user asked for one                           |
+| `log --issue <KEY> --minutes <n>`          | The user asks to record time that nothing observed                          |
+| `day [YYYY-MM-DD]`                         | You need the evidence a day holds, not a screenshot of it                   |
+| `rows [YYYY-MM-DD]`                        | You need the rows the day drew, and the ids an edit names them by           |
+| `edit <row-id> …`                          | The user asks you to correct one row of a day                               |
+| `rules`                                    | You need to know why a band was named, or why it was not                    |
+| `standins`                                 | You need to know which work still waits for a ticket, and for how long      |
+| `standins --remove <id>`                   | A placeholder is wrong or too wide, and the user asked you to delete it     |
+| `standins --rename <id> --name <text>`     | The name a placeholder carries is wrong, and the user asked you to fix it   |
+| `standins --merge <id> --into <id>`        | Two placeholders are one piece of work, and the user asked you to join them |
+| `standins --resolve <id> --issue <KEY>`    | The user named the issue a placeholder is, or the one a resolved one is now |
+| `naming [YYYY-MM-DD]`                      | A checkout was never offered a name and you need the step that stopped      |
+| `worklogs [from] [to]`                     | You need what the user already booked in Tempo over a span of days          |
+| `calendar [from] [to]`                     | You need the user's meetings and calendar entries over a span of days       |
+| `sync <YYYY-MM-DD>`                        | The user asks what a Tempo sync of a day would write, or asks to sync it    |
+| `worklog --delete <id> --day <YYYY-MM-DD>` | The user asked you to delete one of their own Tempo worklogs                |
+| `approval <id>`                            | A write you queued: whether the user approved it, and what it answered      |
+| `approvals`                                | You need what waits in the queue, from every caller                         |
+| `approval <id> --reject`                   | The user asked you to drop a waiting write, or you queued one by mistake    |
+| `ask --stand-in <id>` / `--context <id>`   | The user asks auto mode to look at a stand-in or an unnamed band again      |
+
+`git-flow start` uses the same channel, so a branch is named from the real issue rather than
+from a key you typed. Follow the repository's branch workflow when creating a branch.
+
+## Reading a day
+
+The app's store is encrypted, so no shell reads a day off disk. `day` is the only way in:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack day                       # today: how many events, and of which kind
+{%packageRunner%} ethlete-agents timetrack day 2026-09-10 --out /tmp/day.json
+```
+
+A real day holds thousands of events, so **never print them**. Write them to a file with
+`--out`, then read that file from a test or a script. Without `--out` the command reports
+only the counts, which is what tells you whether a day holds the source you are looking for.
+
+`--out` writes a new file, readable by its owner alone. A destination that already exists is
+refused until you pass `--overwrite`, and a symlink is never written through. The file holds the
+day as it was observed - window titles, paths and messages - so delete it when you are done.
+
+`transcript` prints what the app transcribed of the user's own microphone during the day's calls,
+one 30-second chunk per line. It exists only where the user turned call transcription on, and the
+app deletes a chunk after seven days. Read it only when the task needs what was said.
+
+```bash
+npx ethlete-agents timetrack transcript [YYYY-MM-DD]
+```
+
+## Reading and correcting the rows a day drew
+
+`day` answers what the collectors saw. `rows` answers what the app made of it - the bands on the
+timeline, with the id every edit names a row by, the day's totals and its warnings.
+
+```bash
+{%packageRunner%} ethlete-agents timetrack rows                      # today
+{%packageRunner%} ethlete-agents timetrack rows 2026-09-10 --json
+```
+
+`edit` changes one row. Pass exactly one change per call:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack edit 'ABC-1@2026-09-10T11:00:00.000Z' --day 2026-09-10 \
+  --from 2026-09-10T13:15:00Z --to 2026-09-10T17:00:00Z
+{%packageRunner%} ethlete-agents timetrack edit '<row-id>' --issue ABC-2
+{%packageRunner%} ethlete-agents timetrack edit '<row-id>' --state rejected
+```
+
+`rows` moves the app's own review to that day, so the user sees what you read. An edit is queued
+like every write; once approved, its result's `applied` says how many edits found their row. A
+running day is re-cut on every collector tick, so read `rows` again rather than reusing an id from
+minutes ago.
+
+An edit may correct a row's times, its name, its note and whether it syncs. It may not split, merge
+or delete one - restructuring a day is the user's own decision, made on the screen.
+
+## Why a band carries the name it does
+
+`rules` reads the settings that name a day's work - the attribution rules, the project links,
+the background projects and the applications the user has ruled in or out. It holds no host, no
+account and no token, so it is safe to quote back to the user.
+
+```bash
+{%packageRunner%} ethlete-agents timetrack rules            # a summary of the rules
+{%packageRunner%} ethlete-agents timetrack rules --json     # the whole answer
+```
+
+Read it before claiming a band should have been named something: a rule that donates its time
+carries no issue key, and a project in `backgroundProjects` keeps only the minutes no other
+band claims.
+
+## Work with no ticket yet
+
+A **stand-in** is a name the user gave work that Jira does not hold yet. It takes bands across
+days and across checkouts, and it books nothing. `standins` lists them:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack standins         # the open ones, oldest first
+{%packageRunner%} ethlete-agents timetrack standins --json  # the whole answer, resolved ones included
+```
+
+**Never open or resolve a stand-in.** The name is the user's own word for their work, and the
+app is the only place they give it. If the user asks for a ticket, use `create` and tell them
+to resolve the stand-in in Timetrack.
+
+A placeholder is drawn per branch, and per directory where the branch names no piece of work.
+A base branch, or no branch at all, says nothing about what was worked on, so the directory the
+commits touched answers instead. That directory is the project the repository declares - the one
+carrying the `project.json` or `package.json` above the changed files. A repository that declares
+none lets its own commits pick the grain between them. A directory named with a leading dot is
+the checkout's own tooling, so it never answers: a commit in `.changeset` or `.github` is
+bookkeeping for another piece of work.
+
+Where the directories cannot answer either, the branch the checkout was next cut onto does. A
+branch is very often cut once the work on it has started, so the minutes before the cut sit on
+the base branch although they are that branch's work.
+
+One placeholder written before any of that was true covers a whole checkout, and it blocks a
+per-branch placeholder for every branch of it. The list says so:
+
+```
+Competition journey spec frontend in FIFAGG  3d old, 3 day(s) of work
+  covers all of /home/tom/dev/fifagg/specs, so no branch of it gets one of its own
+```
+
+Two separate things cause that, and either alone is enough: the record names no branch, or the
+rule naming it names no branch. The line above reports both, so take it at its word rather than
+reading `--json` yourself.
+
+### Give one another name
+
+The name is only wrong, and the work behind it is right:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack standins --rename <id> --name '20260921 competition navigation rework'
+```
+
+The days it holds and the rules that name it stay, which is what a delete and a fresh record would
+lose. Rename one only when the user asks. The name is their own word for their work, so a name you
+find unclear is not a fault to correct.
+
+### Resolve one to its issue
+
+The user told you which Jira issue a placeholder is:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack standins --resolve <id> --issue <KEY>
+```
+
+It resolves the placeholder as the user's own pick in the app does, so every band on every day it
+held takes the key. One that is resolved already moves to the new key, as the app's Undo and a new
+pick would. It writes nothing to Tempo, so a day of it already booked keeps the old key there. The
+app reads the issue from Jira before it queues anything, so an unknown key or placeholder answers an
+error and nothing waits. A done issue is fine. The approval card shows the name, the old key and the
+new one with its summary.
+
+### Re-cut one that named two pieces of work
+
+A record covering a whole checkout is repaired rather than deleted, because a delete strands its
+days. `--split` re-cuts it into one record per directory, and moves each day onto the right one:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack standins --split <id>              # the plan, writes nothing
+{%packageRunner%} ethlete-agents timetrack standins --split <id> --force      # queue it for approval
+```
+
+Without `--force` it prints every directory the commits name, with its commit count and its days,
+then says which of them it would write. A directory under three commits is an edit made in
+passing rather than a piece of work, so it is listed but not written. Pass
+`--paths <dir>,<dir>` to pick the pieces yourself.
+
+The commits are read across every branch, and only the ones the checkout's own `user.email`
+authored. That is the history the collector that opened the record read, so work left on an
+unmerged branch still counts and a colleague's commits never shape a piece. `--author <email>`
+overrides the address.
+
+A day the record covers that holds no commit of yours goes back to unnamed, and the split names
+it. That is the honest answer: nothing says which directory it was. The day review is where it
+gets named, and `--claim <dir>` gives every such day to one directory instead.
+
+The record and its checkout-wide rule always go, even when a day is left unnamed. Both are read
+as covering every branch of the checkout, so keeping either would block any later branch from
+getting a record of its own — which is the fault the repair exists to cure.
+
+The record must name the checkout it was opened for. One the user opened by hand names none, and
+the split refuses it.
+
+You may delete one, because that takes a name away rather than putting one on the day:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack standins --remove <id>
+```
+
+The rule that named it goes with it, and what happens next is worth knowing before you ask:
+
+- The record names a branch. The delete refuses that branch, and no second one opens for it.
+- It names none. The delete refuses nothing, so the next pass opens one per branch instead.
+
+**Deleting one strands every day but today.** Only the day the app next reviews gets a new
+placeholder; every earlier day the record covered then reads as unnamed, with nothing left to
+say what it was. The command refuses such a delete and lists the days, and `--force` makes it
+anyway. Ask the user before you use `--force`, and tell them which days they will lose.
+
+## Why a checkout was never offered a name
+
+The day screen offers a whole checkout one issue when the user's own record already answers it. The
+card is either drawn or it is not, and every step that can stop it is invisible from the screen.
+`naming` names the step:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack naming              # today
+{%packageRunner%} ethlete-agents timetrack naming 2026-09-14
+```
+
+It reports whether a Tempo token is stored, how far the read of the worklog history got, and for each
+checkout the day saw either the offer or the reason there is none - `already-named`,
+`no-project-link`, `no-history`, `project-too-small`, `too-few-days` or `share-too-low`. A `history`
+of `failed` or `no-token` explains every checkout at once, so read that line first.
+
+## What Tempo already holds
+
+`worklogs` reads the user's own Tempo worklogs straight from Tempo, whoever wrote them. It is
+read-only, and the app keeps the Tempo token:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack worklogs                          # the last 7 days
+{%packageRunner%} ethlete-agents timetrack worklogs 2026-09-01 2026-09-24    # both days included
+{%packageRunner%} ethlete-agents timetrack worklogs 2026-09-01 2026-09-24 --json
+```
+
+Without `--json` it prints one line per booked day: the total, then minutes per issue. `--json`
+answers each worklog with its day, `startTime` as `HH:MM`, `durationMs`, `issueKey` and
+description. A span is at most 92 days. The descriptions are the user's own words, so quote them
+only when the task needs them.
+
+## What the calendar holds
+
+`calendar` reads the Google calendars the app watches, straight from Google and read-only. The app
+keeps the Google token:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack calendar                          # the last 7 days
+{%packageRunner%} ethlete-agents timetrack calendar 2026-09-01 2026-09-24    # both days included
+{%packageRunner%} ethlete-agents timetrack calendar 2026-09-01 2026-09-24 --json
+```
+
+Without `--json` it prints each day with its meeting hours, then one line per entry: start, minutes,
+title, and the user's answer where it is not a yes. All-day and declined entries are listed but not
+counted. `--json` answers each entry with `calendarId`, `day`, `startMs`, `endMs`, `allDay`, `title`,
+`attendeeCount` and `response`. A span is at most 92 days. Titles come from whoever sent the
+invitation, so quote them only when the task needs them.
+
+## Syncing a day to Tempo
+
+`sync` plans a day exactly as the app's Sync page does, and writes nothing:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack sync 2026-09-07
+{%packageRunner%} ethlete-agents timetrack sync 2026-09-07 --json
+```
+
+It prints every create, update and delete with its issue, local time, minutes, description and
+reason; the rows it holds back (Tempo refuses an empty description); how many are unchanged or still
+awaiting review; keys Jira does not know; and the foreign worklogs it never touches. The first line
+carries a short **plan hash** over the write set.
+
+Writing is a Tempo write, so it follows one rule without exception: **show the user the rows, and
+write only after they confirmed those rows in this conversation.** Then pass the hash the read
+printed:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack sync 2026-09-07 --write --plan 1a2b3c4d
+```
+
+The write is queued, and the user approves it in the app as well - "Approve all" never includes
+it. On approval the app plans the day again and refuses, writing nothing, when the hash differs -
+the day changed since the user saw it, so read it again and ask again. `--write` without `--plan`
+is refused at once. Once approved, `approval <id>` prints each row as `written`, `blocked`,
+`skipped` or `failed`, with the worklog id or the error, and exits non-zero while a row did not
+land. Never re-run the write to retry: a plan read
+straight after a write can miss what Tempo just took and log it twice. The Sync page shows the run
+and retries from its own plan. A "written, but not recorded" line means Tempo holds worklogs the
+app no longer owns; tell the user to delete them in Tempo before this day is written again.
+
+Both reads and writes move the app's Day screen to that day, as `rows` and `edit` do.
+
+## Deleting a Tempo worklog
+
+`worklog --delete` deletes one of the user's own Tempo worklogs. Both flags are required; read the
+id and its day off `worklogs --json`:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack worklog --delete 98765 --day 2026-09-07
+```
+
+It is a Tempo write, so the same rule holds: **name the worklog to the user, and delete only after
+they confirmed that one in this conversation.** The app refuses, deleting nothing, an id that is not
+among the account's own worklogs on that day. The delete is queued for the user's approval like
+`sync --write`; once approved, `approval <id>` answers what went, and the app drops its own record
+of the worklog, so the next `sync` of the day plans from what Tempo holds.
+
+## Writes
+
+Four commands write to Jira or Tempo, so all need the user to have asked for them in this
+conversation - `sync --write` and `worklog --delete` are described above. Each is queued for the
+user's approval in the app:
+
+```bash
+{%packageRunner%} ethlete-agents timetrack create --summary "Reset password mail is not sent" --project FIP
+{%packageRunner%} ethlete-agents timetrack log --issue FIP-2177 --minutes 45 --description "pairing call"
+```
+
+- **`create`** files the issue, once approved, with the instance's own ticket settings - its type, its parent
+  rule and its subject field all come from the app, so the ticket is shaped like every other.
+  `--project` is needed unless the app holds exactly one picked project.
+- **`log`** adds a row to the day in Timetrack. It is **not** a Tempo entry: the user reviews
+  the day and syncs it, which is what keeps an agent's row from double-booking against the
+  hours the day already observed. `--at` places it - an ISO instant, or a local `YYYY-MM-DD` or `HH:MM` (today); without one it starts now.
+
+## What the app decides, not you
+
+- **The projects.** The user picked them in Timetrack. `search` is scoped to them, and
+  `--project <KEY>` is how you look outside.
+- **The branch subject.** `issue` returns `subject` when the instance's subject field is set on
+  that issue. Prefer it over the summary; the summary is a paraphrase.
+- **The instance.** Its host, its issue types and its hierarchy are settings in the app. Do not
+  hardcode any of them in this repo.

package/content/skills/verify-in-app/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: verify-in-app
+description: Verify a UI change in the running app by driving it headlessly with Playwright - screenshots, computed styles, pointer and cursor state - and prove a fix with a test that fails without it. Use whenever you change a view, a component or its styles and need to confirm what renders, not just that it compiles.
+kind: skill
+scope: consumer
+---
+
+# Verify a UI change in the running app
+
+A build that passes says nothing about what the user sees. Serve the app, drive the real page in
+a headless browser, and assert on the rendered DOM and computed styles.
+
+## 1. Serve the app
+
+It may already be running. Check before starting a second instance - the dev server prompts for
+another port and hangs:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:4200/
+```
+
+- `200` → it is up.
+- anything else → start it in the background and poll the curl above until it answers (a cold
+  build can take a minute):
+
+  ```bash
+  npx nx serve <app>
+  ```
+
+The port and any proxy config live in the app's `project.json` `serve` target. A view behind a
+login needs a session: log in once through the form in the script, or seed the token storage the
+app reads before `page.goto`.
+
+## 2. Drive it with Playwright
+
+Use the `playwright` package from the repo's `node_modules`. Write the script in a scratch
+directory outside the repo and run it with `node`:
+
+```js
+import { createRequire } from 'node:module';
+
+const require = createRequire(`${process.cwd()}/`);
+const { chromium } = require('playwright');
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+
+await page.goto('http://localhost:4200/players?search=mul', { waitUntil: 'domcontentloaded' });
+await page.waitForSelector('.players-table', { state: 'attached' });
+
+const state = await page.$eval('.players-table', (el) => {
+  const cs = getComputedStyle(el);
+  return { display: cs.display, color: cs.color, rows: el.querySelectorAll('tr').length };
+});
+console.log(JSON.stringify(state));
+
+await page.screenshot({ path: '/tmp/players.png', fullPage: true });
+await browser.close();
+```
+
+Then read the screenshot back and look at it.
+
+- **`playwright` is CommonJS** - resolve it with `createRequire`; a named ESM import fails.
+- **`waitUntil: 'domcontentloaded'`, never `networkidle`** - the dev server's live-reload socket
+  and any polling query keep the network busy forever.
+- **`waitForSelector` waits for visible by default.** Pass `{ state: 'attached' }` for anything
+  correctly hidden (`opacity: 0`, collapsed, `inert`).
+- **Overlays render at the end of `<body>`,** not inside the view that opened them. Query them from
+  `page`, not from the view's element.
+- After a click that starts a transition, wait out its duration before reading final styles.
+
+## 3. Pointer and cursor state
+
+`getComputedStyle(el).cursor` reports what the stylesheet says, not what the pointer gets - an
+overlay, a backdrop or `pointer-events: none` in between changes the answer. Ask the page which
+element is under the point instead:
+
+```js
+const hit = await page.evaluate(
+  ([x, y]) => {
+    const el = document.elementFromPoint(x, y);
+    return el && { tag: el.tagName, class: el.className, cursor: getComputedStyle(el).cursor };
+  },
+  [640, 300],
+);
+```
+
+`elementFromPoint` returns `null` outside the viewport, so use a viewport tall enough for the
+point, or scroll the target into view first. Hover with `page.mouse.move(x, y)` before reading
+`:hover` styles.
+
+## 4. Prove a fix with a test that bites
+
+A screenshot shows the fix once; a test keeps it. For a bug fix, write the spec (a unit spec for
+logic, or a Playwright e2e spec where the app has one), then:
+
+1. run it against the fix - it passes;
+2. revert the fix (stash it, or comment the one line out) and run it again - it **must fail**;
+3. restore the fix.
+
+A test that passes both ways asserts on the wrong thing. Fix the test before you call the change
+done.
+
+## 5. Report
+
+Say what you drove (URL, clicks, viewport) and what you observed, with the numbers you read. Keep
+the script and screenshots in the scratch directory, not the repo.

package/migrations/app-styling-utilities.md

@@ -0,0 +1,63 @@
+# Move app CSS out of `@layer components`
+
+The `app-styling` rule now says how app components are styled: Tailwind utilities in the
+template, CSS only for what a utility cannot express, and never an app rule in
+`@layer components`. SDK styles are injected into that layer at runtime, after the app's
+stylesheet, so an app rule there ties on layer and loses on source order. That is a bug today,
+and this task fixes it. The rest of the rule applies when a component is next edited.
+
+## Before you start
+
+If this repo has no `app-styling` rule yet (in `AGENTS.md`, or under `.claude/rules/ethlete/`),
+run `ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`), then
+read the rule. If the repo's own styling rules (a styleguide, `CONTRIBUTING.md`, the parts of
+`AGENTS.md` outside the generated block) forbid a change below, follow them and report the
+conflict.
+
+## What to change
+
+1. Find the app stylesheets with a `@layer components` block, global stylesheets included:
+
+   ```bash
+   grep -rlE '@layer components' apps libs --include='*.css' --include='*.scss' --include='*.sass' --include='*.less'
+   ```
+
+2. In each, move the rules out of the block into `@layer utilities`, and delete the empty
+   block. In `@layer utilities` a rule still beats the SDK, and does not beat every utility the
+   way unlayered CSS would.
+3. The move lets these rules win over SDK styles they used to lose to. Check the views that use
+   them. Where a view now looks wrong because the old rule was never meant to apply, delete the
+   rule instead.
+
+## Leave these alone
+
+- A library that ships its own CSS to other repos. The rule is about app components.
+- Generated theme files, such as the surface and colour themes `@ethlete/core` writes.
+- `--spacing` and the other rem scales in `@theme`. If the app has not set `--spacing: 0.4rem`,
+  setting it now rescales every utility already in use: report it and leave it.
+- `html { font-size: 62.5%; }`: if it is missing, report it and leave it. Adding it rescales
+  every `rem` the app uses.
+
+## On touch, not in this task
+
+Rewriting BEM classes and component stylesheets to utilities, replacing hardcoded colours with
+theme tokens, and adding `ViewEncapsulation.None` to a component that relies on emulated CSS
+(its CSS would leak) happen when someone edits that component. Count what is left for the
+final message:
+
+```bash
+grep -rlE 'styleUrls?:' apps libs --include='*.ts' | wc -l
+grep -rlE 'class="[^"]*\b[a-z0-9-]+__[a-z0-9-]+' apps libs --include='*.html' --include='*.ts' | wc -l
+grep -rlE '@Component\(' apps libs --include='*.ts' | xargs grep -LE 'ViewEncapsulation\.None' | wc -l
+```
+
+## Done when
+
+- The grep in step 1 finds no app stylesheet, apart from the ones under "Leave these alone".
+- The type check, lint and build pass for every project you changed.
+- Each view that uses a moved rule is checked in the browser. A view you cannot open (the login
+  fails, no API) is listed as unchecked in your final message; that does not block the task.
+- Your final message gives the three counts above, and whether `--spacing` and the 62.5% root
+  are set.
+
+Then delete this task file.

package/migrations/list-state-query-form.md

@@ -0,0 +1,20 @@
+# Lists with URL state use `defineQueryForm`
+
+The `ethlete-query` skill now says every filtered, searched, sorted or paged list uses
+`defineQueryForm`, not `injectQueryParams()`, `router.navigate` and a draft signal wired by hand.
+Moving a list is a rewrite of its component, so it happens when someone next edits that list. The
+skill says how to keep the old URL working when you do.
+
+No code changes in this task. To see how many components still wire their params by hand, count
+the files that both read and write query params:
+
+```bash
+grep -rlE 'injectQueryParams?\(|queryParamMap|snapshot\.queryParams|\.queryParams\.(pipe|subscribe)\(' apps libs --include='*.ts' |
+  xargs grep -lE '\bqueryParams(Handling)?\b' | wc -l
+```
+
+## Done when
+
+- The count is in your final message, or in the report you give the developer.
+
+Then delete this task file.

package/migrations/nx-layout.md

@@ -0,0 +1,29 @@
+# Compare the workspace with the Nx layout rule
+
+`@ethlete/agent-rules` now ships an `nx-layout` rule for Nx workspaces: thin apps, feature code in
+`libs/domain/<app>/<feature>`, shared `queries`, `types`, `uikit`, `theme` and `env` libs, aliases that
+mirror the path, and one `scope:*` tag per project. New code follows it.
+
+This is a recommendation, not a rewrite. Moving projects changes import paths, project names, tags
+and CI caches across the whole repo, and the rule itself says not to restructure an existing
+workspace unless the team asks for it.
+
+## What to decide
+
+1. Read the rule (in `AGENTS.md`, or under `.claude/rules/ethlete/`). If it is missing, run
+   `ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`).
+2. List where the workspace deviates: feature code inside `apps/`, queries or themes inside an app,
+   `feature/ui/data-access/util` folders, aliases that do not mirror the path, missing `scope:*` tags.
+3. Decide per deviation: move it now, move it when that area is next touched, or keep it.
+4. Keep what you decided where an agent reads it, so it stops flagging it: in `AGENTS.md` above the
+   `<!-- ethlete:agent-rules:start -->` line or below `<!-- ethlete:agent-rules:end -->`, or in the
+   repo's `CONTEXT.md` or an ADR. Never between the two markers: `ethlete-agents sync` rewrites that
+   block and drops the edit. If `AGENTS.md` holds nothing but the block, add the decisions above it.
+
+An agent may prepare the list in step 2. It must not move a project without that decision.
+
+## Done when
+
+- Each deviation from step 2 has a decision, recorded as step 4 says.
+
+Then delete this task file.

package/migrations/sdk-components-over-hand-built-ui.md

@@ -0,0 +1,27 @@
+# Use the SDK component where one exists
+
+The `ethlete-sdk-docs` skill now lists every component domain, with a table that maps common needs
+to them ("Check this list before you build any UI by hand"). Apps built their own bar charts,
+avatars and progress bars because the old list did not name them. Replacing one restyles its view,
+so it happens when someone next edits that view, not in this task.
+
+When you do replace one, check every feature of the hand-built one against the SDK component's
+inputs, slots and `--et-*` tokens first, and keep the hand-built one where a feature has no
+counterpart. Known gaps:
+
+- `et-bar-chart` renders every category label and only truncates it, and has no slot for a title,
+  a note or an empty state.
+- `et-avatar` derives initials from `name` only, and takes its colours from a colour theme only.
+
+No code changes in this task. To count the candidates, skipping hits that already use an `et-`
+element:
+
+```bash
+grep -rlE 'bar-?chart|bar-?graph|avatar|initials|progress-?bar' apps libs --include='*.html' --include='*.ts' | xargs grep -LE '<et-(bar-chart|avatar|progress-bar)' | wc -l
+```
+
+## Done when
+
+- The count is in your final message, or in the report you give the developer.
+
+Then delete this task file.