@devenius/junamis-skills 0.0.0-stage → 1.1.0

package/library/skills/decision-record/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: decision-record
+version: "1.0.0"
+idempotent: false
+description: Use when the user makes a decision that should bind future work ("we're using X", "never do Y here", "going with Z"), or before acting on a request that may conflict with an earlier decision. Writes ADR-style records to docs/decisions/ and flags conflicts instead of silently overriding them. Do not use for open questions or for suggestions the user has not accepted.
+---
+
+# decision-record
+
+Turn a user's decision into a durable record, and check new requests against the records that already exist.
+
+## Mode A: record a decision
+
+Use when the user states a decision.
+
+1. Confirm the decision in one sentence and ask nothing else unless the wording is ambiguous.
+2. Find the next number: highest `NNNN` in `docs/decisions/` plus one, starting at `0001`.
+3. Write `docs/decisions/NNNN-slug.md`:
+
+```markdown
+# NNNN. <Title in imperative form>
+
+Status: Accepted
+Date: <YYYY-MM-DD>
+Supersedes: none
+
+## Context
+Why this came up. Two to four sentences.
+
+## Decision
+The decision, in one or two sentences, stated plainly.
+
+## Consequences
+What this makes easier, what it makes harder, what it rules out.
+```
+
+4. Report the file path and the one-line decision.
+
+## Mode B: check a request against decisions
+
+Use before any skill that changes code or config.
+
+1. List titles in `docs/decisions/` with `Status: Accepted`.
+2. If a request contradicts one, stop. Report the record number, the conflict, and the two options: follow the record, or record a superseding decision.
+3. If the user chooses to supersede, write a new record with `Supersedes: NNNN`. Change the old record's status to `Superseded by NNNN`. Do not edit its body.
+4. If the request is merely different and does not contradict, proceed and mention the related record.
+
+## Gotchas
+
+- Record only decisions the user made. A suggestion from an agent is `Status: Proposed` until the user accepts it, and it does not bind work.
+- Never rewrite a decision's body. History is the point.
+- One decision per file. If a message holds three decisions, write three files.
+- If `docs/decisions/` does not exist, create it. Do not ask.
+
+## Finish
+
+```yaml
+agent: decision-record
+job: record or check decision
+status: complete | needs-decision
+artifacts:
+  - path: docs/decisions/NNNN-slug.md
+    kind: created
+findings:
+  - id: F1
+    severity: high
+    summary: request conflicts with decision NNNN
+    evidence: docs/decisions/NNNN-slug.md
+decisions_owed:
+  - follow NNNN, or supersede it?
+next: user
+```
+
+Omit `findings` and set `next` to the calling skill when there is no conflict.

package/library/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: dependency-upgrade
+version: "1.0.0"
+idempotent: false
+description: Use to upgrade one dependency to a named version, or to resolve a security advisory for one package. Reads the upstream changelog, lists breaking changes, applies the bump in isolation, and runs the project's tests. Do not use to upgrade several packages at once, to change the package manager, or for transitive pins nobody asked about.
+---
+
+# dependency-upgrade
+
+Upgrade exactly one package, prove nothing else changed, and hand the proof to the tests.
+
+## Inputs
+
+- Package name and target version (or "latest stable").
+- Reason: feature need, advisory ID, or routine maintenance.
+
+If the target is missing, ask for it. Do not pick "latest" silently for a major version.
+
+## Steps
+
+1. **Baseline.** Run the project's test command and record the result. If it fails before any change, stop with `status: blocked`.
+2. **Read the upstream.** Fetch the package's changelog or release notes for every version between current and target. Record breaking changes. Note the source URL.
+3. **Check peers.** Read `peerDependencies` of the new version. Report any conflict with installed packages.
+4. **Apply.** Change only that package's version constraint. Install with the project's package manager so the lockfile updates.
+5. **Diff the lockfile.** Confirm the changed entries are the target package and its own dependencies. Anything else is a finding.
+6. **Verify.** Run the test command, then the build command if one exists. Compare with the baseline.
+7. **Code impact.** Search the repo for imports and API names listed as breaking. Fix only call sites that the breaking changes require.
+
+## Gotchas
+
+- A major version bump is a decision. If the changelog lists breaking changes, set `status: needs-decision` unless the user already asked for that version.
+- Lockfile churn across unrelated packages means the install did more than asked. Revert and report.
+- Do not add `overrides` or `resolutions` to force a version unless the user approves. They hide conflicts.
+- An advisory fix needs the fixed version confirmed in the advisory, not guessed from the package name.
+
+## Finish
+
+```yaml
+agent: dependency-upgrade
+job: upgrade <package> to <version>
+status: complete | blocked | needs-decision | failed
+artifacts:
+  - path: package.json
+    kind: updated
+  - path: <lockfile>
+    kind: updated
+findings:
+  - id: F1
+    severity: high
+    summary: breaking change <what> affects <file>
+    evidence: <changelog url>, <file:line>
+decisions_owed:
+  - approve major version bump to <version>?
+next: test
+```
+
+Set `next: test` when the verification passed. Use `next: user` when blocked or when the decision is owed.

