@groupby/ai-dev 0.5.14 → 0.5.16

package/teams/brain-studio/skills/git-context/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: git-context
+description: Provides standardized procedures for acquiring git context in agent workflows — syncing with origin/main (with conflict handling), extracting the current branch name and Jira ticket key, acquiring committed and working-tree diffs, and classifying change types for arch-doc routing. Outputs five named variables (branch-name, ticket-key, committed-diff, working-tree-status, change-types) consumed by jira-context, arch-context, and downstream review, planning, and PR workflow steps (whether skills or prompts). Auto-apply before any prompt that needs the current branch, ticket key, diff, or sync state.
+---
+
+# Git Context Guide
+
+## Relationship to other repository skills
+
+This skill has no dependencies on other skills. It is a foundational workflow skill
+consumed by `jira-context`, `arch-context`, and the downstream workflow steps that
+consume this context (review, planning, and PR steps — skills or prompts).
+
+- `jira-context` — depends on `<ticket-key>` produced here
+- `arch-context` — depends on `<change-types>` produced here
+
+## Mandatory application (agents)
+
+Whenever a prompt or workflow stage requires git context:
+
+1. **Read this skill file** before running any git commands.
+2. Run the **Working method** steps in order.
+3. Store each output variable for use by the calling prompt.
+
+This skill is optional for tasks that do not need branch or diff information
+(e.g. pure documentation lookups or static file edits with no git dependency).
+
+## When to use
+
+- Before fetching a Jira ticket (ticket key is extracted from the branch name here).
+- Before performing a code review (the diff is the subject of review).
+- Before creating or describing a PR (branch must be synced; diff needed for summary).
+- Before writing an implementation plan (diff shows scope of existing work).
+- Any time a prompt says "get the current branch and diff" or "sync with main".
+
+## When not to use
+
+- The user has already provided the diff inline — skip the diff commands; still run the
+  sync and branch steps unless the caller explicitly says they are already done.
+- The calling prompt explicitly says to skip git setup (e.g. a review step signals the
+  PR step that sync is already done) — honour that instruction.
+
+## Truthfulness and claims
+
+- Do not assume the branch name format — always extract from `git branch --show-current`.
+- Do not assume the ticket key pattern — use the regex `[A-Z]+-[0-9]+` against the
+  branch name; do not guess.
+- Do not invent diff content — always use actual command output.
+- Do not declare "no changes" unless all four diff commands return empty output.
+
+## Self-contained operating mode
+
+Use the procedures in the **Embedded implementation standard** below as the sole
+authority for git context gathering in this project. Do not substitute in-memory
+context from a previous session or conversation turn — always re-run the commands.
+
+---
+
+## Embedded implementation standard
+
+### 1) Sync with origin/main
+
+Run in order:
+
+```bash
+git fetch origin
+git merge origin/main
+```
+
+Outcomes:
+
+| Output | Action |
+|--------|--------|
+| `Already up to date` | Continue immediately. |
+| Merge commit created | Note it; continue. |
+| Merge conflict detected | **Stop. Ask the user to resolve conflicts before continuing.** |
+
+### 2) Acquire branch name and ticket key
+
+```bash
+git branch --show-current
+```
+
+- Store the exact output as `<branch-name>`.
+- Extract `<ticket-key>` using the pattern `[A-Z]+-[0-9]+` applied to `<branch-name>`.
+  - Example: `S4R-10620-my-feature` → `S4R-10620`
+  - Example: `BS-1056-some-fix` → `BS-1056`
+- If no key matches, set `<ticket-key>` to `none` and note it prominently — the caller
+  decides whether a missing key is a hard stop.
+
+### 3) Acquire committed diff
+
+Primary commands:
+
+```bash
+git --no-pager diff --stat origin/main...HEAD
+git --no-pager diff origin/main...HEAD
+```
+
+If both return empty output (new branch, no commits ahead of main, or detached HEAD), fall back to:
+
+```bash
+git --no-pager diff --stat HEAD
+git --no-pager diff HEAD
+```
+
+- If all four commands return empty, report: **"No committed changes detected."** and stop
+  unless the caller explicitly continues.
+- Store the full diff output as `<committed-diff>`.
+
+### 4) Acquire working-tree state
+
+```bash
+git status --short
+git --no-pager diff --stat
+git --no-pager diff
+```
+
+- If `git status --short` is empty, there are no uncommitted changes — record this.
+- If staged or unstaged changes exist, store them as `<working-tree-status>` and include
+  them in any summary, PR description, or review the caller produces.
+
+### 5) Classify change types
+
+Inspect `<committed-diff>` (and `<working-tree-status>` if present) and identify which
+categories apply. Store as `<change-types>` for use by the `arch-context` skill.
+
+| Category | Signal |
+|----------|--------|
+| Component / hook (`.tsx`) | Files ending in `.tsx` outside `.styles.tsx` |
+| Styling (`.styles.ts` / `.styles.tsx`) | Files ending in `.styles.ts` or `.styles.tsx` |
+| API / data fetching | `useQuery`, `useMutation`, RTK Query slice files, `api/` paths |
+| State management | Redux slices, selectors, `store/` paths |
+| Test changes | Files under `test/` |
+| Config / build | `webpack`, `tsconfig`, `.env`, `helm/`, `Dockerfile`, `package.json` |
+| Auth / permissions | `auth/`, token, role, permission references |
+| Feature flags | `feature-flag`, `launch-darkly` references |
+| i18n | `localization/`, `.json` translation files |
+
+---
+
+## Working method (apply in this order)
+
+1. **Sync** — Run `git fetch origin` and `git merge origin/main`; stop on conflict.
+2. **Identify** — Run `git branch --show-current`; extract and store `<branch-name>` and
+   `<ticket-key>`.
+3. **Diff** — Run committed diff commands; fall back as needed; store `<committed-diff>`.
+4. **Status** — Run working-tree commands; store `<working-tree-status>`.
+5. **Classify** — Derive `<change-types>` from the diff content.
+6. **Confirm** — Verify all five variables are set before returning to the caller.
+
+## Quality bar before final answer
+
+- `<branch-name>` equals the exact output of `git branch --show-current`.
+- `<ticket-key>` is a extracted key matching `[A-Z]+-[0-9]+`, or explicitly `none`.
+- `<committed-diff>` is non-empty, or "no committed changes detected" is reported.
+- Merge conflicts (if any) caused an immediate stop — no further steps executed.
+- `<change-types>` is derived from the actual diff, not from memory or assumption.
+- No output variable is invented or guessed.

