@epicparty/skills 0.0.0-stage → 0.1.1

package/skills/outdated/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: outdated
+description: Reports which dependencies of a pnpm workspace have newer releases past the release quarantine, and what every changelog in between means for this codebase. Use when asked what is outdated, what a new release brings, or what an upgrade would involve.
+metadata:
+  pack: epicparty/skills
+  version: 0.1.0
+---
+
+# Outdated
+
+Packages in, one report out: each scoped dependency's newest version past the **quarantine**, and what every release in between means for this codebase. The report changes nothing. [`/ep-upgrade`](../upgrade/SKILL.md) applies it.
+
+The **quarantine** is the age a release must reach before the workspace takes it. It is the age the user gave, or else `minimumReleaseAge` in `pnpm-workspace.yaml` — in minutes there — and it skips each package in `minimumReleaseAgeExclude`. With neither, ask the user for this run's quarantine, and recommend `minimumReleaseAge`: pnpm enforces it at install, so the next run reads it too.
+
+The skill reads the registry and the tree and runs no product, so it works in any checkout as it is.
+
+## 1. Pin the scope
+
+- **The packages** — the ones the user named: by name, by catalog ("the tanstack catalog") or by product. With none named, every npm dependency in the workspace: each catalog entry, each direct range in a `package.json`, and the root `packageManager`.
+- **The families** — packages released or used together form one family, and a named package brings its family in. Read them off the workspace: packages published from one source repository (`pnpm view <pkg> repository.url`), a package with its `@types/*`, and the packages of a catalog named for one ecosystem — a `convex` or `sentry` catalog is a family, a catch-all `tooling` catalog is not.
+- **The couplings** — a comment beside a pin or an override in `pnpm-workspace.yaml` is a constraint, and it joins the packages it names into one family. A comment saying `vitest` follows the Vitest that `vite-plus` bundles moves `vitest` only to that version.
+- **The quarantine**, in days.
+
+Done when you can name the packages, their families, and the quarantine in days.
+
+## 2. Find the targets
+
+[`taze`](https://github.com/antfu-collective/taze) reads the catalogs and every manifest in one pass:
+
+```sh
+pnpx taze latest -r -l --no-github-actions --no-node-version --include <a>,<b> --json
+```
+
+- `latest` crosses majors. Leave out `--include` for the whole workspace.
+- `-l` is required. Without it taze skips exact pins, and almost every catalog entry is one.
+- `--no-github-actions --no-node-version` keep the run to packages. Action pins and the Node version are outside this report.
+- taze reads `minimumReleaseAge` and `minimumReleaseAgeExclude` itself. Add `--maturity-period <days>` only for a quarantine the user gave; it replaces the repo's.
+- taze writes the `packageManager` target with a caret. The field takes an exact version, so report the exact one.
+
+taze drops a package without a word when its newest release is still in quarantine and a release on another line — a `v9` maintenance tag, a canary — is the newest one past it. The package then has no row at all, or a row with `"diff": "error"`, and reads as current. So check every scoped package taze did not report: its target is the highest version in `pnpm view <pkg> versions --json` that is newer than the current one and past the quarantine in `pnpm view <pkg> time --json`. Take the versions from `versions`, because `time` also keeps unpublished ones.
+
+Confirm the quarantine held on one target that has a younger release: `pnpm view <pkg> time --json` shows the target past the quarantine and the newer release skipped.
+
+Done when every scoped package has a target with its publish date, or reads as current.
+
+## 3. Read the changelogs
+
+Read every release between the current version and the target. A breaking change ships in a middle release as often as in the last one. Sources, in order: the GitHub releases (`gh release list -R <owner>/<repo>`, the repository from `pnpm view <pkg> repository.url`), the `CHANGELOG.md`, then the migration guide of each major.
+
+Fan the reading out: subagents in parallel, one per large family and one per handful of small ones, each given its packages and their version spans. Each returns, per package:
+
+- **Breaking** — each change that touches our code, with the files it hits (`rg` the imports).
+- **Deprecated** — each API we call that the span deprecates, with its replacement and the files that call it.
+- **Improves us** — each new feature that replaces or simplifies code we have: a workaround, an override, a patch, a hand-rolled helper, a comment that names an upstream issue. With the files.
+- **New** — each feature worth knowing that no code of ours needs yet.
+- **Security** — each advisory the span fixes, with its id.
+- **Defaults** — each changed default that alters what the product collects, stores or shows, with what our config sets today.
+- **Peers** — the target's `peerDependencies` and `engines` (`pnpm view <pkg>@<version> peerDependencies engines`).
+
+A package with no changelog to find says so, and the gate becomes its only check.
+
+Done when every target has its items, or reads as nothing that touches us.
+
+## 4. Check the targets fit
+
+Check each target's peer ranges against the other targets and against the couplings, and its `engines` against the project's Node version — `.node-version`, `.nvmrc`, or the root `engines.node`. A **Breaking** item can hold a package with no range to show it — a plugin we keep that misbehaves under the target. A package in `minimumReleaseAgeExclude` skips the quarantine, but its dependencies do not. When it pins one exactly, check that dependency's publish date too (`pnpm view <pkg>@<version> dependencies`). A dependency still in quarantine holds the package at its newest version whose dependencies have all passed. A conflict holds the package at the newest version that fits (`pnpm view <pkg> versions --json`), or at its current one.
+
+Done when no target's peer range excludes another target, no `engines` range excludes the project's Node version, and each held package has its reason.
+
+## 5. Find the unused
+
+A scoped dependency is **unused** when nothing reaches it: no import (`rg` the package name across the workspace), no binary in a script, no reference in a config file, and no peer range of another installed package it satisfies. Check each manifest's entries and each catalog entry that no manifest references. The check is workspace-wide: a package that any workspace package reaches is used, whichever manifest declares it.
+
+Done when each scoped dependency is used, or listed as unused with where it is declared.
+
+## 6. Write the report
+
+The report lives in the reply only — a later `/ep-upgrade` in the same thread reads it from there, and another thread runs this skill again. It is read top-down: the highlights first, the detail by family after them. Every line holds one fact, and every version is exact, because `/ep-upgrade` takes the report as its plan.
+
+```markdown
+**Quarantine:** 3 days, from `minimumReleaseAge`. **Scope:** the whole workspace — 80 of 112 packages behind, 12 families.
+
+## Highlights
+
+1. **Sentry 10.65.0 → 11.8.0** — breaking: `beforeSend` receives … Touches `src/lib/sentry/server.ts`.
+2. **TanStack Router 1.170.17 → 1.170.45** — improves us: typed search defaults remove the casts in `src/routes/…`.
+
+## By family
+
+### vite — `vite-plus`, `@voidzero-dev/vite-plus-core`, `vitest`, `@vitest/coverage-v8`
+
+`vite-plus` and `vite-plus-core` 1.0.0 → 1.3.0 (minor) · `vitest` and `@vitest/coverage-v8` 5.0.1 → 5.0.5 (patch)
+
+- **Breaking:** none that touches us.
+- **Improves us:** `vp test --changed` … could replace … in `package.json`.
+- **New:** …
+- **Peers:** fit.
+
+### Nothing that touches us
+
+- **tailwind** (4 packages) — 4.3.2 → 4.3.3, patch. Bug fixes in …
+
+## Held
+
+- `posthog-js` 1.438.13 — under the quarantine until 2026-10-23. Takes 1.438.12.
+- `better-auth` 1.7.10 — `@convex-dev/better-auth` 0.12.5 peers on `<1.7.0`. Takes 1.6.33.
+- `jsdom` 30.1.3 — its `engines` excludes Node 24.14.0, the project's Node version. Stays on 29.1.1.
+
+## Open questions
+
+1. **Sentry `dataCollection`** — v11 removes `sendDefaultPii` and collects request bodies, headers and IPs by default, because … Our events then carry … (`src/lib/sentry/…`). Options: keep v10's set — …; take the new default — …. Recommended: keep v10's set, because ….
+
+## Unused
+
+- `@tailwindcss/cli` — in the `styling` catalog. No manifest references it.
+```
+
+- **Highlights** — the items that change what the user decides, ranked: **Security** for an advisory our current version has — in shipped code before a dev tool — then **Breaking** and **Defaults**, then **Improves us**, then a **New** feature with real weight. Each names the family, the version jump, the item and its files.
+- **A family block** for each family with at least one item, majors first, then by item count. The version line names every package that moves. The bullets keep the order of step 3; **Breaking** is always there, as "none that touches us" when empty, so the reader knows it was checked. Any other label with nothing is left out.
+- **Nothing that touches us** — one line per remaining family: the span, the kind, and what the releases did in a few words.
+- **Held** — every release a package does not take, its reason, and the version it takes instead. A held package that still moves also keeps its line in its family block.
+- **Open questions** — each choice the report leaves to the user: a major to take or hold, a held package with another way out, a default that changes what the product collects or shows, an optional adoption. Each carries what [`/ep-upgrade`](../upgrade/SKILL.md) needs for its briefing: what changed and why, what it touches here, the options with their consequences, and a recommendation with its reason.
+- **Unused** — last, each unused dependency with where it is declared. Leave the heading out when there is none.
+
+Done when every scoped package that moves appears once — in a family block or under **Nothing that touches us** — every release it does not take is under **Held**, every package that neither moves nor is held is in the count of current packages, and every unused one is under **Unused**.

package/skills/research/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: research
+description: Investigates a question against primary sources and reports the findings, publishing a large one where the project keeps its research. Use when a question needs facts from outside this repo, or the user asks for a topic researched. A failure in this code goes to /ep-diagnose instead.
+metadata:
+  pack: epicparty/skills
+  version: 0.1.0
+---
+
+# Research
+
+A question about facts outside this repo — a platform's behaviour, a library's contract, a spec. Research ends in **findings the user can decide from**, and in a **published note** when the findings are worth going back to.
+
+The decision belongs on the issue or in the ADR. The evidence belongs in the note, at the project's **Destination** setting. A note is evidence and never a rule: an agent that finds research beside the standards follows the evidence instead of the decision, so a note that lands in the repo says so on its first line.
+
+## 1. Investigate
+
+Spin up a **background agent** so you keep working while it reads. Its brief: primary sources first — official docs, source code, specs, first-party help centres — and a secondary source only where no primary exists, labelled as such. Every claim carries its source. A page that blocks fetching is cited from its search snippet and marked `(snippet)`; a claim with no source at all is marked `(unverified)`.
+
+Done when every claim in the findings has a source or a mark.
+
+## 2. Report
+
+The reply is the findings' default home, sized to the question: an answer with its sources, or a comparison table with a synthesis. Lead with what the user asked, then what it means for the decision in hand.
+
+Done when the user can decide from the reply alone.
+
+## 3. Decide the home
+
+A research earns a published note when both hold:
+
+- **It is big.** A comparison across many sources, or more than a reply carries without burying the answer.
+- **Something will cite it.** A story, an ADR or a PR will point back at it, or the user says they want to go back to it.
+
+Both hold: publish (§ 4). Only the first holds: ask the user whether to keep it. Neither: the reply was the whole deliverable, and the agent's working notes are discarded with it.
+
+Done when the home is named: the reply, or a published note.
+
+## 4. Publish
+
+Read the **Destination** setting now, per [Settings](#settings). This is the one step that needs it, so a research that ended in the reply never asks.
+
+Every destination takes the same note:
+
+- **Title**: `Research: <the question>`.
+- **Body**: the date, the question, the method and its limits, the findings with inline `[n]` citations, the synthesis, and the `Sources` list. The whole note, so it stands without the chat.
+
+Then publish it the way the setting says.
+
+**GitHub Discussion** — one Discussion in the setting's category, resolved by name, never by id:
+
+```sh
+publish_research() { # publish_research <category> <title> <body-file>
+  # Braced on purpose: the harness substitutes skill arguments into a bare $N.
+  local category="${1}" title="${2}" body_file="${3}"
+  local owner name repo_id category_id
+  read -r owner name < <(gh repo view --json owner,name --jq '"\(.owner.login) \(.name)"')
+  read -r repo_id category_id < <(gh api graphql -f query='
+    query($o:String!,$r:String!){ repository(owner:$o,name:$r){ id
+      discussionCategories(first:20){ nodes{ id name } } } }' \
+    -f o="$owner" -f r="$name" \
+    --jq ".data.repository | \"\(.id) \(.discussionCategories.nodes[] | select(.name==\"$category\") | .id)\"")
+  [[ -z "$category_id" ]] && { echo "no $category category: a maintainer creates it under Settings → Discussions" >&2; return 1; }
+  gh api graphql -f query='
+    mutation($r:ID!,$c:ID!,$t:String!,$b:String!){
+      createDiscussion(input:{repositoryId:$r,categoryId:$c,title:$t,body:$b}){ discussion{ url } } }' \
+    -f r="$repo_id" -f c="$category_id" -f t="$title" -f b="$(cat "$body_file")" \
+    --jq '.data.createDiscussion.discussion.url'
+}
+```
+
+A missing category stops the publish: say so, because only a human can create one.
+
+**A file in this repo** — `<directory>/<YYYY-MM-DD>-<slug>.md`, its first line `> Research evidence, not a rule. The decision lives in the issue or ADR that cites this note.` Write it to the working tree and name the path; it is committed when the user asks, or with the work that cites it.
+
+**Somewhere else** — follow the setting's instructions as written. A tool they name that this session cannot reach stops the publish: say which one.
+
+Done when the reply carries the note's URL or path.
+
+## 5. Cite
+
+Whatever the research fed — the story, the ADR, the PR body — links the note and states the conclusion in one line beside the link. A reader of the issue learns what was decided without opening the note, and opens it only to see why.
+
+Done when the citing document names the decision and the link.
+
+## Settings
+
+This skill reads one **setting**, **Destination**, at § 4. Each `###` heading below is one setting: its topic, its question, and its options. `/ep-setup` reads the same headings to ask every setting up front.
+
+1. **The settings home.** The `## Agent skills` block of the root `AGENTS.md` — or `CLAUDE.md`, whichever the project has — names where `ep-*` settings live and in what form. With neither file present, first ask which to create, recommending `AGENTS.md`, which most agents read. With no such line, ask the user where to keep them, the default first:
+   - **`docs/agents/<topic>.md`** (default) — one Markdown file per topic, one `##` heading per setting, named as the setting. Other headings in the file are the project's own notes.
+   - **One file** — at a path the user names.
+   - **Another form** — as the user describes it.
+
+   Write their answer as one line in that block, creating the block when it is missing — for the default, `` `ep-*` settings: `docs/agents/<topic>.md`, one heading per setting. ``
+2. **The setting.** Read it at the settings home. Present: use it, and ask nothing.
+3. **Missing.** Ask its question below, recommended answer first, with the follow-up its option needs. Write the answer at the settings home, tell the user where it went and that they can edit it there or through `/ep-setup`, then continue.
+
+### Destination
+
+Topic `research`. Question: *Where should research worth keeping be published?*
+
+| Option | Follow-up | Recommend when |
+| --- | --- | --- |
+| **GitHub Discussion** | The category name, default `Research` | The repo has Discussions on (`gh repo view --json hasDiscussionsEnabled`) |
+| **A file in this repo** | The directory, default `docs/research/` | Discussions are off |
+| **Somewhere else** | The instructions, in the user's words: the tool, the place, the format | — |
+| **Nowhere** | — | — |
+
+**Nowhere** makes the reply every research's home: § 3 then names the reply and § 4 never runs.
+
+## Guardrails
+
+- **Findings are facts, decisions are the user's.** Report what the sources say and what it implies for the choice in hand; put the choice to the user.
+- **One note per question.** A follow-up on the same question extends that note — a comment on the Discussion, a dated section in the file — rather than starting a second one.
+- **A note is evidence, never a rule.** Nothing in `AGENTS.md`, a standard or a skill points at one as the thing to follow; they point at the ADR or the story that decided. A note directory stays out of every standards route.

package/skills/router/BOARD.md

@@ -0,0 +1,157 @@
+# Board
+
+How the `ep-*` skills keep a project board, where the **Tracker** setting (`/ep` `## Settings`) names one. Without a board, every rule here is skipped: the labels, the branches and the PRs carry the state. The project's own rules add to these and win where they differ.
+
+## Stages
+
+The skills name a board's statuses by **stage**. The **Tracker** setting maps each stage to the board's own status name.
+
+| Stage | Meaning | Who writes it |
+| --- | --- | --- |
+| **Ideas** | A draft idea, not wanted yet; never a real issue | A skill, on a draft it creates |
+| **Triage** | Not evaluated, or waiting on the reporter or on a decision | The board's automation on add, then projected from the labels |
+| **Backlog** | Prioritised, not started | Projected from the labels |
+| **Ready** | Fully specified | Projected from the labels |
+| **Queued** | Wanted now: a worker may claim it. Only where the **Ready signal** is this board column (`/ep-deliver`) | **The user**, by hand. A skill only returns a story there (see Rules) |
+| **Building** | Being built, validated and self-reviewed on a branch | `/ep-implement` § 1, or the `/ep-deliver` claim |
+| **Review** | PR open, awaiting CI and review | `/ep-to-pr` § 5, and the board's automation where it watches linked PRs |
+| **Shipping** | Merged; deploy running, awaiting its receipt | `/ep-ship` § 1 |
+| **Parked** | Optional. A worker stopped on a question; its branch or PR holds the work | `/ep-deliver`, at the park |
+| **Done** | Closed | The board's automation on close |
+
+A board without some of these stages skips them, and the skills write nothing for a stage it lacks. Without **Parked**, a parked story keeps the stage it had, and its question label and comment are what mark it.
+
+## Labels drive the status, until the work starts
+
+Up to **Ready**, the status is a **projection** of the labels, not a second source of truth: set it in the same pass you set the labels, or the two drift and the board stops being worth reading. From **Queued** — or, without that stage, from the claim — the labels stop driving it and the board **is** the state.
+
+Up to **Ready**, read this table top-down and take the **first** row that matches; the rows overlap in practice, so order is the rule. Labels are named by role (the **Labels** setting).
+
+| Labels on the issue | Stage |
+| --- | --- |
+| The triage label, or an axis still unset | Triage |
+| The info label | Triage — looked at, but waiting on the reporter |
+| The discovery label | Triage — looked at, but waiting on a decision |
+| A ready label | Ready |
+| Every axis set | Backlog |
+
+The triage label outranks a priority deliberately. The two co-occur on real issues: a priority applied at filing time is a guess, and the triage label says a maintainer has still not evaluated the issue. Whoever triages drops it, and only then does the backlog row take effect.
+
+**Queued is intent; a ready label is a property.** A ready label says the story is specified well enough to build. Queued says the user wants it started now. Keeping them apart is what lets a story be honestly ready and still not be started.
+
+## Rules
+
+- **Never add an issue to the board by hand where an automation adds it.** Your job is only the status of an item that is already there.
+- **When creating an issue, leave the status alone.** The automation adds the item asynchronously, so anything set in the same breath as the create races it and silently does nothing. Get the labels right instead; the board catches up on its own.
+- **When filing an idea, create a draft on the board, never an issue.** A draft is the one item you add by hand, because no automation can. An add automation may still write Triage on it, asynchronously, so `board_idea` below sets Ideas and re-reads until it holds.
+- **When labels move an issue along**, set the new stage in the same pass. By then the item exists.
+- **Only the user queues a story.** No skill puts an issue in Queued that the user did not put there. A user's explicit yes to a skill's offer — `/ep-triage` offers it on a ready story — is the user queuing it. An agent that queues its own work has removed the control the gate exists to give. The one write a skill makes is a **return**: a story the user queued, whose claim produced no branch and no PR, goes back to Queued (`/ep-deliver` § 1). The user wanted it started, and a worker that died does not cancel that.
+- **A claim is one write, then a read.** Write Building **before** cutting the branch, then re-read the item. A worker that does not see itself as the writer lost the race. This is the only thing stopping two workers building one story.
+- **Review when the PR opens**, not after CI goes green: Review covers "PR open, awaiting CI and review", so an amber build belongs there too. The write may agree with an automation that already made it; it costs one call and covers a PR opened without a link.
+- **Shipping immediately *before* the merge**, not after. The merge closes the issue, and a close automation then writes Done; a later Shipping write would land on top of Done and stick, because that trigger is spent.
+- **Never set Done by hand**, except when reconciling: moving an issue you have just read as **closed** confirms rather than asserts. Setting Done on anything else only masks whether the issue actually closed.
+- **Done means closed, not shipped.** A close automation fires on any close, including *not planned*. The merged PR is what says the work landed.
+- **Never hardcode the project, field or option ids.** They are regenerated whenever the board is recreated, so resolve them every time.
+
+## When the user asks
+
+| The user says | It means |
+| --- | --- |
+| "the board" | The board the **Tracker** setting names |
+| "save it as an idea", "add it to the board as an idea", "a draft issue" | A draft in Ideas, with `board_idea`. Never a real issue |
+| "check the board", "update the statuses" | [Checking the board](#checking-the-board), with every card you moved named in the reply |
+
+## Checking the board
+
+Read every card and move each one whose stage no longer matches what exists. Take the first rule that applies:
+
+1. **The issue is closed**: Done.
+2. **Building, Review, Shipping or Parked**: the in-flight table in [`/ep-deliver`](../deliver/SKILL.md) `### 1. Reconcile what is in flight` — a branch, a PR, a merge.
+3. **Triage, Backlog or Ready**: the label table above.
+4. **Queued, or a draft in Ideas**: leave it. Both are the user's own moves.
+
+Never queue a story the user did not queue: the only Queued write is the return that step 2 makes. Name every card you moved, from which stage to which, and why. A card moved in silence is a card the user can no longer trust.
+
+## GitHub Projects commands
+
+For a GitHub Project linked to the repository, with a single-select `Status` field. `board` finds the one open board linked to the repo — by that link, not by its title, so renaming it changes nothing. `board_status` sets the status of an issue already on it; `board_idea` saves an idea as a draft and prints the draft's id. Pass the board's own status names, from the **Tracker** setting. An empty item id in `board_status` means the automation has not added the issue yet; leave it, do not add it yourself.
+
+```sh
+repo() { # prints "<owner> <name>"
+  gh repo view --json owner,name --jq '"\(.owner.login) \(.name)"'
+}
+
+board() { # prints "<number> <project-id>": the one open board linked to this repo
+  local owner name
+  read -r owner name < <(repo)
+  gh api graphql -f query='
+    query($o:String!,$r:String!){ repository(owner:$o,name:$r){
+      projectsV2(first:10){ nodes{ number id closed } } } }' -f o="$owner" -f r="$name" \
+    --jq '[.data.repository.projectsV2.nodes[] | select(.closed==false)][0] | "\(.number) \(.id)"'
+}
+
+board_option() { # board_option <project-number> <status-name>: prints "<field-id> <option-id>"
+  local owner name
+  read -r owner name < <(repo)
+  gh project field-list "$1" --owner "$owner" --format json \
+    --jq ".fields[] | select(.name==\"Status\") | \"\(.id) \(.options[] | select(.name==\"$2\") | .id)\""
+}
+
+board_set() { # board_set <project-id> <item-id> <field-id> <option-id>
+  gh api graphql -f query='
+    mutation($p:ID!,$i:ID!,$f:ID!,$o:String!){
+      updateProjectV2ItemFieldValue(input:{
+        projectId:$p, itemId:$i, fieldId:$f, value:{singleSelectOptionId:$o}
+      }){ projectV2Item{ id } }
+    }' -f p="$1" -f i="$2" -f f="$3" -f o="$4" >/dev/null
+}
+
+board_item_status() { # board_item_status <item-id>
+  gh api graphql -f query='
+    query($i:ID!){ node(id:$i){ ... on ProjectV2Item {
+      fieldValueByName(name:"Status"){ ... on ProjectV2ItemFieldSingleSelectValue { name } } } } }' \
+    -f i="$1" --jq '.data.node.fieldValueByName.name'
+}
+
+board_status() { # board_status <issue-number> <status-name>
+  local issue="$1" target="$2" # not `status`: zsh reserves that name
+  local owner name number project_id field_id option_id item_id
+  read -r owner name < <(repo)
+  read -r number project_id < <(board)
+  read -r field_id option_id < <(board_option "$number" "$target")
+
+  item_id=$(gh api graphql -f query='
+    query($o:String!,$r:String!,$n:Int!){
+      repository(owner:$o,name:$r){ issue(number:$n){
+        projectItems(first:10){ nodes{ id project{ id } } } } }
+    }' -f o="$owner" -f r="$name" -F n="$issue" \
+    --jq ".data.repository.issue.projectItems.nodes[] | select(.project.id==\"$project_id\") | .id") ||
+    { echo "issue #$issue does not exist" >&2; return 1; }
+
+  [[ -z "$item_id" ]] && { echo "issue #$issue is not on the board yet" >&2; return 1; }
+
+  board_set "$project_id" "$item_id" "$field_id" "$option_id"
+}
+
+board_idea() { # board_idea <title> <body> <ideas-status-name>: prints the draft's item id
+  local owner name number project_id field_id option_id item_id
+  read -r owner name < <(repo)
+  read -r number project_id < <(board)
+  read -r field_id option_id < <(board_option "$number" "$3")
+  item_id=$(gh project item-create "$number" --owner "$owner" \
+    --title "$1" --body "$2" --format json --jq '.id')
+
+  # An add automation may write Triage on the draft, asynchronously:
+  # set Ideas until a re-read shows it held.
+  local attempt
+  for attempt in 1 2 3; do
+    board_set "$project_id" "$item_id" "$field_id" "$option_id"
+    sleep 5
+    [[ "$(board_item_status "$item_id")" == "$3" ]] && { echo "$item_id"; return 0; }
+  done
+  echo "draft $item_id did not stay in $3" >&2
+  return 1
+}
+```
+
+Writing to a project needs a token carrying the `project` scope; the repo scope alone is not enough, and the default `GITHUB_TOKEN` cannot write an organisation's projects at all. Locally: `gh auth refresh -s project,read:project`.

package/skills/router/DECISIONS.md

@@ -0,0 +1,71 @@
+# Decisions
+
+Where a decision the work makes is written down, and how the `ep-*` skills read the project's domain documents. The project's own rules — its domain doc, its ADR layout — add to these and win where they differ.
+
+## Before exploring, read these
+
+- **The glossary** — `GLOSSARY.md` at the root, or a `GLOSSARY-MAP.md` that points at one glossary per context. A project that already names them `CONTEXT.md` and `CONTEXT-MAP.md` keeps those names. Read each one relevant to the topic.
+- **The ADRs** — `docs/adr/`, and in a multi-context project the context's own ADR directory beside its glossary. Read the ones that touch the area you are about to work in.
+
+Where any of these does not exist, **proceed silently**. Their absence is not a finding, and creating them upfront is work nobody asked for: they are created lazily, when a term or a decision actually gets resolved — [`/ep-grill`](../grill/SKILL.md) writes them as a session settles them, in the formats below.
+
+## Where a decision goes
+
+Three homes, widening in scope. Pick by **how long the decision binds**, not by how much detail it carries.
+
+| The decision | Home |
+| --- | --- |
+| Shapes the increment being built, and nothing beyond it | The story's `## Implementation Decisions` |
+| Binds code outside its own story, in one area | An ADR |
+| Binds more than one area, or is applied repeatedly | A project standard |
+
+**The story is the default.** Most decisions made while building are answers to "how do we do this one", and they belong in the issue that asked for the work. Writing an ADR for one of those duplicates the story into a file nobody reads.
+
+**An ADR earns its file when someone will need the decision while working on something else.** The cheap proxy: would a code comment cite it? A function that refuses to do the obvious thing needs a reason with a stable address, and `// (ADR 0006)` is that address.
+
+The reason a live constraint cannot stay in the story is lifetime. **A story is frozen once its work lands on the default branch** — later changes become new issues, so a feature that keeps moving leaves a chain of closed stories, and a constraint parked in one of them can only be reconstructed by reading the whole chain and guessing which parts still hold. **An ADR is live**: it is superseded in place by a named successor, so there is exactly one current answer.
+
+**A standard is an ADR that outgrew its context.** When a second area needs the same rule, the ADR stays as decision history and the rule moves to the project's standards, which become binding.
+
+Three things that are **not** ADRs: a decision that only shapes its own increment (the story), a restatement of an existing standard (point at the standard), and a plan for work not yet done (an issue).
+
+## Writing the glossary
+
+When a term is resolved, write it into the glossary right there — never batched for later — in the shape of [`GLOSSARY-FORMAT.md`](./GLOSSARY-FORMAT.md).
+
+## Writing an ADR
+
+<!-- upstream: mattpocock/skills skills/engineering/domain-modeling/ADR-FORMAT.md -->
+
+**Offer an ADR only when all three hold:** the decision is **hard to reverse**, it is **surprising without context** — a reader of the code would wonder why — and it is **the result of a real trade-off**, with genuine alternatives. Missing any one, skip it: an easy decision is reversed, an obvious one is never wondered about, and one with no alternative records nothing.
+
+What qualifies: the architecture's shape; how contexts integrate; a technology choice with lock-in — not every library, only the ones that take a quarter to swap; a boundary or scope decision, the explicit noes included; a deliberate deviation from the obvious path; a constraint the code cannot show, such as a compliance rule or a partner's response-time contract; and a rejected alternative whose rejection is not obvious, so nobody proposes it again in six months.
+
+ADRs live in `docs/adr/` as `0001-slug.md`, `0002-slug.md`, and so on — the next number is the highest in the directory plus one. Create the directory with the first ADR.
+
+```md
+# {The decision, stated as a claim}
+
+{One to three sentences: the context, what was decided, and why.}
+```
+
+That can be the whole ADR. Keep it short: one to three paragraphs.
+
+- **The title states the decision as a claim**, present tense — "Blocking severs relationships and never confirms itself", not "Blocking behaviour". The title is what a reader scans a directory for.
+- **The body gives the decision, what it rules out, and the cost accepted.** The cost is the part that stops the decision being reopened every six months.
+- **`## Considered options` only when a rejected option will be proposed again.** Most decisions do not need it. `## Consequences` only when a downstream effect is not obvious, and a `Status` line (proposed, accepted, deprecated, superseded) only where decisions get revisited.
+- **An ADR number is its identity.** Numbers run per directory and are never reused, so a new ADR takes the next free number in the directory it lands in.
+- **Supersession is stated by the successor**, naming what it replaces and what still stands. Add a line to the superseded ADR pointing forward; leave its body intact as history.
+- **Qualify a citation that crosses directories.** Where several ADR directories share one numbering space, `ADR 0006` names several decisions. Inside a context's own tree a bare number reads as that context's ADR; a citation from outside it takes the context's prefix.
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept — an issue title, a refactor proposal, a hypothesis, a test name — use the term as the glossary defines it. Do not drift to synonyms the glossary avoids.
+
+A concept the glossary lacks is a signal: either you are inventing language the project does not use (reconsider), or there is a real gap: add the term when the user settles it, or note it in your report when they are not there to.
+
+## Flag ADR conflicts
+
+When your output contradicts an existing ADR, surface it rather than silently overriding it:
+
+> _Contradicts ADR 0007 (match-scoped disqualification) — but worth reopening because…_

package/skills/router/GIT.md

@@ -0,0 +1,70 @@
+# Git
+
+How the `ep-*` skills name, commit, merge and catch up work. The project's own git rules — in its agent files, or the document they route to — add to these and win where they differ.
+
+## Commits
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): `type(scope): description`, the type from the set `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `style`, `perf`, `build`, `revert`.
+
+- **Each commit stands alone**: its own subject, its own scope, and a body wherever the change needs explaining. Under a rebase merge every commit reaches the default branch as itself, and it is written for the reader who finds it there.
+- Move and rename files with `git mv`, so history follows them.
+- Validate before committing.
+- Stage only your own changes. Work in the tree you did not write is somebody's, and it stays out of your commits.
+
+## Naming an issue, a PR and a branch
+
+One **scope** identifies a piece of work everywhere it appears — the issue, the PR and the branch — taken from the **Scopes** setting (`/ep` `## Settings`). Read it once and you know which part of the project is moving.
+
+| Artifact | Shape | Example |
+| --- | --- | --- |
+| Issue title | `<scope>: description` | `billing/invoices: send a reminder before an invoice falls due` |
+| PR title | `type(<scope>): description` | `feat(billing/invoices): send a reminder before an invoice falls due` |
+| Branch | `type/<scope-with-dashes>-short-slug` | `feat/billing-invoices-due-reminder` |
+
+- **The scope is the same string on all three**, cased the way the project's rules case it.
+- **The issue carries no type.** One issue can legitimately produce a `feat` PR and a `fix` PR, and a title that names a type would be wrong for one of them. The type lives on a label, where the project has a type axis.
+- **The PR always carries a type**, the branch's dominant change.
+- **The description is a lowercase imperative phrase** with no trailing period, and it reads the same on the issue and the PR. It does not restate the scope.
+- **Commits inside the PR keep their own narrower scopes.** A `feat(billing/invoices)` PR may hold `feat(billing/api)` and `feat(billing/web)` commits: the PR names the feature, each commit names the layer it touches.
+
+Without scopes, every shape drops its scope: `description`, `type: description`, `type/short-slug`.
+
+## Merging
+
+Merge the way the **Merge strategy** setting says (`/ep` `## Settings`):
+
+- **Rebase** — every commit lands on the default branch as itself, so the branch's history is the record. The PR title and body reach the default branch in no form at all: anything a reader of `git log` needs is in a commit message already. A review fix is a commit like any other, and is written as one.
+- **Squash** — the PR becomes one commit, its subject the PR title and its body the PR body. The PR body is part of the record, and is written for the `git log` reader as well as the reviewer.
+- **Merge commit** — the branch's commits land as themselves under a merge commit titled by the PR.
+
+## Catching up with the default branch
+
+**A branch catches up by a rebase onto `origin/<default>`.** A conflict with the default branch is the usual reason. Never merge the default branch into the branch: under a rebase merge the merge commit is dropped and the conflict comes back, and under any strategy it buries the branch's own changes in a merge nobody reviews.
+
+```sh
+git fetch origin <default>
+git rev-parse HEAD                  # the old head SHA: it must match the PR's head
+git rebase origin/<default>
+```
+
+Resolve each conflicting commit as the rebase stops on it, and continue until every commit is replayed. A resolution belongs to the commit that conflicted, so each commit still stands alone. Keep the rebase to conflict resolution: a review fix is its own commit, made on top of the rebased branch.
+
+<!-- upstream: mattpocock/skills skills/engineering/resolving-merge-conflicts/SKILL.md (removed upstream at daa01d8) -->
+
+Each stop, in order:
+
+1. **Read the state** — `git status`, the conflicting files, and the commit being replayed.
+2. **Find why each side changed.** Read the commit messages, then the PRs and issues behind them. A hunk resolved without knowing either intent is a guess.
+3. **Resolve each hunk.** Keep both intents where they fit together. Where they cannot, keep the one that matches the default branch's later decision, and name the trade-off in your report. Add no behaviour neither side had.
+4. **Run the checks** the change touches — `/ep-implement`'s **Scoped check** setting where it is set, or the project's typecheck and tests — and fix what the resolution broke.
+5. **Stage and continue** — `git add` the resolved files, then `git rebase --continue`.
+
+Abort the rebase only when the user asks: a conflict is resolved, not walked away from.
+
+The rebased head is a commit nobody has tested, so the project's full suite runs on the head you push. Push with a lease pinned to the old head SHA:
+
+```sh
+git push --force-with-lease=<branch>:<old-head-sha>
+```
+
+The pinned lease refuses the push when somebody pushed to the branch after you read it. A bare `--force-with-lease` checks against the remote-tracking ref, and any fetch since your read — yours, or an editor's in the background — may have moved that ref over a commit you never saw.

package/skills/router/GLOSSARY-FORMAT.md

@@ -0,0 +1,48 @@
+# Glossary format
+
+<!-- upstream: mattpocock/skills skills/engineering/domain-modeling/GLOSSARY-FORMAT.md -->
+
+How the glossary is written, once a term is resolved. Where it lives is [`DECISIONS.md`](./DECISIONS.md) `## Before exploring, read these`; the examples below use `GLOSSARY.md`, and a project that keeps `CONTEXT.md` writes the same thing there.
+
+## One glossary
+
+```md
+# {Context name}
+
+{One or two sentences: what this context is and why it exists.}
+
+## Language
+
+**Order**:
+A customer's request to buy one or more products.
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+```
+
+- **Be opinionated.** Where several words name one concept, pick the best and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences: what the term _is_, not what it does.
+- **Only the project's own concepts.** A general programming concept — a timeout, an error type, a utility pattern — stays out, however much the project uses it.
+- **Group terms under subheadings** when natural clusters emerge. One cohesive area is a flat list.
+- **No implementation details.** The glossary is not a spec, a scratch pad or a home for implementation decisions. It is a glossary and nothing else.
+
+## Several contexts
+
+A map at the root lists the contexts, where each glossary lives, and how they relate:
+
+```md
+# Glossary map
+
+## Contexts
+
+- [Ordering](./src/ordering/GLOSSARY.md): receives and tracks customer orders
+- [Billing](./src/billing/GLOSSARY.md): generates invoices and processes payments
+
+## Relationships
+
+- **Ordering → Billing**: Ordering emits `OrderPlaced`; Billing consumes it to generate an invoice
+```
+
+With a map, infer which context the term belongs to, and ask when it is unclear. With neither file, create a root glossary when the first term is resolved — never before.