package/library/skills/deploy-verify/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: deploy-verify
+version: "1.0.0"
+idempotent: true
+description: Use after the user has deployed, to confirm the live or staging environment is healthy. Probes health and readiness endpoints with GET requests only, runs the smoke checks listed in the release notes, and reports pass or fail with evidence. Do not use to deploy, to send write requests, or to log in with real user credentials.
+---
+
+# deploy-verify
+
+Confirm the deploy is alive and the critical paths respond. Read only.
+
+## Inputs
+
+- Base URL of the environment (ask if not given).
+- The release notes file, `docs/releases/<version>.md`, for the version being verified.
+
+## Steps
+
+1. **Health.** `GET <base>/health` (or the endpoint the project documents). Expect 200 within 2 seconds.
+2. **Readiness.** `GET <base>/ready` if it exists. Expect 200. A 200 on health with a failing ready means the dependencies are down: report it as a finding.
+3. **Version.** If the health response includes a version or commit, compare with the release. A mismatch means the old version is still serving: fail.
+4. **Smoke.** Read the smoke list from the release notes. For each path, send a GET and record the status code. Do not send POST, PUT, PATCH, or DELETE.
+5. **Errors.** Sample the error rate from logs or the platform if the user has given access. Otherwise say it was not checked.
+6. **Decide.** All checks pass: `complete`. Any critical path fails: `failed`, and set `next: rollback`.
+
+## Gotchas
+
+- Health returning 200 does not prove the app works. Check at least one real path.
+- Do not follow redirects into a login page and call that a pass. Report the redirect.
+- A preview URL is not production. Name which environment was checked.
+- Do not retry a failing POST to "see if it works now". This skill never writes.
+
+## Finish
+
+```yaml
+agent: deploy-verify
+job: verify <version> at <base>
+status: complete | failed
+artifacts:
+  - path: docs/releases/<version>.md
+    kind: read-only
+findings:
+  - id: F1
+    severity: critical
+    summary: GET /checkout returns 500
+    evidence: "<timestamp> GET /checkout -> 500"
+decisions_owed: []
+next: rollback
+```
+
+Set `next: none` on success. Set `next: rollback` only on a critical failure, and the orchestrator will still ask the user before rolling back.