package/teams/brain-studio/skills/html/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: html
+description: >-
+  Provides self-contained modern HTML authoring rules — document baseline (`<!doctype html>`, `lang`, `charset`, viewport, `title`), semantic structure (`header`/`nav`/`main`/`aside`/`footer`/`article`/`section`/`figure`), heading and landmark hierarchy, interactive element discipline (`button` for actions, `a` for navigation), accessible forms (explicit `<label>`, `fieldset`/`legend`, real input types — never placeholder-as-label), accessibility defaults (WCAG 2.2: keyboard operability, visible focus, meaningful link text, `alt` strategy, accessible status updates), tables/media (data tables only, captions/transcripts), metadata/SEO fundamentals, validation via Nu HTML Checker, and the project's `js-` / `ts-` `id` prefix convention for script-targeted nodes — without relying on fetching external docs. Project rule: **markup, styles, and scripts live in separate files** (`.html`, `.css`, `.js`/`.mjs`/`.ts`). **Project rule (script placement):** `type="module"` scripts go in `<head>` (implicitly deferred, early download, compatible with `<link rel="modulepreload">`); non-module `<script src="…">` go at the **end of `<body>`** or use explicit `defer` in `<head>`; `async` only for truly independent scripts (analytics, widgets) with no DOM dependency or ordering requirement. **Hard bans:** do not put authored CSS in `<style>` blocks or bulk inline `style=""`; do not put application logic in inline `<script>` bodies; do not use non-interactive elements (`div`, `span`) as controls; do not use placeholder text as a label replacement; do not use tables for page layout. Auto-apply whenever working with HTML files (`.html`) or HTML snippets, including creating, editing, reviewing, refactoring, or explaining markup.
+---
+
+# HTML Best Practices Guide
+
+## Purpose
+Answer HTML implementation questions using **embedded rules below** as the default standard. Treat external URLs as **optional citations**, not prerequisites.
+
+## When to use
+- Writing or reviewing HTML, accessible markup, semantic structure, forms, or document metadata
+- HTML audits / reviews against semantic + accessibility (WCAG 2.2) + SEO fundamentals
+- Choosing between `button` vs `a`, `section` vs `article`, `figure` vs raw `img`, native input types, ARIA only when needed
+- Wiring **`id` hooks** that scripts will query (`js-…` / `ts-…` prefix convention)
+- HTML validation strategy (Nu HTML Checker) and accessibility checks (automated + manual keyboard pass)
+
+## When not to use
+- Primary request is **CSS-only** styling strategy (use the **styled-components** skill)
+- Primary request is **JavaScript-only** logic (use the **javascript** / **typescript** skill)
+- Framework-specific component logic not centered on markup
+- Backend/API design unrelated to markup
+
+## Truthfulness and claims
+- Do not invent browser support percentages, survey stats, or traffic numbers
+- Do not claim there is one official global ranking of HTML guides — distinguish **authority** (standards) from **popularity** (usage/traffic)
+- Never invent statistics, versions, or survey results
+- Label third-party traffic metrics as **estimates**
+- For uncertain edge behavior (validator quirks, ARIA pattern correctness, screen-reader output), prefer **verify with a minimal repro + Nu HTML Checker + screen-reader pass** over guessing
+
+## Self-contained operating mode
+- **Default:** follow **Embedded implementation standard** in this file for all recommendations
+- **Do not** rely on parsing optional reference URLs to decide routine markup, accessibility patterns, or document metadata
+- Use external links **only** when:
+  - the user asks for citations or "official docs"
+  - behavior is ambiguous/edge-case and needs verification
+  - standards-version confirmation is required (WHATWG HTML, WCAG 2.2)
+
+---
+
+## Embedded implementation standard
+
+### 0) File separation (required)
+- Treat **`.html` as markup-only** for authored pages: structure, text, media, and **links** to other assets — not a container for large inline styles or application scripts.
+- **Styles** live in one or more **`.css` files**; reference them from the document head with `<link rel="stylesheet" href="…">` (adjust paths if a build step emits different URLs).
+- **Scripts** live in **`.js` or `.mjs` files** (or `.ts` compiled to `.js`); reference them with `<script src="…"></script>` (or `<script type="module" src="…"></script>` when the script uses ES module syntax). Do **not** embed application logic in inline `<script>…</script>` bodies.
+- **Inline `style=""` attributes** are not the home for authored layout or theme; use classes and external stylesheets (see the **styled-components** skill). Reserve inline styles only for **tiny, dynamic** values when no class-based token suffices (rare).
+- **Exception:** environments that **cannot** load external assets (some email templates, locked sandboxes, single-file demos) may inline; default for normal web pages is always **three files minimum** when the page needs CSS and JS.
+
+### 0.1) Script placement (required, project rule)
+
+Script type determines placement. Apply the rule for each script independently; never scatter scripts mid-document.
+
+| Script type | Placement | Notes |
+|---|---|---|
+| `<script type="module" src="…">` | **`<head>`** | Implicitly deferred — never render-blocking; early placement enables `<link rel="modulepreload">` for sub-module preloading. |
+| `<script src="…">` (non-module, no `defer`) | **End of `<body>`, immediately before `</body>`** | Parser has already built the DOM by the time it executes; `defer` is unavailable or unsupported. |
+| `<script src="…" defer>` | **`<head>`** (or end of `<body>`) | Both are equivalent; prefer `<head>` with `defer` when early download matters; end-of-body when simplicity is preferred and early download is irrelevant. |
+| `<script src="…" async>` | `<head>` | Use **only** for truly independent scripts (analytics, chat widgets) that have **no** DOM dependency and **no** ordering requirement. Never use `async` for application scripts. |
+| Inline `<script>` — application logic | **Banned** | See §0. |
+
+Additional rules:
+- Do **not** scatter scripts mid-document regardless of type.
+- Order module scripts within `<head>` in **dependency order** (polyfills / shared utilities first, app entry last); add `<link rel="modulepreload" href="…">` for critical sub-modules when load performance matters.
+- Non-module end-of-body scripts are also ordered by dependency: helpers/polyfills first, app entry last.
+
+```html
+<!-- good: module scripts in <head> (deferred), legacy polyfill at end of body -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Example</title>
+    <link rel="stylesheet" href="./styles.css">
+    <link rel="modulepreload" href="./app.js">
+    <script type="module" src="./app.js"></script>
+  </head>
+  <body>
+    <main id="ts-root">…</main>
+
+    <!-- non-module polyfill that has no defer support goes at end of body -->
+    <script src="./vendor/legacy-polyfill.js"></script>
+  </body>
+</html>
+```
+
+```html
+<!-- bad: type="module" script at end of body — wastes implicit defer advantage, prevents modulepreload -->
+<body>
+  <main>…</main>
+  <script type="module" src="./app.js"></script>
+</body>
+```
+
+```html
+<!-- bad: non-module script mid-document (render-blocking, unpredictable DOM state) -->
+<body>
+  <header>…</header>
+  <script src="./header-thing.js"></script>
+  <main>…</main>
+</body>
+```
+
+### 1) Document baseline (required)
+- Use `<!doctype html>`
+- Set `<html lang="...">` to the document language
+- Include `<meta charset="utf-8">`
+- Include `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- Include a unique, descriptive `<title>`
+
+### 2) Semantic structure (required)
+- Prefer semantic elements over generic containers:
+  - layout/regions: `header`, `nav`, `main`, `aside`, `footer`
+  - content: `article`, `section`, `figure`, `figcaption`
+  - text semantics: `strong`, `em`, `blockquote`, `cite`, `time`
+- Use `section` only when it has a meaningful heading or grouping purpose
+- Keep DOM structure shallow and readable; avoid unnecessary wrapper nesting
+
+### 3) Heading and landmark rules
+- Use a logical heading hierarchy (`h1` → `h2` → `h3`...)
+- Do not skip heading levels without reason
+- Ensure one clear page-level heading strategy
+- Ensure primary content is inside `main`
+
+### 4) Interactive element rules
+- Use **`button`** for actions, **`a`** for navigation
+- Never use non-interactive elements (`div`, `span`) as controls unless absolutely necessary
+- If custom controls are required, they must support **keyboard, focus, role, and state** semantics (consult ARIA Authoring Practices Guide before inventing one)
+
+### 5) Forms (required for form UIs)
+- Every form control must have an associated label (`<label for>` or wrapped label)
+- Group related options with `fieldset` and `legend`
+- Use appropriate input types (`email`, `tel`, `url`, `date`, `number`, etc.)
+- Use `name` attributes for successful form submission mapping
+- **Do not use placeholder text as a label replacement**
+- Required/error/help text must be visible and understandable in **text, not color alone**
+
+### 6) Accessibility defaults (required)
+- **Keyboard operability** for all interactive controls
+- **Visible focus indicator** must remain present (do not remove `:focus-visible` styling without a comparable replacement — see the **styled-components** skill)
+- **Meaningful link text** (avoid vague labels such as "click here", "read more")
+- **Informative images** need meaningful `alt`; **decorative images** should use empty `alt=""`
+- Announce **status / error updates** in an accessible way when forms are dynamic (`aria-live`, `role="status"`, `role="alert"` as appropriate)
+
+### 7) Tables and media
+- Use **tables only for tabular data**, not page layout
+- For data tables, include header cells (`th`), `scope`, and associations where needed (`headers` / `id`)
+- Provide **captions / transcripts** for audio/video media when relevant to content meaning
+- Pair `<img>` with explicit `width`/`height` (or `aspect-ratio` in CSS) to avoid layout shift
+
+### 8) Metadata and discoverability
+- Add accurate metadata (`title`, optional meta description)
+- Use **canonical URLs** where duplicate URL variants exist
+- Keep URL and heading structure descriptive and human-readable
+- Avoid spam tactics (keyword stuffing, hidden text, manipulative markup)
+
+### 9) Validation and quality gate
+- Validate HTML with **Nu HTML Checker** before finalizing significant markup work
+- Run accessibility checks: **automated** (axe, Lighthouse) **plus manual keyboard pass**
+- Treat validator / a11y issues as **must-fix** unless intentionally documented
+
+### 10) Script-targeted `id` names (project convention)
+- Give any **`id` that scripts select or update** a leading **`js-`** or **`ts-`** prefix so reviewers can see script ownership without opening every module.
+- Use **`js-`** when the consuming code lives in **`.js` / `.mjs`** (or the project treats the hook as plain JavaScript).
+- Use **`ts-`** when the consuming code lives in **`.ts` / `.tsx`** (or the build is TypeScript-first for that feature).
+- After the prefix, keep the token **`kebab-case`** and descriptive (e.g. `js-todo-list`, `ts-chart-root`); **`id` uniqueness** on the document still applies.
+- Elements referenced **only** by declarative HTML (for example **`for`/`id`**, URL fragments, **`aria-labelledby`**) **without** script queries may omit the prefix; if the same node is **both** scripted and referenced that way, **one** `id` with the script prefix keeps markup and scripts aligned.
+
+---
+
+## Working method
+1. Identify user intent: **implementation**, **learning**, or **audit**
+2. Start with **semantic native HTML** choices — pick `button` / `a` / `nav` / `main` etc. before reaching for `div` + ARIA
+3. Apply **accessibility defaults** (section 6):
+   - proper heading structure and landmarks
+   - explicit form labels
+   - keyboard operability and visible focus
+   - meaningful link text
+   - image `alt` strategy
+4. Add **metadata and SEO basics** where relevant (section 8)
+5. Enforce **file separation** (section 0) and **document baseline** (section 1): linked `.css` / `.js`, no inline app CSS/JS unless the delivery context forbids externals
+6. When scripts query nodes by **`id`**, apply **section 10** (`js-` / `ts-` prefix convention)
+7. Recommend **validation** (section 9) via Nu HTML Checker + automated and manual a11y checks
+8. Provide concise recommendations; include external links only when asked or needed
+
+## Response template
+1. Summary decision (why this approach)
+2. Best-practice recommendations
+3. Common mistakes to avoid
+4. Verification checklist
+5. Sources (optional unless requested)
+
+## Quality bar before final answer
+- Guidance cites **embedded sections** above, not unnamed blogs
+- Recommendations are **semantic-first** and **accessibility-first** (sections 2, 3, 4, 6)
+- **Document baseline** is present (`<!doctype html>`, `lang`, `charset`, viewport, `title`) — section 1
+- **Markup, CSS, and JS are in separate files** when the page uses authored styles or scripts (section 0)
+- **Script placement follows the type-based rule (section 0.1):** `type="module"` scripts are in `<head>`; non-module scripts without `defer` are at the end of `<body>`; `async` is used only for truly independent scripts; no scripts are scattered mid-document; inline application logic remains banned
+- Script-selected `id`s follow **section 10** (`js-` / `ts-` prefix) when external scripts wire the DOM
+- Headings follow a **logical hierarchy** (section 3); primary content lives in `main`
+- Form controls are **labeled**, with `fieldset`/`legend` where relevant; **placeholder is not used as a label replacement** (section 5)
+- Tables are used **only for tabular data** with proper `th` / `scope` (section 7)
+- Accessibility-sensitive choices mention **keyboard, focus, contrast, and `alt` strategy** explicitly when relevant (section 6)
+- Claims are either sourced or clearly labeled as opinion/estimate
+- Includes at least one **validation step** (`validator.w3.org/nu`) — section 9
+- No fabricated statistics; uncertain edges flagged for manual verification
+
+---
+
+## Source hierarchy (for conflicts only)
+1. **Normative standards:** WHATWG HTML, W3C WCAG 2.2
+2. **Practical implementation docs:** MDN, web.dev, W3C WAI tutorials, WCAG quickref, ARIA Authoring Practices Guide
+3. **Adoption context:** Stack Overflow Developer Survey
+4. **Search guidance:** Google SEO Starter Guide
+
+## Optional references (citations / verification only)
+- https://html.spec.whatwg.org/multipage/
+- https://developer.mozilla.org/en-US/docs/Web/HTML
+- https://www.w3.org/TR/WCAG22/
+- https://www.w3.org/WAI/WCAG22/quickref/
+- https://www.w3.org/WAI/tutorials/
+- https://www.w3.org/WAI/ARIA/apg/
+- https://web.dev/learn/html/welcome
+- https://developers.google.com/search/docs/fundamentals/seo-starter-guide
+- https://survey.stackoverflow.co/2024/technology/#most-popular-technologies-language-prof
+- https://validator.w3.org/nu/
+
+---
+
+## Project automation
+- If the project includes a `.cursor/hooks/html-guard.mjs` hook, it may run `postToolUse` when writing or reviewing `.html` files and may inject follow-up context for baseline HTML issues.