@yaawn/workflow 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# @yaawn/workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Installs `.agents/` skill files (skills, instructions, output-styles), agent personas, the shared `.yaawn/yaawn-definition-of-done.md`, `.yaawn/yaawn-verification-commands.md`, `.yaawn/yaawn-user-roles.md` and `.yaawn/yaawn-project-glossary.md`, and the `yaawn-*` issue templates into your project.
+
+## Usage
+
+```bash
+npm install @yaawn/workflow
+npx @yaawn/workflow
+```
+
+### Options
+
+| Flag                            | Effect                                                                                                                                                                                    |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-y`, `--yes`                   | Skip the interactive setup (with `--uninstall`: remove without asking)                                                                                                                    |
+| `--agent copilot\|claude\|vibe` | Coding agent to set up; saved to `.yaawn/yaawn-settings.json`, which is local to each developer (gitignored). Omitted: the previous choice, else `copilot`. Other values exit with code 1 |
+| `--uninstall`                   | Remove the yaawn files from your project instead of installing                                                                                                                            |
+| `-v`, `--version`               | Print the version                                                                                                                                                                         |
+| `-h`, `--help`                  | Show help                                                                                                                                                                                 |
+
+The install command syncs the bundled payload to your project root:
+
+```
+your-project/
+├── .agents/
+│   ├── instructions/
+│   ├── output-styles/
+│   ├── personas/
+│   └── skills/
+├── .github/
+│   └── ISSUE_TEMPLATE/
+│       ├── yaawn-bug-report.md
+│       ├── yaawn-refactor.md
+│       ├── yaawn-spike.md
+│       └── yaawn-story.md
+└── .yaawn/
+    ├── .gitignore
+    ├── yaawn-definition-of-done.md
+    ├── yaawn-project-glossary.md
+    ├── yaawn-user-roles.md
+    └── yaawn-verification-commands.md
+```
+
+In a terminal, the sync prints colored output with one line per synced directory. After syncing, the command runs a short keyboard-driven setup:
+
+1. **Coding agent** — pick exactly one: GitHub Copilot, Claude Code, or Mistral Vibe. The choice is saved to `.yaawn/yaawn-settings.json` and preselected on the next run. The file is local to each developer — `.yaawn/.gitignore` keeps it out of git, so every teammate picks their own agent.
+1. **Definition of done** — type the tasks your team requires before work counts as done. They are added as a checklist to `.yaawn/yaawn-definition-of-done.md`.
+1. **Verification commands** — type the commands to run, in order. They are added in run order as a list to `.yaawn/yaawn-verification-commands.md`. `/yaawn-verify-executed-plan` runs exactly these commands and stops at the first failure, so list the cheap ones first.
+1. **User roles** — type the roles your product's users have, the "As a …" of a user story (for example `Account Owner`). They are added as a plain list to `.yaawn/yaawn-user-roles.md`, and the story skills write stories from these roles. With no roles listed, stories are written for the Developer.
+1. **GitHub projects** — type the names of the GitHub projects your team uses (for example `Team Board`). After the sync, they are written into the `projects:` line of every `yaawn-*` issue template in `.github/ISSUE_TEMPLATE/`, so new issues land on those project boards. Names already in the templates are kept and merged with the new ones (case-insensitive, no duplicates); with no names entered, the templates stay unchanged.
+1. **Languages** — check the languages your project uses. Only the matching language-tagged instructions — `yaawn-*.<lang>.instructions.md` files in `.agents/instructions/` — are installed; instructions without a language tag always install.
+
+After the sync, the command links `.agents/` where the chosen agent looks for it, with relative symlinks:
+
+- **Copilot:** `.github/skills` → `../.agents/skills` and `.github/instructions` → `../.agents/instructions`.
+- **Claude Code:** `.claude/skills` → `../.agents/skills`. Instructions are imported in `.claude/CLAUDE.md` with one `@../.agents/instructions/<file>` line per instruction file, inside a block between `<!-- yaawn:instructions:start -->` and `<!-- yaawn:instructions:end -->`. Only that block is written; the rest of the file stays yours.
+- **Vibe:** no skill links — Vibe reads `.agents/skills` natively. Instructions are listed in the root `AGENTS.md`, inside a block between `<!-- yaawn:instructions:start -->` and `<!-- yaawn:instructions:end -->`: a note to read the instructions whose `applyTo` matches a file before editing it, followed by one `- .agents/instructions/<file>` line per instruction file. Only that block is written; text outside it stays yours.
+
+If the folder already exists as a real folder, each `yaawn-*` skill or instruction is linked inside it one by one. Existing links into `.agents/` are kept, and anything else with the same name is skipped and left untouched. Each link is reported as created, already there, skipped, or failed; a failed link shows the `ln -s` command to create it by hand, the other links are still created, and the command exits with code 1. Switching agents keeps the old agent's links.
+
+Keyboard controls in the setup wizard: `enter` adds the typed item to the current step (on an empty line it continues to the next step), `tab`/`shift+tab` switch to the next/previous step, `esc` finishes the setup from any step and installs (like `tab`, it keeps what you typed on the current step), `ctrl+c` cancels the install without writing anything. In the language step, `space` toggles the language under the cursor, `up`/`down` move, and `enter` confirms the selection and finishes the setup.
+
+Existing answers are kept when you run it again — already-listed items show up pre-checked, selected languages show up pre-checked, and duplicates are skipped — and the setup is skipped when you pass `--yes`; then all language-tagged instructions install. Without a terminal (for example in CI) the command stops unless you pass `--yes`. You can also edit these files by hand. In the commands file, every `- ` bullet is one command, run through the shell from the repo root:
+
+```markdown
+- `npm run lint && npm test`
+- `npm run e2e`
+```
+
+The command runs as an explicit step, not a lifecycle script, so it behaves the same in every package manager (npm, yarn, bun). With npm or yarn you can also invoke the bin directly: `npm exec workflow` or `yarn workflow`.
+
+## Uninstall
+
+```bash
+npx @yaawn/workflow --uninstall        # list, confirm, remove
+npx @yaawn/workflow --uninstall --yes  # remove without asking (CI)
+npm uninstall @yaawn/workflow
+```
+
+When yaawn files are found, an interactive run first asks whether to **Install / update** or **Uninstall**; fresh projects skip this question. `--uninstall` skips the question and goes straight to uninstalling.
+
+- **List, then confirm.** The command lists every file it will remove and asks before deleting anything. The answer defaults to "No"; declining or `ctrl+c` prints "Uninstall cancelled. Nothing was removed." and exits with code 130.
+- **What is removed.** Every `yaawn-*` entry the current package ships that exists in your project — in `.agents/skills/`, `.agents/instructions/`, `.agents/output-styles/`, `.agents/personas/`, `.github/ISSUE_TEMPLATE/`, plus `.agents/yaawn-glossary.md`, `.agents/yaawn-grilling.md`, `.yaawn/yaawn-definition-of-done.md`, `.yaawn/yaawn-verification-commands.md`, `.yaawn/yaawn-user-roles.md`, `.yaawn/yaawn-project-glossary.md`, `.yaawn/yaawn-settings.json`, and `.yaawn/.gitignore`. Every agent link into `.agents/` is removed too, for every agent — `.github/skills`, `.github/instructions`, `.claude/skills`, the links inside those folders when they are real folders, and the yaawn import block in `.claude/CLAUDE.md`, and the yaawn instructions block in `AGENTS.md` (each file is deleted only when nothing else is left in it). Folders that become empty are removed too; `.agents/`, `.github/`, and `.yaawn/` themselves are kept, and so are folders that were already empty.
+- **What is kept.** `.yaawn/plans/` (your team's plans and logs), your own files, and stale `yaawn-*` entries from older versions that the current package no longer ships.
+- **Stays inside your project.** Symlinks are removed, never the files they point to. If a target folder points outside the project, the command stops before removing anything.
+- **Stops at the first error.** Agent links are removed first, and every link is tried even if one fails. If a file cannot be removed, the command stops, shows what was already removed and the error, and exits with code 1. Nothing is restored.
+- **Nothing to remove.** Without yaawn files the command says so and exits with code 0.
+- **Without a terminal.** `--uninstall` without `--yes` exits with code 1 and removes nothing.
+- **Package removal.** The summary ends with the command that removes the package itself: `npm uninstall @yaawn/workflow`.
+
+## Behavior
+
+- **Always overwrites, except your answers.** The package is the source of truth — after `npm update @yaawn/workflow`, re-run `npx @yaawn/workflow` to sync the latest versions into your project. The exceptions are `.yaawn/yaawn-definition-of-done.md`, `.yaawn/yaawn-verification-commands.md`, `.yaawn/yaawn-user-roles.md`, and `.yaawn/yaawn-project-glossary.md`: they are only written when missing, so your team's answers survive updates.
+- **Deletes yaawn files first.** Before copying, the command deletes the `yaawn-*` entries in `.agents/skills/`, `.agents/instructions/`, `.agents/output-styles/`, `.agents/personas/`, and `.github/ISSUE_TEMPLATE/`, so skills and templates the package no longer ships disappear. Do not put your own changes into `yaawn-*` files — they are replaced on every sync. Everything else in those folders (your own skills, workflows, and templates) and everything in `.yaawn/` (your answers and plans) is left alone.
+- **Language-tagged instructions.** Instruction files named `yaawn-*.<lang>.instructions.md` (for example `yaawn-clean-code.typescript.instructions.md`) install only for the languages selected in the setup. Unchecking a language on a later run removes its instructions again. With `--yes` or without a terminal, all language-tagged instructions install.
+- **Tracked by git.** The command never touches your root `.gitignore` — `.yaawn/` is meant to be committed, so plans, logs, your definition of done, and your verification commands are shared with the team. The exception is `yaawn-settings.json`: the command writes `.yaawn/.gitignore` (replaced on every sync) to keep each developer's coding-agent choice out of git.
+- **Non-destructive.** Existing `.yaawn/` and `.github/` folders are kept — only the shipped `yaawn-*` files are replaced in them, and missing folders are created.
+- **Idempotent.** Running the install command multiple times produces the same result.
+- **Non-blocking.** If the sync fails for any reason, the command reports the error but does not fail.
+- **`--yes` in CI.** Without a terminal and without `--yes`, the command exits with code 1 and a message to rerun with `--yes`, and writes nothing. In CI, always run `npx @yaawn/workflow --yes`.
+- **Native binary.** The installer is a Go binary shipped per platform; `npx @yaawn/workflow` runs a small Node.js shim that starts it. See [Supported platforms](#supported-platforms).
+
+## What's included
+
+- **Skills** — agent skill definitions with references and scripts
+- **Instructions** — project-level instruction files
+- **Output styles** — predefined output formatting styles
+- **Agent personas** — `.agents/personas/yaawn-*.md`: Developer (default), Reviewer, and Product Owner. The always-on `yaawn-personas` instruction picks the persona per task; you never choose one
+- **Issue templates** — `yaawn-*` templates for bugs, refactors, spikes, and stories; they no longer reference the Definition of Done
+- **Definition of Done** — `.yaawn/yaawn-definition-of-done.md`, the standard checklist and its single source of truth; `/yaawn-implement-plan` and `/yaawn-verify-executed-plan` read it directly
+- **Verification commands** — `.yaawn/yaawn-verification-commands.md`, the commands `/yaawn-verify-executed-plan` runs
+- **User roles** — `.yaawn/yaawn-user-roles.md`, the roles the story skills write for; Developer when none are listed
+- **Project glossary** — `.yaawn/yaawn-project-glossary.md`, the project's settled terms, written by `/yaawn-grill-design`; created once and kept across updates
+
+## Supported platforms
+
+The binary ships in one optional dependency per platform, and npm installs only the one matching your machine:
+
+| Platform             | Package                        |
+| -------------------- | ------------------------------ |
+| macOS, Apple silicon | `@yaawn/workflow-darwin-arm64` |
+| macOS, Intel         | `@yaawn/workflow-darwin-x64`   |
+| Linux, x64           | `@yaawn/workflow-linux-x64`    |
+| Linux, arm64         | `@yaawn/workflow-linux-arm64`  |
+| Windows, x64         | `@yaawn/workflow-win32-x64`    |
+
+On any other platform, the command exits with code 1 and prints `workflow: unsupported platform <platform>/<arch> — supported: ...`. When the platform package is missing (for example after `npm install --omit=optional`, or from a stale `npx` cache), it prints `workflow: installer binary package @yaawn/workflow-<platform> is not installed — ...`.
+
+## Configuration
+
+The installer's content lives in three JSON files in `config/`. The binary reads them at every start, so editing them needs no rebuild:
+
+- **`wizard.json`** — the setup steps in order (`id`, `title`, `description`, `kind` of `text-list` or `multiselect`, `targetFile`, `placeholder`) and every user-facing message under `messages`: help, version, intro, outro, key hints, and status and error lines. `{placeholders}` are filled in at runtime.
+- **`settings.json`** — `brandColor`, the `filePrefix` of yaawn-owned files, the `outputFileNames` the text-list steps write to, the `languagePattern` that extracts the language tag from instruction file names, the `languageLabels` shown in the language step, and the `languageImplications` — tags whose files also install when a tag is selected (e.g. TypeScript also installs JavaScript, not the other way round).
+- **`install-tasks.json`** — the `syncTargets`: which bundled `source` directory is copied to which project `target`, which files are only seeded when missing (`seedOnly`), which `removeFirst` globs are deleted before copying, which files are installed under a different name (`renames`, plain file names mapped source → target, e.g. `gitignore` → `.gitignore`, because npm drops `.gitignore` files from published packages), and which directory holds the language-tagged instructions (`languageInstructions`).
+
+All three are validated strictly on load. An unknown key, a missing field, or a path that escapes the package root (sources) or the project directory (targets) stops the command with exit code 1 and a message naming the file and field — nothing is written.
+
+## Development
+
+The installer source is a Go module in `cli/`. Install the Go version pinned by the `toolchain` line in `cli/go.mod`, then:
+
+```bash
+cd packages/workflow/cli
+go test ./...
+go run ./cmd/workflow --package-root .. --yes
+```
+
+`--package-root` points the binary at the package directory holding `config/` and the payload; the shim passes it automatically. The local run syncs into the current directory (or `INIT_CWD` when set), so run it from a scratch project, not from this repository.
+
+## Releasing
+
+Publishing runs only in GitHub Actions ([`publish-workflow.yml`](../../.github/workflows/publish-workflow.yml)); the release script refuses to publish locally.
+
+To release, open **Actions → Publish @yaawn/workflow → Run workflow** on `main`, pick the version bump (`patch`, `minor`, `major`), and uncheck **dry-run**.
+
+The workflow runs the Go tests, bumps `version` in `package.json`, and runs `release/release-installer.mjs`. The script cross-compiles the binary for the five supported platforms into `npm/<platform>/` (gitignored), writes one package per platform at the new version, sets `optionalDependencies` to that version, publishes the platform packages, and then publishes `@yaawn/workflow`. After a successful publish, the workflow commits `package.json` to `main` and pushes the tag `workflow-v<version>`. Versions that are already on npm are skipped.
+
+With **dry-run** checked, the workflow builds and runs `npm publish --dry-run` without committing or tagging. Locally, run `npm run release:dry-run` with Go installed.
+
+Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers): npm authenticates the workflow via OIDC, so no long-lived token is stored. On npmjs.com, each of the six packages (`@yaawn/workflow` and `@yaawn/workflow-<platform>`) needs a trusted publisher with repository `markusfalk/yaawn`, workflow `publish-workflow.yml`, and environment `npm`.
+
+Trusted publishers can only be added to packages that already exist. To bootstrap a new package, publish its first version once by hand with interactive 2FA, then add the trusted publisher. For the platform packages:
+
+```bash
+cd packages/workflow
+npm login
+npm run release:dry-run
+for p in darwin-arm64 darwin-x64 linux-x64 linux-arm64 win32-x64; do
+  (cd "npm/$p" && npm publish)
+done
+```

package/agents/instructions/output-styles/yaawn-eli5.instructions.md

@@ -0,0 +1,45 @@
+---
+name: ELI5
+description: 'Use only when the user explicitly asks for an ELI5, beginner-level, or plainly-worded explanation. Rewrites chat prose to use analogies, everyday vocabulary, and short sentences. Changes wording only — never code, commands, or file paths.'
+keep-coding-instructions: true
+---
+
+# ELI5
+
+Explain things the way you would to someone smart who has never seen this system before.
+
+## Scope
+
+This style changes **the prose of chat answers only**. It never changes:
+
+- code, identifiers, and type names
+- file paths and shell commands
+- API names, endpoints, and configuration keys
+- error messages, stack traces, and log output
+- diffs and code comments
+- commit messages and PR descriptions
+- i18n keys and i18n values
+- anything inside a fenced code block
+
+Reproduce all of the above verbatim. Generated code follows the repository's existing conventions and is never reworded to fit this style.
+
+Accuracy outranks every rule below:
+
+- Never simplify a technical term into an inaccurate one.
+- Never shorten an error message or a security warning.
+- Never drop a caveat to make a sentence shorter.
+
+If a rule in this file would make the answer wrong, the rule loses.
+
+If another output style is also active, stop and ask which one applies.
+
+## Writing rules
+
+- Lead with an analogy or a concrete everyday comparison, then connect it back to the real thing.
+- Use everyday vocabulary. Prefer "reads" over "consumes", "goes wrong" over "fails to resolve".
+- Keep sentences short. One idea per sentence.
+- Introduce every technical term the first time it appears: name it, then say what it does in plain words.
+- Prefer concrete examples over abstract description.
+- Say what something is _for_ before saying how it works.
+- Do not use jargon as a shortcut. If a term is unavoidable, explain it.
+- Keep the answer as short as the question allows. Simple is not the same as long.

package/agents/instructions/yaawn-accessibility.css.instructions.md

@@ -0,0 +1,58 @@
+---
+applyTo: '**/*.css'
+description: 'Write accessible CSS following the A11Y Project checklist: color contrast, visible focus, reduced motion, zoom and reflow, touch targets. See https://www.a11yproject.com/checklist/'
+---
+
+## Accessible CSS
+
+Style content so everyone can perceive and operate it. These rules cover the styling layer of the A11Y Project checklist; they never replace accessible markup — fix the HTML first, then style it.
+
+### Content
+
+- Align body text to the start edge (`text-align: start`) — avoid centered or justified paragraphs
+- Never use CSS-generated content (`::before`/`::after`) for information the page needs; keep it in the markup
+
+### Keyboard
+
+- Give every interactive element a clearly visible focus style with `:focus-visible`
+- Never remove `outline` without a replacement of equal visibility (`outline: none` alone is forbidden)
+- Make the skip link visible when it receives focus
+- Do not reorder content visually (`order`, `flex-direction: row-reverse`, grid placement) so that focus order no longer matches what people see
+
+### Controls
+
+- Make links recognizable without color — underline links in body text
+- Style hover, focus, and active states for every control
+
+### Appearance
+
+- Size text and containers in relative units (`rem`, `em`, `%`) so content stays readable and does not overlap at 200% text size or zoom
+- Do not fix heights on containers holding text; let them grow
+- Keep related content, labels, and controls close together so people using screen magnifiers can find them
+- Never convey information by color alone — add text, an icon, a pattern, or an underline
+- Keep the layout simple and consistent across pages
+- Hide content visually but keep it for assistive technology with a visually-hidden class (clip pattern); use `display: none` or `visibility: hidden` only when content must be hidden from everyone
+
+### Animation
+
+- Wrap non-essential animation, transitions, parallax, and smooth scrolling in `@media (prefers-reduced-motion: no-preference)`, or remove them inside `@media (prefers-reduced-motion: reduce)`
+- Slow down animation that is essential to understanding instead of removing it
+- Never flash content more than three times per second
+- Keep animations subtle and short
+
+### Color contrast
+
+- Give normal-sized text a contrast ratio of at least 4.5:1 against its background
+- Give large text (24px, or 18.66px bold) at least 3:1
+- Give icons, input borders (text inputs, checkboxes, radio buttons), and focus indicators at least 3:1
+- Keep text over images or video legible — add a solid or semi-opaque backdrop behind it
+- Respect forced-colors mode: do not convey state only through `background-color` or `box-shadow`, which forced colors remove
+
+### Mobile and touch
+
+- Build layouts that reflow to a 320 CSS px wide viewport without horizontal scrolling (except data tables, maps, and similar 2D content)
+- Support portrait and landscape — never hide or rotate content based on `orientation`
+- Make touch targets at least 44×44 CSS px, using padding instead of shrinking the hit area
+- Leave space between adjacent interactive items so people can scroll past them
+
+Reference: [The A11Y Project — Checklist](https://www.a11yproject.com/checklist/)

package/agents/instructions/yaawn-accessibility.html.instructions.md

@@ -0,0 +1,90 @@
+---
+applyTo: '**/*.{html,tsx,jsx}'
+description: 'Write accessible markup following the A11Y Project checklist: alt text, one h1, labelled inputs, table headers, captions, lang. See https://www.a11yproject.com/checklist/'
+---
+
+## Accessible HTML
+
+Write markup that assistive technology can read, understand, and operate. These rules cover the markup layer of the A11Y Project checklist; they build on the semantic HTML instruction — pick the semantic element first, then apply the rules below.
+
+### Content
+
+- Give every `<a>`, `<button>`, and `<label>` text that is unique on the page and describes its destination or action — never "click here" or "read more" alone
+- Write instructions that name the element or section, not only its position, shape, color, or sound ("use the Search button", not "the button on the right")
+
+### Global code
+
+- Write valid HTML — no duplicate `id`s, no unclosed or misnested elements
+- Set the page language on the root element (`<html lang="en">`) and mark passages in another language with `lang` on their element
+- Give every page or view a unique, descriptive `<title>`
+- Never disable zoom in the viewport meta tag — no `user-scalable=no`, no `maximum-scale=1`
+- Wrap page regions in landmark elements: `<header>`, `<nav>`, `<main>` (exactly one), `<aside>`, `<footer>`
+- Keep DOM order equal to visual order so content flows linearly
+- Use `tabindex` only with `0` or `-1` — never a positive value; do not add it to natively focusable elements
+- Do not use the `autofocus` attribute
+
+### Keyboard
+
+- Make every interactive element reachable by keyboard by using native controls (`<a href>`, `<button>`, form fields)
+- Mark content that is hidden from view as `hidden` or `inert` so its controls cannot receive focus (closed menus, off-screen navigation, closed dialogs)
+
+### Images
+
+- Give every `<img>` an `alt` attribute
+- Use `alt=""` for decorative images; describe the content and purpose for informative ones
+- Include any text shown in the image in its `alt` (a logo's alt is the brand name)
+- Provide a full text alternative for complex images (charts, graphs, maps) next to the image, linked via `<figure>`/`<figcaption>` or `aria-describedby`
+- Give inline `<svg>` that conveys meaning `role="img"` and an accessible name (`<title>` or `aria-label`); give decorative `<svg>` `aria-hidden="true"`
+
+### Headings
+
+- Use exactly one `<h1>` per page or view, describing its purpose — not the site name repeated on every page
+- Introduce each content section with a heading; never use headings only for their look
+- Nest headings in order and never skip a level (`h2` → `h3`, not `h2` → `h4`)
+
+### Lists
+
+- Mark up related items as `<ul>`, `<ol>`, or `<dl>` — including navigation links and card grids
+
+### Controls
+
+- Use `<a href="…">` for navigation, always with an `href` — also in single-page apps
+- Use `<button>` for actions and set `type="button"` on buttons that do not submit a form
+- Provide a skip link to `<main>` as the first focusable element on the page
+- Avoid opening links in a new tab or window; when one must, say so in the link text or an accessible hint
+- Give icon-only controls an accessible name (visually hidden text or `aria-label`)
+
+### Tables
+
+- Use `<table>` for tabular data only, never for layout
+- Mark header cells as `<th>` with `scope="col"` or `scope="row"`
+- Give every table a `<caption>` that names its content
+
+### Forms
+
+- Associate every input with a `<label>` via `for`/`id`
+- Group related inputs with `<fieldset>` and name the group with `<legend>`
+- Set `autocomplete` on fields that ask for personal data (name, email, address, phone)
+- After submission, show an error summary above the form that lists each error and links to its field
+- Link each error message to its input with `aria-describedby` and mark the input `aria-invalid="true"`
+- State errors, warnings, and success in text or an icon with a text alternative — never by color alone
+
+### Media
+
+- Do not set `autoplay` on `<video>` or `<audio>`
+- Use the `controls` attribute or an accessible custom player so every media element can be paused
+
+### Video
+
+- Provide captions for every video with speech or meaningful sound via `<track kind="captions" srclang="…" label="…">`
+
+### Audio
+
+- Provide a text transcript for every audio file and link it next to the player
+
+### Mobile and touch
+
+- Do not lock the page to one orientation
+- Keep space between adjacent links and buttons so people can scroll without activating them
+
+Reference: [The A11Y Project — Checklist](https://www.a11yproject.com/checklist/)

package/agents/instructions/yaawn-accessibility.javascript.instructions.md

@@ -0,0 +1,50 @@
+---
+applyTo: '**/*.{js,jsx,ts,tsx,mts}'
+description: 'Write accessible JavaScript following the A11Y Project checklist: keyboard-operable controls, focus management, live regions, reduced motion, safe rendering. See https://www.a11yproject.com/checklist/'
+---
+
+## Accessible JavaScript
+
+Keep scripted behavior operable for keyboard, screen reader, and switch users. These rules cover the scripting layer of the A11Y Project checklist. Reach for JavaScript last — when a native HTML element or CSS solves the problem, use it instead.
+
+### Global code
+
+- Update `document.title` on every client-side route change so each view has a unique title
+- Let people turn off, adjust, or extend session timeouts — warn them before the session ends and offer a way to extend it
+- Do not move focus or change context on load or on input alone (no automatic submit on `change`)
+
+### Keyboard
+
+- Prefer native elements (`<button>`, `<a href>`, `<dialog>`, `<details>`) over scripted widgets — they are keyboard-operable for free
+- When a custom control is unavoidable, give it the matching `role`, `tabindex="0"`, an accessible name, and state attributes (`aria-expanded`, `aria-pressed`, `aria-selected`) kept in sync with its state
+- Handle `Enter` and `Space` for button-like controls, and arrow keys where the ARIA Authoring Practices pattern expects them
+- Never bind actions to mouse-only events (`mousedown`, `mouseover`, `dblclick`) without a keyboard equivalent
+- Set `inert` (or remove from the DOM) on content that is closed or off screen so it cannot receive focus
+
+### Controls
+
+- Move focus into a dialog when it opens and return it to the triggering control when it closes; prefer `<dialog>` with `showModal()`
+- Trap focus only inside a modal dialog, and always let `Escape` close it
+- Move focus to the new view's `<h1>` or `<main>` (with `tabindex="-1"`) after a client-side route change
+- Announce dynamic updates (results counts, saved states, toasts, form errors) through a live region (`role="status"` or `aria-live="polite"`; `role="alert"` only for urgent errors) that exists in the DOM before the update
+- On a failed submit, render the error summary, move focus to it, and link each error to its field
+
+### Media
+
+- Never start playback automatically — play only after a user action
+- Give custom media players keyboard-operable, labelled controls for play/pause, volume, captions, and seeking
+- Let `Space` toggle playback when the player has focus, without hijacking `Space` scrolling elsewhere on the page
+
+### Animation
+
+- Check `matchMedia('(prefers-reduced-motion: reduce)')` before running scripted animation, scrolling, or auto-advancing carousels, and listen for changes
+- Provide a control to pause, stop, or hide anything that moves, blinks, or auto-updates for more than five seconds, including background video
+
+### Safe rendering
+
+- Render user-supplied or remote content with `textContent`, `setAttribute`, or framework bindings that escape output — never with `innerHTML`, `outerHTML`, `insertAdjacentHTML`, or `document.write`
+- Sanitize HTML with a maintained sanitizer (for example DOMPurify) when rich content must be rendered, and avoid framework escape hatches such as `dangerouslySetInnerHTML` with untrusted data
+- Write messages into live regions as text, never as markup built from user input
+- Never pass user content to `eval`, `new Function`, or string arguments of `setTimeout`/`setInterval`
+
+Reference: [The A11Y Project — Checklist](https://www.a11yproject.com/checklist/)

package/agents/instructions/yaawn-clean-code.typescript.instructions.md

@@ -0,0 +1,74 @@
+---
+applyTo: '**/*.{ts,mts,tsx}'
+description: 'This document outlines the clean code principles and best practices for the codebase.'
+---
+
+## Clean Code Principles (Based on Robert C. Martin)
+
+### 1. Single Responsibility Principle (SRP)
+
+- Each class/module should have one and only one reason to change
+- Keep functions focused and small
+- Separate concerns appropriately
+
+### 2. Naming Conventions
+
+- Use intention-revealing names
+- Choose meaningful and pronounceable variable names
+- Use consistent verbs for method names (get/set/is/has/update)
+- Avoid abbreviations unless they're widely accepted
+- never use snake_case or Hungarian notation
+- Use PascalCase for classes and interfaces
+- Use camelCase for variables, functions, and methods
+
+### 3. Function Rules
+
+- Functions should do one thing
+- Keep functions small (preferably under 20 lines)
+- Minimize the number of arguments (3 or fewer is ideal)
+- Avoid flag arguments
+- Don't repeat yourself (DRY principle)
+
+### 4. Comments and Documentation
+
+- See the Comments section of `AGENTS.md` — it is the single source of truth for when to comment and how to tag one
+
+### 5. Error Handling
+
+- Use strong typing to prevent errors
+- Handle errors gracefully
+- Don't ignore caught errors
+- Prefer early returns
+- Use meaningful error messages
+
+### 6. Code Organization
+
+- Keep related code together
+- Organize code by feature/module
+- Maintain a clear and consistent project structure
+
+### 7. Testing
+
+- Write tests first (TDD)
+  - Write a failing test that defines the desired behavior
+  - Write the minimum code needed to make the test pass
+  - Refactor while keeping tests green
+  - No new code without corresponding tests
+- Make tests readable
+  - Use descriptive test names that explain the behavior being tested
+  - Follow the AAA pattern (Arrange, Act, Assert)
+  - Keep test setup focused and minimal
+- One assert per test
+  - Each test should verify one specific behavior
+  - Use separate tests for different conditions
+  - Avoid testing multiple things in one test case
+- Keep tests fast and independent
+  - No dependencies between tests
+  - Clean up test data after each test
+  - Mock external dependencies appropriately
+  - Tests should be able to run in any order
+- Test Coverage
+  - Aim for high test coverage in business logic
+  - Unit test all public APIs
+  - Include edge cases and error conditions
+  - Write integration tests for critical paths

package/agents/instructions/yaawn-function-coupling.typescript.instructions.md

@@ -0,0 +1,100 @@
+---
+applyTo: '**/*.{ts,mts,tsx}'
+description: 'Orchestrate the steps of a flow in parallel at the call site, and pass shared data through the constructor or class members.'
+---
+
+## **✅ Keep methods independent of each other**
+
+Orchestrate every step of a flow from one method, so each step can change or be removed without touching the others. Methods are coupled when a change in one forces changes in the others.
+
+❌ **Counter-example** — each method calls the next and threads the same parameter, so removing `findLastChapter()` would also force a change in `openBook()`:
+
+```tsx
+export class ReaderService {
+
+  // this is where my journey through middle earth begins
+  read(isbn: number) {
+    // some extra logic
+    this.openBook(isbn);
+  }
+
+  openBook(isbn: number) {
+    // some extra logic
+    this.findLastChapter(isbn);
+  }
+
+  findLastChapter(isbn: number) {
+    // some extra logic
+    this.findLastPage(isbn);
+  }
+
+  findLastPage(isbn: number) {
+    // some extra logic
+    this.startReading(isbn);
+  }
+
+  startReading(isbn: number) {
+    // some extra logic
+  }
+}
+```
+
+## **✅ Call the steps in parallel**
+
+Call every step from the orchestrating method, so the complete flow is visible in one place and each step stays independently testable.
+
+```tsx
+export class ReadBookService {
+
+  // the isbn is passed from another service/component/controller/...
+  read(isbn: number) {
+    // Now I can see the complete feature in one place 🥳
+    // There is no coupling any more between functions.
+    this.openBook(isbn);
+    this.findLastChapter(isbn);
+    this.findLastPage(isbn);
+    this.startReading(isbn);
+  }
+
+  private openBook(isbn: number) {
+    // some logic
+  }
+
+  private findLastChapter(isbn: number) {
+    // some logic
+  }
+
+  private findLastPage(isbn: number) {
+    // some logic
+  }
+
+  private startReading(isbn: number) {
+    // some logic
+  }
+}
+```
+
+## **✅ Reduce repeated arguments with class members**
+
+Inject shared data once through the constructor — or a lifecycle hook such as Angular's `OnInit` — and read it from the class member in every method that needs it.
+
+```tsx
+export class ReadBookService {
+
+  constructor(private isbn: number) {}
+
+  read() {
+    // No params passed
+    this.openBook();
+    this.findLastChapter();
+    this.findLastPage();
+    this.startReading();
+  }
+
+  private openBook() {
+    // use class member
+    console.log(this.isbn);
+  }
+  // findLastChapter(), findLastPage(), startReading() follow the same shape
+}
+```

package/agents/instructions/yaawn-html-css-js.html.instructions.md

@@ -0,0 +1,32 @@
+---
+applyTo: '**/*.{html,css,ts,tsx,js,jsx}'
+description: 'When creating new features, resolve the needed logic in this order: HTML first, then HTML & CSS, and only then JavaScript/TypeScript.'
+---
+
+## HTML > CSS > JS
+
+When building new UI features, prefer the simplest technology that solves the problem. Follow this priority order:
+
+### 1. HTML only
+
+- Use native HTML elements and attributes to achieve the desired behavior
+- Examples: `<details>`/`<summary>` for expand/collapse, `<dialog>` for modals, form validation attributes (`required`, `pattern`, `min`, `max`), the `popover` attribute, `contenteditable`
+- If a native HTML feature solves the problem, use it — no CSS or JS needed
+
+### 2. HTML + CSS
+
+- If HTML alone is not sufficient, add CSS before reaching for JavaScript
+- Examples: `:hover`/`:focus`/`:focus-within` for interactivity, CSS transitions and animations, `position: sticky`, CSS Grid/Flexbox for layout, `@media` queries for responsive behavior, `scroll-behavior: smooth`, `:target` for tab-like behavior without JS
+- Prefer a CSS-only solution over a JS-driven one whenever it is equally maintainable
+
+### 3. JavaScript / TypeScript
+
+- Only add JS/TS when neither HTML nor CSS can achieve the required behavior
+- Examples: fetching data, complex state management, real-time updates, browser APIs not covered by HTML/CSS
+- Keep the JS layer as thin as possible — use it to enhance, not to replace, what HTML and CSS can already do
+
+### Why this order
+
+- HTML and CSS are more accessible, performant, and resilient than JS — they work without JavaScript enabled, parse faster, and degrade gracefully
+- Less JavaScript means less to load, less to maintain, and fewer bugs
+- Progressive enhancement: start with a working baseline and layer on complexity only when needed