package/library/skills/document/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: document
+version: "1.0.0"
+idempotent: false
+janitor_only: true
+description: Use when the design registry prose, Known gaps, or coverage needs a janitor pass. Reorganizes and reconciles what deltas and code already produced; never introduces new facts, promotes drafts, or edits external skills.
+---
+
+# document
+
+You are the design registry janitor. You may reorganize, normalize, and reconcile the registry so a fresh reader can answer "what is here" and "what needs adjusting". You do not invent the answer.
+
+## Rules
+
+- **No new facts.** Every sentence you keep or move must already be in a design delta, the current design file, or the code it points at. If a fact is missing, record it in `## Known gaps` as a question, do not write it as truth.
+- **No promotion.** Never change `status: draft` to `active`, and never resolve a `needs_review` surface. Only a delta or an operator may do that.
+- **No checksum edits by hand.** Run `junamis-design-registry validate` after a prose pass. If a body changed, apply the change through a design delta so `design_checksum`, `version`, and the change log stay correct.
+- **No external edits.** The external `document` skill is not yours to change. This internal skill is the janitor override.
+- **No scope changes.** You do not add a surface, remove a surface, or change `code_paths`. Add a gap instead.
+
+## Steps
+
+1. **Read the registry.** Run `junamis-design-registry validate`. Stop on any error and report the exact file and line.
+2. **Load the target surfaces.** Use `junamis-design-registry load --surface <surface_id>` for each surface in the request. Read the body; the frontmatter is metadata, not prose.
+3. **Normalize prose.** Fix duplicated sentences, stale tense, and accidental aspiration in `## Current state`. Keep every fact. Do not add a fact to make a paragraph read better.
+4. **Reconcile Known gaps against code.** A gap that the code already satisfies becomes a delta that removes the line. A gap the code does not satisfy stays. A new observation becomes a new gap bullet, phrased as a question.
+5. **Audit coverage.** Run `junamis-design-registry drift`. Report overlaps always. Report unclaimed code files. When `bootstrap_complete` is false, say that enforcement is off; do not flip the flag yourself.
+6. **Regenerate.** If you changed a surface through a delta, run `junamis-design-registry index --write` and `junamis-design-registry validate`. Then confirm the index is byte-stable by generating it twice.
+7. **Report.** Name every surface you touched, every gap you kept, and every gap you removed with the delta that removed it.
+
+## Gotchas
+
+- A prose edit that changes the body without a delta breaks the checksum guard. Use a delta.
+- `## Known gaps` must be explicit. `- None` is valid; an empty section is not.
+- A surface with `status: deprecated` or `needs_review` does not accept a delta. Report it, do not force it.
+- Coverage overlaps are always worth reporting, even when enforcement is off.
+- `INDEX.md` is derived. Never edit it by hand.
+
+## Finish
+
+```yaml
+agent: document
+job: <one line>
+status: complete | blocked | needs-decision | failed
+artifacts:
+  - path: <repo-relative path>
+    kind: created | updated | read-only
+findings: []
+decisions_owed: []
+next: orchestrator
+```

