@gallopsystems/agent-skills 1.28.0 → 1.30.0

package/plugins/linear/skills/linear/cli.md

@@ -0,0 +1,249 @@
+# `linear.mjs` — CLI Fallback
+
+Read this only when you need an operation the Linear MCP server doesn't expose (see **Linear Tooling** in `SKILL.md`). The workflow rules in `SKILL.md` — status, placement, labels, templates — apply no matter which tool you use.
+
+The fallback tooling is a single zero-dependency Node script, `bin/linear.mjs`. It runs on bare `node` (v18.3+ — no `npm install`, no `tsx`, no build step) and uses symbolic names instead of raw UUIDs (`--state backlog`, `--assignee frontend`, `--labels bug,frontend`).
+
+Invoke it as `node <skill>/bin/linear.mjs <command> [args] [--flags]`. Examples below write `node linear.mjs` for brevity — use the full path to the file, or `cd` into the skill's `bin/` directory first. Run `node linear.mjs help` for the full command list.
+
+It wraps the Linear GraphQL API and reads `LINEAR_API_KEY` from the environment plus the workspace config from `~/.config/linctl/workspace.json`. There is nothing to source — every invocation loads config fresh.
+
+## Setup (run once per user)
+
+### Workspace bootstrap config
+
+Before running any `linear.mjs` command, verify that the per-user workspace config exists at `~/.config/linctl/workspace.json` (override path with `$LINCTL_WORKSPACE_FILE`). This file holds **every team** in the workspace (each with its own UUID plus its workflow-state and label UUIDs — states differ per team), an optional `defaultTeam`, and the Linear member UUIDs that play the Frontend/PM and Backend roles. Without it, every command that needs the team, members, states, or labels fails.
+
+> **Multi-team workspaces:** `workspace.json` registers all teams, but `states`/`labels` are per-team (each team's `Todo` is a distinct UUID). Which team a command targets is resolved in this order: the **`--team <key|name|uuid>`** flag → the **`LINCTL_DEFAULT_TEAM`** env var (a per-repo default — set it via direnv/`.envrc` or your shell so every command in a repo targets that team) → the **`defaultTeam`** field in `workspace.json`. If none resolve, `--team` is **required** on team-scoped commands; workspace-wide commands (e.g. `list-initiatives`) work without a team. A legacy config (predating per-team support, i.e. with no `defaultTeam` key and top-level `states`/`labels`) still works — it falls back to the first registered team — but re-run `init` to migrate it to the per-team schema.
+
+```bash
+[ -f "${LINCTL_WORKSPACE_FILE:-$HOME/.config/linctl/workspace.json}" ] && echo "ok" || echo "missing"
+```
+
+**If missing,** instruct the user to run:
+
+```bash
+node linear.mjs init
+```
+
+`init` calls Linear's GraphQL API, lists the workspace's members, and prompts the user to designate (1) the Frontend/PM lead and (2) the Backend lead by number, then (3) an optional default team key (blank = no default, so `--team` is required on each team-scoped call). It registers **all** teams with their per-team states/labels and writes `~/.config/linctl/workspace.json`. The config is read fresh on every invocation — no re-sourcing needed.
+
+### `LINEAR_API_KEY`
+
+`linear.mjs` reads `LINEAR_API_KEY` from the environment. Before using any command, check whether it's set:
+
+```bash
+[ -n "$LINEAR_API_KEY" ] && echo "set" || echo "missing"
+```
+
+**If missing, onboard the user:**
+
+1. Tell them: *"I need a Linear personal API key to run the CLI. Create one at https://linear.app/settings/account/security (click 'New API key', name it 'Claude Code', copy the `lin_api_...` token), then paste it here in chat."*
+2. When they paste the key, install it into `~/.zshenv` so every future shell — including the ones Claude Code spawns — picks it up automatically:
+   ```bash
+   echo 'export LINEAR_API_KEY=lin_api_THEIR_KEY_HERE' >> ~/.zshenv
+   ```
+   (Use `~/.bashrc` instead if the user is on bash.)
+3. Export it in the current shell too so the next tool call works without restart:
+   ```bash
+   export LINEAR_API_KEY=lin_api_THEIR_KEY_HERE
+   ```
+4. Verify with a harmless call: `node linear.mjs list-members`.
+
+**Never commit the key, never write it into `.env` or any project file** — `~/.zshenv` is the single source of truth.
+
+## Symbolic names (no UUIDs needed)
+
+The CLI resolves friendly names against `workspace.json`, so you rarely need raw UUIDs:
+
+```
+--team       ACME | "Acme Corp"  (team key or name)                          (or a UUID)
+--state      todo | backlog | "in progress" | "in review" | done | canceled   (or a UUID)
+--assignee   frontend | backend                                               (or a UUID)
+--labels     bug,frontend,feature  (comma-separated label names)              (or UUIDs)
+--priority   0-4  or  none | urgent | high | medium | low
+```
+
+`--team` selects which team a team-scoped command runs against, and `--state`/`--labels` then resolve against **that team's** states and labels. When `--team` is omitted it falls back to `$LINCTL_DEFAULT_TEAM` (a per-repo default) and then to `workspace.json`'s `defaultTeam`; if none are set you'll get an error listing the registered team keys. Workspace-wide commands (initiatives) don't need a team. Any value that's already a UUID is passed through untouched. Label names match case-insensitively with `-` and space interchangeable (`tech-debt` → `Tech Debt`), but `init` only registers the type and domain labels (`discovery`, `tech-debt`, `bug`, `feature`, `improvement`, `frontend`, `backend`, `db`) — apply the status flags (`client-request`, `Needs Clarification`, `agent blocked`) via the MCP server or by UUID. Project and milestone IDs are still UUIDs (pass them with `--project` / `--milestone`).
+
+## Creating Issues
+
+```bash
+# --project and --milestone are always required
+node linear.mjs create-issue \
+  --title 'Add user profile page' \
+  --description 'Create /profile page with user info and settings' \
+  --priority high \
+  --state backlog \
+  --assignee frontend \
+  --labels feature,frontend \
+  --estimate 3 \
+  --project 'project-uuid-here' \
+  --milestone 'milestone-uuid-here'
+
+# Create a bug report
+node linear.mjs create-issue \
+  --title 'Login redirect fails on Safari' \
+  --description 'Users on Safari not redirected after login. Reproduced on Safari 17.' \
+  --priority urgent \
+  --state backlog \
+  --assignee frontend \
+  --labels bug,frontend \
+  --project 'project-uuid-here' \
+  --milestone 'milestone-uuid-here'
+
+# Long descriptions: pass a file instead of inline text (no shell-escaping)
+node linear.mjs create-issue --title 'Investigate perf issue' --state backlog \
+  --description-file ./issue-body.md \
+  --project 'project-uuid' --milestone 'milestone-uuid'
+
+# Find the existing M project for the milestone this work falls under — do not create one.
+# (Prefer the MCP `get_initiative` with includeProjects; this lists them via the CLI.)
+node linear.mjs list-projects            # copy the [KEY] M<n> project's UUID
+PROJECT_ID='project-uuid-here'
+# Find the deliverable milestone the work falls under — do not create one in an M project.
+node linear.mjs list-milestones "$PROJECT_ID"   # copy the milestone's UUID
+MILESTONE_ID='milestone-uuid-here'
+node linear.mjs create-issue --title 'Investigate performance issue' --state backlog \
+  --project "$PROJECT_ID" --milestone "$MILESTONE_ID"
+```
+
+### Priority Values
+- `0` = No priority
+- `1` = Urgent
+- `2` = High
+- `3` = Medium
+- `4` = Low
+
+## Listing & Filtering Issues
+```bash
+# List all issues (pretty table by default)
+node linear.mjs list-issues
+
+# Filter by state type: backlog, unstarted, started, completed, canceled
+node linear.mjs list-issues started
+
+# Raw JSON output (for piping) — add --json to any list command
+node linear.mjs list-issues --json
+node linear.mjs list-issues started --json
+```
+
+## Updating Issues
+```bash
+# Move issue by status name
+node linear.mjs move-issue "issue-uuid" "In Progress"
+node linear.mjs move-issue "issue-uuid" "Done"
+
+# Assign to a team member by role
+node linear.mjs assign-issue "issue-uuid" frontend
+node linear.mjs assign-issue "issue-uuid" backend
+
+# General update — symbolic flags
+node linear.mjs update-issue "issue-uuid" --priority urgent --state todo
+
+# Or merge arbitrary raw JSON input with --raw
+node linear.mjs update-issue "issue-uuid" --raw '{"priority":1}'
+```
+
+## Issue Dependencies
+
+Prefer the MCP relations (see `SKILL.md`); these are the fallback:
+
+```bash
+# Create a "blocks" dependency (backend blocks frontend)
+node linear.mjs add-dependency "$BLOCKER_ISSUE_ID" "$BLOCKED_ISSUE_ID"
+
+# List all dependencies for an issue (both directions)
+node linear.mjs list-dependencies "$ISSUE_ID"
+
+# Remove a dependency by relation UUID (get UUID from list-dependencies)
+node linear.mjs remove-dependency "$RELATION_ID"
+```
+
+## Comments
+```bash
+# Add a comment to an issue
+node linear.mjs add-comment "$ISSUE_ID" --body "Comment body text here"
+
+# Long comment from a file (no shell-escaping)
+node linear.mjs add-comment "$ISSUE_ID" --body-file ./comment.md
+```
+
+## Searching
+```bash
+node linear.mjs search-issues "login bug"
+```
+
+## Projects & Milestones
+```bash
+# Create a new project (linked to an initiative)
+# Projects mirror the signed proposal's milestones ([KEY] M<n>) or a confirmed revision ([KEY] R<n>).
+# Never create one to hold work you couldn't place — see "Never invent a project".
+node linear.mjs create-project --name "[KEY] M1 — Milestone Name" --initiative "$INITIATIVE_ID" --description "Short description"
+
+# List all projects (pretty table with initiative, state, progress)
+node linear.mjs list-projects
+
+# List milestones within a project
+node linear.mjs list-milestones "$PROJECT_ID"
+
+# List issues grouped by milestone within a project
+node linear.mjs list-project-issues "$PROJECT_ID"
+
+# Raw JSON variants (for piping) — add --json
+node linear.mjs list-projects --json
+node linear.mjs list-milestones "$PROJECT_ID" --json
+node linear.mjs list-project-issues "$PROJECT_ID" --limit 200 --json
+
+# Only inside a confirmed R project: create a milestone for one of the revision's deliverables
+MILESTONE_ID="$(node linear.mjs create-milestone "$R_PROJECT_ID" "Deliverable name" | node -e "process.stdin.once('data',d=>console.log(JSON.parse(d).data.projectMilestoneCreate.projectMilestone.id))")"
+
+# Creating a project is only for a CONFIRMED out-of-scope revision — next R<n>, same initiative
+node linear.mjs create-project --name "[KEY] R1 — Revision Name" --initiative "$INITIATIVE_ID" --description "Short description"
+```
+
+## Bulk Moves (MCP has no equivalent)
+```bash
+# Move many issues to a milestone — 0.5s delay between calls so Linear doesn't drop writes.
+# Keep batches to ~9 issues and verify (list-project-issues) between batches.
+node linear.mjs batch-move-to-milestone "$MILESTONE_ID" "$ISSUE_ID_1" "$ISSUE_ID_2" "$ISSUE_ID_3"
+```
+
+## Raw GraphQL
+```bash
+# Escape hatch for anything else, e.g. a field save_issue didn't apply
+node linear.mjs api 'mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success } }' \
+  '{"id": "issue-uuid", "input": {"projectMilestoneId": "milestone-uuid"}}'
+```
+
+## Initiatives
+```bash
+# Create a new initiative (= a newly signed proposal; a repeat client gets another one)
+node linear.mjs create-initiative --name "ClientName" --description "Short description"
+
+# List all initiatives (pretty table with ID, status, description)
+node linear.mjs list-initiatives
+
+# Get full initiative detail by name (case-insensitive)
+node linear.mjs get-initiative-by-name "Northwind"
+
+# Get full initiative detail by ID
+node linear.mjs get-initiative "$INITIATIVE_ID"
+
+# Update initiative content (markdown) or description
+node linear.mjs update-initiative "$INITIATIVE_ID" --content-file ./initiative-notes.md
+node linear.mjs update-initiative "$INITIATIVE_ID" --description "Short description"
+
+# Add an external link (e.g., repo) as a resource on the initiative
+node linear.mjs add-initiative-link "$INITIATIVE_ID" "https://github.com/org/repo" "GitHub Repo"
+
+# Raw JSON of all initiatives
+node linear.mjs list-initiatives --json
+```
+
+## Info Commands
+```bash
+node linear.mjs list-states        # Workflow states
+node linear.mjs list-members       # Team members
+node linear.mjs list-labels        # Labels
+```

package/plugins/linear/skills/linear/examples/backend-data-model.md

@@ -0,0 +1,31 @@
+<!--
+Title:    Store the technician name and certification date on the visit
+Labels:   Feature, Backend, DB
+Estimate: M (3)
+Note:     Existing columns are named because they go away; nothing new is prescribed —
+          no column list, types, or indexes. The Backend lead designs the schema.
+-->
+
+**Context:** [Our thinking — Why certification moves off the technician](https://linear.app/<workspace>/document/<our-thinking-doc>) · [How they operate — Where certification dates come from](https://linear.app/<workspace>/document/<how-they-operate-doc>)
+
+---
+
+## Context
+
+The customer keeps technician certification dates in their HR system and doesn't want to maintain technician records in two places. They've asked to just enter the technician's name and certification date on each visit, instead of picking from a technician list.
+
+## Functionality
+
+* Store the technician's name on the visit as free text. It's optional — a visit without a name is an unassigned slot (what we call a slot visit today).
+* Store a certification date on the visit, entered by the user. Use it to work out the rate bracket and whether supervision is required, as of the job's scheduling date.
+* If the job type requires certification and the visit has no date, flag it the same way we flag an uncertified technician today. Don't guess.
+* Remove `visits.technician_id` and the technician/slot visit kinds. Every visit has the same shape, with an optional name.
+* This is greenfield, so there's no migration of existing technician visits. Update the seeds to use named visits.
+
+## Acceptance criteria
+
+- [ ] A visit can be saved with a name and a date, with just a name, or with neither
+- [ ] Rates and supervision are calculated from the visit's certification date
+- [ ] Saving the schedule keeps the name and date on every visit
+- [ ] Table and column comments explain the new columns and what they replace
+- [ ] Tests written

package/plugins/linear/skills/linear/examples/backend-feature.md

@@ -0,0 +1,30 @@
+<!--
+Title:    Send a quote by email from the platform
+Labels:   Feature, Backend
+Estimate: M (3)
+Relation: KEY-141 (the sending-address decision) is linked inline, not narrated
+-->
+
+**Context:** [Our thinking — Recipients and template](https://linear.app/<workspace>/document/<our-thinking-doc>) · [How they operate — Customer contacts](https://linear.app/<workspace>/document/<how-they-operate-doc>)
+
+---
+
+## Context
+
+Dispatchers say getting a quote out to a customer takes too long. Right now they generate it, download it, and email it from Outlook. They want to send it without leaving the platform.
+
+## Functionality
+
+* Send an existing quote to one or more recipients, with the quote PDF attached (the one from `/api/jobs/:id/quotes/:quoteId/pdf`).
+* Recipients have to be contacts of the job's customer (`contacts` rows with that `customer_id`). Contacts without an email address can't be picked.
+* Send from the logged-in user's own email address, as decided in KEY-141.
+* The frontend sends the subject and body — it fills in a default from a template, and the user can edit it. The backend sends the subject and body exactly as submitted and doesn't replace the body.
+* Reject the send if any recipient isn't a contact of the job's customer.
+* We're not keeping a record of sends for now — what was sent, to whom, when, or whether it was delivered. That's out of scope for this revision.
+
+## Acceptance criteria
+
+- [ ] Each valid recipient gets the quote, sent from the user's own address
+- [ ] Sending to someone who isn't a contact of the job's customer fails
+- [ ] Sending to a contact with no email address fails
+- [ ] Tests written

package/plugins/linear/skills/linear/examples/bug.md

@@ -0,0 +1,30 @@
+<!--
+Title:    Invoices list total doesn't include credits
+Labels:   Bug, Backend
+Estimate: S (2)
+Note:     The title states the broken behavior — no "Fix:" prefix. Root cause and location
+          come from reading the code on main, not from the reporter's guess.
+-->
+
+## Bug
+
+The invoices list shows the total before credits. So an invoice for $1,000 with a $200 credit shows $1,000 in the list but $800 on the invoice page. The invoice page is right.
+
+## Root cause
+
+The list endpoint adds up `invoice_lines.amount` directly. The detail endpoint uses `getInvoiceTotals`, which takes the credits off.
+
+## Steps to reproduce
+
+1. Apply a credit to any open invoice.
+2. Open the invoices list.
+
+## Likely location
+
+* `server/api/invoices/index.get.ts` (the list total)
+* `server/utils/invoice-totals.ts` (`getInvoiceTotals`, which does it correctly)
+
+## Acceptance criteria
+
+- [ ] The list and the invoice page show the same total, with or without a credit
+- [ ] Tests written

package/plugins/linear/skills/linear/examples/discovery.md

@@ -0,0 +1,34 @@
+<!--
+Title:    Decide what hours to check overtime thresholds against
+Labels:   Discovery, Backend
+Estimate: S (2)
+Note:     This is an open question only because the requester said it was one — the agent
+          never decides on its own that something needs the client. Each option includes
+          its trade-offs; the answer gets folded into the dependent issues, not logged here.
+-->
+
+**Context:** [Our thinking — Overtime thresholds](https://linear.app/<workspace>/document/<our-thinking-doc>) · [How they operate — How the system works today](https://linear.app/<workspace>/document/<how-they-operate-doc>)
+
+---
+
+## Context
+
+Overtime has to keep working once technician records go away, and it depends on a number that's only stored on those records.
+
+A job type's rate item can have a `min_weekly_hours` threshold. Below it, the base rate applies; above it, the extra hours are paid at the overtime rate.
+
+Right now we check the threshold against `technicians.weekly_hours`, which is the technician's **total** week across all their jobs. That's different on purpose from `visits.hours`, which is just the hours on one visit — the scheduler shows a warning when they don't match (KEY-92), since a technician who works for two customers has more hours in total than on either visit.
+
+## Open question
+
+What should we compare the threshold against instead?
+
+* **The visit's own `hours`.** It's already there, so there's nothing new to enter. The downside: a technician split across two customers gets judged on each share separately, so they might miss a threshold they actually meet.
+* **A second hours field on the visit.** Keeps today's distinction — say, "40 hours a week in total" next to the 20 hours on this visit — but it's one more field to fill in.
+
+If the customer never actually splits a technician across customers, the first option is the answer.
+
+## Acceptance criteria
+
+- [ ] We have an answer from the customer, and it's written up in the project's "Our thinking" doc
+- [ ] The issues that depend on this are updated with the answer

package/plugins/linear/skills/linear/examples/frontend-feature.md

@@ -0,0 +1,36 @@
+<!--
+Title:    Pick the job type on the job and enter the technician name and date on each visit
+Labels:   Feature, Frontend
+Estimate: L (5)
+Note:     Every path in UI Notes was verified in the repo on main. If the repo can't be
+          checked, leave paths out entirely — no "To Determine" / TBD section.
+-->
+
+**Context:** [Our thinking — What that means](https://linear.app/<workspace>/document/<our-thinking-doc>) · [How they operate — How the system works today](https://linear.app/<workspace>/document/<how-they-operate-doc>)
+
+---
+
+## Context
+
+Dispatchers set the same job type on every visit of a job, which is repetitive and easy to get wrong. They've also asked to stop picking technicians from a list here — they keep that list in their HR system. They want to pick the job type once for the job, and type the technician's name and certification date on each visit.
+
+## Requirements
+
+- [ ] The job editor lets you pick one job type (or none) next to the service category. No job type means no restrictions.
+- [ ] Each visit has a free-text technician name. If it's blank, the visit is an unassigned slot, so the technician/slot toggle goes away.
+- [ ] Each visit has a certification date, with a date picker.
+- [ ] The visit shows the rate that date gives. If the job type needs a date and there isn't one, show that clearly instead of showing $0.
+- [ ] Remove technician search/select from the scheduler.
+
+## UI Notes
+
+* Components: `app/components/JobEditor.vue` (job type picker), `app/components/VisitRow.vue`, `app/components/VisitRatePreview.vue` — checked in the repo.
+* Pages: `app/pages/jobs/[id]/edit.vue`, `app/pages/jobs/[id]/index.vue`.
+* VoltSelect for the job type, VoltInputText for the name, VoltDatePicker for the date.
+* Follow DESIGN_LANGUAGE.md — zinc palette, no decorative shadows.
+
+## Acceptance criteria
+
+- [ ] You can schedule a job from start to finish with a job type and a mix of named and unnamed visits, and the pricing comes out right
+- [ ] Nothing in the scheduler references technician records anymore
+- [ ] Tests written

package/plugins/linear/skills/linear/examples/right-and-wrong.md

@@ -0,0 +1,138 @@
+# Issue Writing — Right and Wrong
+
+Each pair is a real correction made on a drafted issue. ❌ is what agents tend to write; ✅ is how we write it.
+
+## Titles
+
+```
+❌ Fix: Invoice list total wrong
+❌ [ACME] UI: Add quote email
+❌ Spike: overtime hours
+✅ Invoices list total doesn't include credits
+✅ Send a quote by email from the platform
+✅ Decide what hours to check overtime thresholds against
+```
+
+No prefixes at all — no client, no domain, no `Fix:` / `Chore:` / `Spike:`. The team already identifies the client, and the labels show the type and domain. Just say what the issue is about.
+
+## Framing
+
+```
+❌ ## Context
+   Add a Send button to the quote page that emails the PDF through Resend.
+
+❌ ## Context
+   Dispatchers want to email quotes from the platform, which will improve
+   customer satisfaction and reduce churn.
+
+❌ ## Context
+   There's nowhere in the app to attach a quote to an email, so dispatchers
+   print each quote and fax it to the customer.
+
+✅ ## Context
+   Dispatchers say getting a quote out to a customer takes too long. Right now
+   they generate it, download it, and email it from Outlook. They want to send
+   it without leaving the platform.
+```
+
+Frame the issue around the intent — who has the problem and what they're trying to get done — not the fix. The first ❌ goes straight to the solution. The second is framed around intent, but it includes a reason nobody gave. The third makes up a workaround: nobody said anything about faxing, the agent guessed it because the feature doesn't exist. The reason and the current workaround both come from the requester. The ✅ mentions Outlook because the dispatchers said that's what they do. If the requester didn't tell you, ask them.
+
+## Describing things literally
+
+```
+❌ The generated quote PDF is currently silent on tax.
+❌ The list endpoint ignores credits and doesn't know about partial payments.
+
+✅ The generated quote PDF doesn't include a tax line.
+✅ The list endpoint doesn't subtract credits or partial payments.
+```
+
+Documents, code, and systems don't speak, know, want, or ignore anything. Say what they do or what they contain.
+
+## Backend: behavior, not schema
+
+```
+❌ Add a `quote_sends` table:
+   - id (bigint, PK)
+   - quote_id (bigint, FK → quotes.id, indexed)
+   - status (text, CHECK in ('queued','sent','failed'))
+
+✅ * Recipients have to be contacts of the job's customer. Contacts without an
+     email address can't be picked.
+   * We're not keeping a record of sends for now. That's out of scope for this
+     revision.
+```
+
+Say what needs to happen, the business rules, and what's out of scope. The Backend lead decides the tables, columns, types, indexes, and constraints. It's fine to mention columns and endpoints that already exist — just don't design new ones.
+
+## Status and enum fields
+
+```
+❌ status: `draft`, `sent`, `accepted`, or `expired`
+
+✅ We need to be able to tell whether a quote is still being edited, sent but
+   not answered yet, accepted, or expired. Only quotes still being edited can
+   change, and the jobs list filters on the other three.
+```
+
+Explain what the status needs to tell apart and what depends on it. Let the implementer name the values.
+
+## Grounding in the repo
+
+```
+❌ Lift the rate math out of `useMockRates.ts` on the wireframe branch.
+❌ Per the plan in KEY-29, rates will come from the job type — that's wrong,
+   instead...
+❌ ## To Determine
+   - [ ] Which page renders the jobs list?
+
+✅ The list endpoint adds up `invoice_lines.amount` directly. The detail
+   endpoint uses `getInvoiceTotals`, which takes the credits off.
+```
+
+Describe what the code on `main` does today, and check it. Don't point at a wireframe branch or a scratch file the assignee might not have — paste what matters into the issue instead. Don't frame the issue around another issue's plan. If you can't check the repo, leave file paths out rather than adding a TBD section.
+
+## Links between issues
+
+```
+❌ Upstream data capture lives in Scheduling: KEY-14 (captures the visit
+   hours). Backend generation is handled by KEY-15 (blocking).
+❌ see the Job Scheduling project
+❌ ## Sub-issues
+   - KEY-201
+   - KEY-202
+
+✅ ...the scheduler shows a warning when they don't match (KEY-92), since a
+   technician who works for two customers...
+```
+
+Link another issue inline, by its identifier, the first time you mention something it covers — once per issue is enough. Dependencies go in Linear relations, not in the text. Linear already shows sub-issues, so don't list them. Anything you name — a project, an issue, a doc — should be a link.
+
+## Open questions
+
+```
+❌ ## Open questions
+   - Should the send be logged? (needs a meeting with the client)
+   - Which template should the default body use?
+
+✅ (asked the requester before writing — both answers are now in the body)
+   * We're not keeping a record of sends for now...
+   * The frontend sends the subject and body...
+```
+
+Ask the requester everything before you write. Only put a question in the issue if the requester tells you it's an open question — don't decide on your own that it needs a meeting.
+
+## After a clarifying answer
+
+```
+❌ ## Functionality
+   * Send to a single recipient.
+   ...
+   ## Update (2025-05-01) — clarified with requester
+   * Actually, more than one recipient per send.
+
+✅ ## Functionality
+   * Send an existing quote to one or more recipients...
+```
+
+The body should always read as the current spec. When an answer changes something, rewrite that part so it reads as if it always said that. No "Update", "Decisions", or "Clarifications" sections, no dated headers, and no struck-through text.

package/plugins/linear/skills/linear/examples/small-improvement.md

@@ -0,0 +1,24 @@
+<!--
+Title:    Let app pages use the full window width
+Labels:   Improvement, Frontend
+Estimate: XS (1)
+Note:     A small, fully-understood change stays small: one requirement, one criterion.
+          No doc header — this project has no "Our thinking" / "How they operate" docs.
+-->
+
+## Context
+
+People on wide screens have asked for more room. Every app page is capped at `max-w-6xl` and centered, so tables and the schedule view get squeezed while both sides of the screen stay empty.
+
+## Requirements
+
+- [ ] Remove `max-w-6xl mx-auto` from `PageHeader` and from each page's filter bar and main content wrapper. Keep the side padding as it is.
+
+## UI Notes
+
+* Component: `app/components/PageHeader.vue`
+* Pages: customers, jobs (index, `[id]`), invoices, schedule, settings, users
+
+## Acceptance criteria
+
+- [ ] Pages and their headers stretch to the full window width, with the same side padding as before

package/plugins/linear/skills/linear/tech-stack.md

@@ -270,4 +270,4 @@ The `NUXT_` prefix auto-binds to `runtimeConfig` in `nuxt.config.ts`.
 |------|---------|
 | **pre-commit** | Format (oxfmt) + lint fix (oxlint) on staged `.ts/.vue/.js` files |
 | **pre-push** | Backend tests, frontend tests, typecheck, lint (in parallel) |
-| **post-merge** | Auto `yarn install` if `package.json`/`yarn.lock` changed; warns if new migrations detected |
+| **post-merge** | Auto `yarn install` if `package.json`/`yarn.lock` changed; prints a warning if new migrations are detected |