package/library/skills/env-doctor/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: env-doctor
+version: "1.0.0"
+idempotent: true
+description: Use when the project will not install, build, or run locally, or before starting work on an unfamiliar machine. Checks runtime and package-manager versions against the project's declared requirements, lockfile presence, and which environment variable names the code needs. Writes docs/env-report.md. Do not use to install software or to set secret values.
+---
+
+# env-doctor
+
+Diagnose the local environment and report what is wrong, with the exact fix command. Change nothing.
+
+## Checks
+
+Run each check. Record pass, fail, or unknown with evidence.
+
+1. **Runtime.** Read `engines` in `package.json` (or `.nvmrc`, `.tool-versions`). Compare with `node --version`. Fail if the installed major is below the minimum.
+2. **Package manager.** Read `packageManager` in `package.json`. Compare with the tool actually on PATH. Fail on mismatch.
+3. **Lockfile.** Exactly one lockfile should exist for the declared manager. Fail if zero, or if more than one.
+4. **Env names.** Find env var names the code reads (`process.env.NAME`, `import.meta.env.NAME`, or the project's config loader). Compare with `.env.example`. Report names missing from the example. Never print values, and never open `.env` for reading values.
+5. **Services.** Only check services the user has named or the project config declares. Report reachability as pass or fail. Do not start services.
+6. **Scripts.** Confirm the scripts the project's docs name (`dev`, `build`, `test`) exist in `package.json`.
+
+## Output
+
+Write `docs/env-report.md`:
+
+```markdown
+# Environment report
+
+Checked: <YYYY-MM-DD HH:MM>
+
+| Check | Result | Evidence |
+|---|---|---|
+| Runtime | pass | node 26.0.0 >= 26 |
+
+## Fixes
+- <exact command for each failure>
+```
+
+## Gotchas
+
+- Read `engines` before you decide a version is wrong. Projects pin different minimums.
+- `.env` contains secrets. Compare names only, using `grep -o` on keys or the example file.
+- Do not install, upgrade, or switch versions. Print the command and let the user run it.
+- A missing `.env.example` is a finding. A missing `.env` is not, unless the code requires it at startup.
+
+## Finish
+
+```yaml
+agent: env-doctor
+job: environment check
+status: complete | failed
+artifacts:
+  - path: docs/env-report.md
+    kind: created
+findings:
+  - id: F1
+    severity: high
+    summary: <failing check>
+    evidence: <command and output>
+decisions_owed: []
+next: user
+```
+
+Use `status: failed` when a check that blocks running fails. Set `next` to the originating skill when every check passes.

package/library/skills/frontend/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: frontend
+version: "1.0.0"
+idempotent: false
+description: Use when building or reviewing frontend UI in a SaaS app. Detects the workspace stack (React, Next.js, Vue, Svelte) and component library (shadcn/ui, Radix, MUI, Chakra). Uses shadcn components and design tokens. Use when the task involves UI components, layouts, forms, tables, modals, or styling. Do not use for backend or API work.
+---
+
+# frontend
+
+Build frontend UI that matches the project's stack and component conventions. Detect first, then build.
+
+## Inputs
+
+- The project root. Read `package.json` for framework and UI library.
+- If the project uses Next.js, coordinate with the `nextjs` agent for routing, data fetching, and Server/Client boundaries.
+- `components.json` if it exists (shadcn configuration).
+- `tailwind.config.*` or CSS variables for design tokens.
+
+## Stack detection
+
+1. **Framework.** Check `package.json` dependencies: `next` (Next.js), `react` (React), `vue` (Vue), `svelte` (SvelteKit). If multiple, note the primary.
+2. **UI library.** Check for `@radix-ui/*`, `@mui/*`, `@chakra-ui/*`, or `shadcn` in dependencies. Check for `components.json` (shadcn).
+3. **Styling.** Tailwind (`tailwindcss`), CSS modules, or styled-components.
+4. **State.** Check for `zustand`, `redux`, `jotai`, `pinia`, or React Context usage.
+
+## When shadcn/ui is present
+
+- Use `npx shadcn@latest add <component>` to add components. Do not hand-write what shadcn provides.
+- Compose with `cva` variants and `cn()` for conditional classes.
+- Use semantic design tokens (`bg-background`, `text-foreground`), never hardcoded colors.
+- Check `components.json` for the `style` (default, new-york) and `iconLibrary`.
+
+## When shadcn is not present
+
+- Use the project's existing component library. Do not introduce shadcn without asking.
+- Follow the existing patterns for variants, spacing, and theming.
+
+## General rules
+
+1. **Accessible by default.** Labels, focus states, keyboard navigation, ARIA where needed.
+2. **Responsive.** Mobile-first with Tailwind breakpoints. Test at 375px, 768px, 1024px, 1440px.
+3. **Loading and empty states.** Every data-driven component needs skeleton, empty, and error states.
+4. **Forms.** Use react-hook-form + zod with shadcn Form components. Inline errors, accessible fields.
+5. **Tables.** TanStack Table + shadcn Table. Sorting, filtering, pagination, selection.
+
+## Gotchas
+
+- Do not mix component libraries. If the project uses shadcn, do not add MUI components.
+- shadcn components are copied into the project, not imported from a package. Edit them in place.
+- `components.json` must exist before running `shadcn add`. If it doesn't, run `shadcn init` first.
+- Dark mode requires CSS variables for both light and dark themes. Check `globals.css`.
+
+## Finish
+
+```yaml
+agent: frontend
+job: frontend UI for <scope>
+status: complete
+artifacts: []
+findings: []
+decisions_owed: []
+next: none
+```

package/library/skills/handoff/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: handoff
+version: "1.1.0"
+idempotent: true
+description: Use to save the current session state to .junamis/handoff.md at the end of work, or to read it at the start of a session so work resumes without re-explaining. Use when the user says "save where we are", "pick up", "continue", or when a session is ending. Do not use for per-step status; that is the HANDOFF block every skill ends with.
+---
+
+# handoff
+
+Keep one short file that lets a fresh agent continue. The file is the memory. The chat is not.
+
+## Write (end of session)
+
+Overwrite `.junamis/handoff.md` with exactly these sections, in this order:
+
+Only the orchestrator fills `## Suggested commit`. A specialist must not run this skill or write that section.
+
+```markdown
+# Handoff
+
+Updated: <YYYY-MM-DD HH:MM>
+
+## Goal
+One sentence.
+
+## Current state
+What is done, in three bullets at most. Name the files that changed.
+
+## Decisions in force
+Links to docs/decisions/ entries that govern this work. "None" if none.
+
+## Open questions
+Questions only the user can answer. "None" if none.
+
+## Next step
+One concrete action, with the skill that does it.
+
+## Suggested commit
+Orchestrator only. Leave this section untouched if you are not the orchestrator.
+Message: `<type(scope): summary>`
+Files:
+- `<repo-relative path>`
+Rationale: <one line>
+State: proposed | committed <sha> | none
+
+## Do not
+Things a fresh agent would otherwise repeat or break. "Nothing recorded" if none.
+```
+
+## Read (start of session)
+
+1. Read `.junamis/handoff.md`. If it is missing, say so and run `route` on the user's request.
+2. Reply with at most five lines: goal, state, next step, open questions.
+3. Check each path named in "Current state" still exists. Report any that do not.
+4. Continue from "Next step" only after the user confirms, or when the user's request matches it.
+5. If you are the orchestrator, read `## Suggested commit` and reuse it when the user says "commit". If you are not the orchestrator, ignore it.
+
+## Gotchas
+
+- Keep it under 60 lines. A handoff that needs scrolling is a transcript, not a handoff.
+- Never paste secrets, tokens, or env values. Name the variable, not the value.
+- Do not record what was tried and failed unless it will stop the next agent. Put that under "Do not".
+- Overwrite, do not append. Old state is in git and in the decision records.
+- The `## Suggested commit` section is orchestrator-only. Never write or change it from any other agent. The orchestrator fills it at the end of every task with a Conventional Commits message, the exact files, a one-line rationale, and a state.
+- `State: proposed` is not approval. The orchestrator commits only after the user asks.
+
+## Finish
+
+```yaml
+agent: handoff
+job: save or load session state
+status: complete
+artifacts:
+  - path: .junamis/handoff.md
+    kind: created | updated | read-only
+findings: []
+decisions_owed: []
+next: none
+```

package/library/skills/incident-response/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: incident-response
+version: "1.0.0"
+idempotent: false
+description: Use when production is failing right now: outage, error spike, users reporting breakage, data looks wrong in live. Orders the work as stabilize first, then gather evidence read-only, then hypothesize, then record the incident. Do not use for a bug in development or staging; that is debug. Do not change production data from this skill.
+---
+
+# incident-response
+
+Stop the bleeding first. Understand it second. Write it down throughout.
+
+## Order (do not reorder)
+
+1. **Stabilize.** Ask what mitigations exist: feature flag, rollback, traffic shift, disabling a job. Recommend the smallest one that stops user harm. Do not execute it yourself. Routing to `rollback` requires user confirmation.
+2. **Timeline.** Establish when it started, what changed just before (deploys, config, migrations, dependency bumps), and the first symptom. Use `git log` and the release notes.
+3. **Evidence.** Read logs, error reports, and metrics the user provides. Read-only. Quote the lines you rely on with timestamps.
+4. **Hypotheses.** List at most three causes, each with the evidence for and against. Rank them.
+5. **Confirm.** Pick the top hypothesis only if evidence confirms it. Otherwise state what data would confirm it and ask for it.
+6. **Record.** Write `docs/incidents/<YYYY-MM-DD>-<slug>.md`:
+
+```markdown
+# <Title>
+
+Status: open | mitigated | resolved
+Started: <time>   Detected: <time>   Mitigated: <time or pending>
+
+## Impact
+Who was affected and how.
+
+## Timeline
+- <time>: <event, with source>
+
+## Evidence
+- <quoted line, source, time>
+
+## Hypotheses
+1. <cause>: for <...>, against <...>
+
+## Mitigation and next steps
+```
+
+## Gotchas
+
+- Do not guess a root cause in the first reply. Ask for the logs.
+- Do not run a fix against production without the user's explicit go-ahead in this session.
+- Do not edit or delete production records to "clean up" a symptom. Record it.
+- A rollback that does not fix the symptom means the cause is not the release. Say so.
+- Keep secrets, tokens, and customer data out of the incident record. Redact.
+
+## Finish
+
+```yaml
+agent: incident-response
+job: triage <incident>
+status: complete | needs-decision | blocked
+artifacts:
+  - path: docs/incidents/<YYYY-MM-DD>-<slug>.md
+    kind: created
+findings:
+  - id: F1
+    severity: critical
+    summary: <most likely cause, with confidence>
+    evidence: <log line, timestamp>
+decisions_owed:
+  - approve mitigation: <action>?
+next: user
+```
+
+Use `next: debug` only when the evidence points to a code defect and the user has approved a fix path. Otherwise `next: user`.

package/library/skills/nestjs/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: nestjs
+version: "1.0.0"
+idempotent: false
+description: Use when building or reviewing a NestJS application. Covers module structure, dependency injection, guards, pipes, interceptors, exception filters, and database integration. Use when the project has a nest-cli.json or @nestjs/core dependency. Delegates deep NestJS patterns to the external nestjs-best-practices skill. Do not use for non-NestJS backends.
+---
+
+# nestjs
+
+Build NestJS applications with clean module boundaries and proper dependency injection. Deep patterns come from the external `nestjs-best-practices` skill.
+
+## Inputs
+
+- The project root. Confirm `@nestjs/core` is in `package.json` dependencies.
+- `nest-cli.json` and `src/` directory.
+
+## Rules
+
+1. **One module per feature.** Each feature has its own module with controller, service, and DTOs. No god modules.
+2. **Dependency injection.** Use constructor injection. Never instantiate services with `new` outside of factories.
+3. **Guards for auth.** Use `@UseGuards()` for authentication and authorization. Never check auth inside a service.
+4. **Pipes for validation.** Use `ValidationPipe` with DTOs. Never validate manually in controllers.
+5. **Interceptors for cross-cutting.** Logging, caching, and transformation go in interceptors, not services.
+6. **Exception filters.** Use global exception filters for consistent error responses. Never catch and rethrow in controllers.
+7. **Repository pattern.** Services depend on repository interfaces, not ORM directly. Use TypeORM or Prisma through a repository.
+8. **Testing.** Unit test services with mocked repositories. E2E test controllers with a test module.
+
+## Delegation
+
+For deep NestJS patterns (CQRS, microservices, WebSockets, GraphQL, advanced DI), load the external `nestjs-best-practices` skill. It covers 40+ rules with code examples.
+
+## Gotchas
+
+- Circular dependencies between modules: use `forwardRef()` sparingly. Better to restructure.
+- `@Global()` modules are for truly cross-cutting concerns (config, database). Do not overuse.
+- DTOs must use `class-validator` decorators. Plain interfaces won't trigger validation.
+- E2E tests need a separate test database. Never run E2E against production.
+
+## Finish
+
+```yaml
+agent: nestjs
+job: nestjs guidance for <scope>
+status: complete
+artifacts: []
+findings: []
+decisions_owed: []
+next: none
+```

package/library/skills/nextjs/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: nextjs
+version: "1.0.0"
+idempotent: false
+description: Use when building or reviewing a Next.js application with the App Router. Covers Server Components, Server Actions, routing, layouts, data fetching, caching, middleware, and deployment. Use when the project has a next.config or app/ directory. Do not use for Pages Router or non-Next.js React apps.
+---
+
+# nextjs
+
+Build Next.js App Router applications correctly. Server Components by default, client boundaries only where needed.
+
+## Inputs
+
+- The project root. Confirm `next` is in `package.json` dependencies.
+- `next.config.*` and `app/` directory.
+
+## Rules
+
+1. **Server Components by default.** Add `"use client"` only for interactivity, browser APIs, or hooks. Never add it to a component that only renders data.
+2. **Server Actions for mutations.** Use `"use server"` functions called from forms or event handlers. Validate input with zod. Never trust client-sent data.
+3. **Async params.** In Next.js 15+, `params` and `searchParams` are Promises. Await them. Type them as `Promise<{...}>`.
+4. **Data fetching in Server Components.** Fetch directly; no useEffect. Use `cache()` or the fetch cache. Revalidate with `revalidatePath` or `revalidateTag`.
+5. **Route handlers** (`route.ts`) for webhooks and external API proxies. Return `NextResponse.json()`.
+6. **Middleware** (`middleware.ts`) for auth redirects and locale detection. Keep it fast: no database calls.
+7. **Images and fonts.** Use `next/image` and `next/font`. Set `sizes` and `priority` for LCP images.
+8. **Error boundaries.** `error.tsx` per route segment. `not-found.tsx` for 404s. `loading.tsx` for Suspense.
+9. **Metadata.** Export `metadata` or `generateMetadata` from page/layout files. Never set `<title>` manually.
+10. **Deployment.** Default to Vercel. Set `output: "standalone"` for Docker. Environment variables must be prefixed `NEXT_PUBLIC_` to reach the client.
+
+## Gotchas
+
+- `"use client"` on a parent makes all children client components. Push the boundary as deep as possible.
+- Server Actions must be in a file with `"use server"` at the top, or be async functions in a Server Component.
+- `cookies()` and `headers()` are async in Next.js 15. Await them.
+- `revalidateTag` requires the fetch to use `{ next: { tags: [...] } }`.
+- Dynamic routes need `generateStaticParams` for static generation, or they render on demand.
+
+## Finish
+
+```yaml
+agent: nextjs
+job: next.js guidance for <scope>
+status: complete
+artifacts: []
+findings: []
+decisions_owed: []
+next: none
+```

package/library/skills/perf-budget/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: perf-budget
+version: "1.0.0"
+idempotent: true
+description: Use to measure performance against budgets the user has set: JavaScript bundle size, API latency, and Core Web Vitals on a named URL. Records measurements over repeated runs and compares them to docs/perf/budgets.md. Read-only on code. Do not use to optimize code; that is a follow-up task. Do not use for Vercel billing or function-cost analysis.
+---
+
+# perf-budget
+
+Measure, compare to a budget, and report. Never guess a number.
+
+## Budgets
+
+Read `docs/perf/budgets.md`. If it does not exist, create it with empty budgets and ask the user to set values. Do not invent budgets.
+
+```markdown
+# Performance budgets
+
+| Metric | Budget | Scope |
+|---|---|---|
+| Initial JS (gzip) | 170 KB | /  |
+| API p95 latency | 300 ms | GET /api/items |
+| LCP | 2.5 s | https://<url> |
+```
+
+## Steps
+
+1. **Bundle.** Run the project's build. Measure gzip size of the entry chunks from the build output. Record the build command and tool version.
+2. **API latency.** For each endpoint in the budget, send 20 GET requests sequentially. Record p50 and p95. Read-only endpoints only.
+3. **Web Vitals.** If a URL is given, run a Lighthouse or Playwright trace with the tool already in the project, three runs. Record the median.
+4. **Compare.** For each metric: within budget, over budget, or not measured. Over budget is a finding, with the amount over.
+5. **Write.** `docs/reviews/perf-<YYYY-MM-DD>.md` with a table of metric, budget, measured, status, method.
+
+## Gotchas
+
+- One run is noise. Use the runs listed above and report the spread.
+- Measure on the same machine and conditions every time, and say which.
+- Do not compare a dev build to a production budget. Build for production first.
+- Latency from a laptop is not latency from the region users are in. Name the location.
+
+## Finish
+
+```yaml
+agent: perf-budget
+job: measure performance against budgets
+status: complete | blocked | failed
+artifacts:
+  - path: docs/reviews/perf-<YYYY-MM-DD>.md
+    kind: created
+  - path: docs/perf/budgets.md
+    kind: read-only
+findings:
+  - id: F1
+    severity: high
+    summary: initial JS 240 KB gzip over 170 KB budget
+    evidence: <build output file and size>
+decisions_owed:
+  - set budget values for <metric>?
+next: user
+```
+
+Use `status: blocked` when no budgets are set and the user has not answered. Use `next: maintainer` only if the user asks for optimization work.