swe-workflow-skills 0.1.0

package/scripts/resolve.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// Resolve roles.json into skill lists and skillOverrides maps.
+//
+// Dependency-free helper shared by install.mjs / uninstall.mjs (import) and by the
+// SessionStart hook + the /role command (CLI). Pure JSON + set logic — runs on
+// Linux, macOS, and Windows with only the Node that Claude Code already requires.
+//
+// Usage (CLI):
+//   node resolve.mjs roles                       List role keys + labels (TSV).
+//   node resolve.mjs skills <role>               Resolved skill set for a role (one per line).
+//   node resolve.mjs label  <role>               Human label for a role.
+//   node resolve.mjs overrides [role]            Emit a skillOverrides JSON object marking
+//                                                every installed skill outside (pinned ∪ role)
+//                                                as "name-only". Installed skill names are read
+//                                                from stdin (newline-separated). No role => only
+//                                                the pinned set stays on (the baseline).
+//   node resolve.mjs apply <settings.local.json> <skills_dir> [role]
+//                                                Merge the name-only baseline (for [role], or
+//                                                pinned-only) into the settings file's
+//                                                skillOverrides, preserving all other keys and
+//                                                any overrides for non-installed skills.
+//   node resolve.mjs prune <settings.local.json> [skill ...]
+//                                                Remove the given skills from the settings
+//                                                file's skillOverrides (used by uninstall).
+//                                                Drops skillOverrides entirely when empty.
+//   node resolve.mjs validate <skills_dir>       Integrity check: every referenced skill
+//                                                exists, and every non-meta skill is in >=1 role.
+//
+// roles.json is read from $ROLES_JSON if set, else ../roles.json relative to this file.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_ROLES_JSON =
+  process.env.ROLES_JSON || join(HERE, "..", "roles.json");
+
+// ---- core resolution -------------------------------------------------------
+
+export function loadRoles(rolesPath = DEFAULT_ROLES_JSON) {
+  return JSON.parse(readFileSync(rolesPath, "utf-8"));
+}
+
+function roleOrDie(data, role) {
+  const roles = data.roles || {};
+  if (!(role in roles)) {
+    const known = Object.keys(roles).sort().join(", ");
+    die(`unknown role '${role}' (known: ${known})`);
+  }
+  return roles[role];
+}
+
+// Role working set = its core set UNION its own skills, order-stable.
+export function resolvedSkills(data, role) {
+  const r = roleOrDie(data, role);
+  const core = (data.core || {})[r.core || "universal"] || [];
+  const seen = new Set();
+  const out = [];
+  for (const skill of [...core, ...(r.skills || [])]) {
+    if (!seen.has(skill)) {
+      seen.add(skill);
+      out.push(skill);
+    }
+  }
+  return out;
+}
+
+// Skills that stay `on` (full description, auto-trigger): the pinned set, plus the
+// active role's working set when a role is given.
+export function keepOnSet(data, role) {
+  const keep = new Set(data.pinned || []);
+  if (role) for (const s of resolvedSkills(data, role)) keep.add(s);
+  return keep;
+}
+
+export function nameonlyMap(data, installed, role) {
+  const keepOn = keepOnSet(data, role);
+  const map = {};
+  for (const s of installed) if (!keepOn.has(s)) map[s] = "name-only";
+  return map;
+}
+
+// Directory entries that are skills (subdirectories), sorted.
+export function installedSkills(skillsDir) {
+  return readdirSync(skillsDir)
+    .filter((e) => statSync(join(skillsDir, e)).isDirectory())
+    .sort();
+}
+
+// ---- settings I/O ----------------------------------------------------------
+
+// Recursively sort object keys so output is deterministic (mirrors Python's
+// json.dump(..., sort_keys=True)).
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = sortKeysDeep(value[k]);
+    return out;
+  }
+  return value;
+}
+
+export function loadSettings(settingsPath) {
+  if (existsSync(settingsPath) && statSync(settingsPath).isFile()) {
+    try {
+      return JSON.parse(readFileSync(settingsPath, "utf-8")) || {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+export function writeSettings(settingsPath, settings) {
+  mkdirSync(dirname(resolvePath(settingsPath)), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(sortKeysDeep(settings), null, 2) + "\n");
+}
+
+// ---- apply / prune ---------------------------------------------------------
+
+// Merge the name-only baseline into a settings file. Returns {nameOnly, on, role}.
+export function applyBaseline(data, settingsPath, skillsDir, role) {
+  if (role === "all" || role === "none") role = null;
+  if (role) roleOrDie(data, role);
+
+  const installed = installedSkills(skillsDir);
+  const desired = nameonlyMap(data, installed, role); // {skill: "name-only"} tail
+
+  const settings = loadSettings(settingsPath);
+  let existing = settings.skillOverrides;
+  if (!existing || typeof existing !== "object" || Array.isArray(existing)) existing = {};
+
+  // Preserve overrides for skills we don't manage (not installed here); we own every
+  // installed skill's entry: name-only for the tail, absent (=> on) otherwise.
+  const installedSet = new Set(installed);
+  const merged = {};
+  for (const [k, v] of Object.entries(existing)) if (!installedSet.has(k)) merged[k] = v;
+  Object.assign(merged, desired);
+  settings.skillOverrides = merged;
+
+  writeSettings(settingsPath, settings);
+  const nameOnly = Object.keys(desired).length;
+  return { nameOnly, on: installed.length - nameOnly, role };
+}
+
+// Remove the given skills from a settings file's skillOverrides. Returns removed count.
+export function pruneSettings(settingsPath, skills) {
+  if (!(existsSync(settingsPath) && statSync(settingsPath).isFile())) return { removed: 0, missing: true };
+  const settings = loadSettings(settingsPath);
+  const overrides = settings.skillOverrides;
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    return { removed: 0, noOverrides: true };
+  }
+  const want = new Set(skills);
+  let removed = 0;
+  for (const s of want) {
+    if (s in overrides) {
+      delete overrides[s];
+      removed++;
+    }
+  }
+  if (Object.keys(overrides).length > 0) settings.skillOverrides = overrides;
+  else delete settings.skillOverrides; // drop the empty key entirely
+  writeSettings(settingsPath, settings);
+  return { removed };
+}
+
+// ---- validate --------------------------------------------------------------
+
+export function validate(data, skillsDir) {
+  const errors = [];
+
+  // Every skill referenced anywhere in the SSOT.
+  const referenced = new Set([...(data.pinned || []), ...(data.meta_only || [])]);
+  for (const core of Object.values(data.core || {})) for (const s of core) referenced.add(s);
+  const inARole = new Set();
+  for (const role of Object.keys(data.roles || {})) {
+    for (const s of resolvedSkills(data, role)) {
+      referenced.add(s);
+      inARole.add(s);
+    }
+  }
+
+  // Every referenced skill must exist on disk.
+  for (const skill of [...referenced].sort()) {
+    if (!isDir(join(skillsDir, skill))) errors.push(`referenced skill missing on disk: ${skill}`);
+  }
+
+  // Every non-meta skill on disk must belong to >=1 role (no orphans).
+  const meta = new Set(data.meta_only || []);
+  const universal = new Set((data.core || {}).universal || []);
+  const technical = new Set((data.core || {}).technical || []);
+  const covered = new Set([...inARole, ...universal, ...technical]);
+  for (const entry of readdirSync(skillsDir).sort()) {
+    if (!isDir(join(skillsDir, entry))) continue;
+    if (meta.has(entry)) continue;
+    if (!covered.has(entry)) errors.push(`orphan skill (in no role/core): ${entry}`);
+  }
+  return errors;
+}
+
+function isDir(p) {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+
+// ---- CLI -------------------------------------------------------------------
+
+export function die(msg, code = 1) {
+  process.stderr.write(`resolve.mjs: ${msg}\n`);
+  process.exit(code);
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+const CLI = {
+  roles(data) {
+    for (const [key, r] of Object.entries(data.roles || {})) {
+      process.stdout.write(`${key}\t${r.label || key}\n`);
+    }
+  },
+  skills(data, args) {
+    if (!args[0]) die("skills requires a <role>");
+    for (const s of resolvedSkills(data, args[0])) process.stdout.write(s + "\n");
+  },
+  label(data, args) {
+    if (!args[0]) die("label requires a <role>");
+    process.stdout.write(roleOrDie(data, args[0]).label || args[0]);
+    process.stdout.write("\n");
+  },
+  overrides(data, args) {
+    const role = args[0] || null;
+    if (role) roleOrDie(data, role);
+    const installed = readStdin()
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+    process.stdout.write(JSON.stringify(sortKeysDeep(nameonlyMap(data, installed, role)), null, 2) + "\n");
+  },
+  apply(data, args) {
+    if (args.length < 2) die("apply requires <settings.local.json> <skills_dir> [role]");
+    const { nameOnly, on, role } = applyBaseline(data, args[0], args[1], args[2]);
+    process.stdout.write(
+      `applied: ${nameOnly} name-only, ${on} on (role=${role || "baseline"}) -> ${args[0]}\n`,
+    );
+  },
+  prune(_data, args) {
+    if (!args[0]) die("prune requires <settings.local.json> [skill ...]");
+    const settingsPath = args[0];
+    const res = pruneSettings(settingsPath, args.slice(1));
+    if (res.missing) process.stdout.write(`pruned: 0 (no settings file at ${settingsPath})\n`);
+    else if (res.noOverrides) process.stdout.write(`pruned: 0 (no skillOverrides) -> ${settingsPath}\n`);
+    else process.stdout.write(`pruned: ${res.removed} skillOverrides entries -> ${settingsPath}\n`);
+  },
+  validate(data, args) {
+    if (!args[0]) die("validate requires a <skills_dir>");
+    const errors = validate(data, args[0]);
+    if (errors.length) {
+      for (const e of errors) process.stderr.write(`FAIL: ${e}\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`OK: roles.json integrity verified against ${args[0]}\n`);
+  },
+};
+
+// Commands that don't read roles.json — they work on a settings file alone, so they
+// must run even when resolve.mjs is installed away from roles.json (e.g. under hooks/).
+const NO_ROLES_DATA = new Set(["prune"]);
+
+function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+  if (!cmd || !(cmd in CLI)) {
+    die(`usage: resolve.mjs <${Object.keys(CLI).join("|")}> [args]`, 2);
+  }
+  const data = NO_ROLES_DATA.has(cmd) ? {} : loadRoles();
+  CLI[cmd](data, args);
+}
+
+// Run as CLI only when invoked directly (not when imported). Compare case-insensitively
+// on Windows, where the invoking path's drive-letter / casing may differ from the
+// module URL's even when they point at the same file.
+function samePath(a, b) {
+  const x = resolvePath(a);
+  const y = resolvePath(b);
+  return process.platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+if (process.argv[1] && samePath(process.argv[1], fileURLToPath(import.meta.url))) {
+  main();
+}

package/skills/accessibility-design/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: accessibility-design
+description: "Design and implement accessible web/mobile apps to WCAG 2.1/2.2 — semantic HTML, ARIA patterns, keyboard navigation, focus management, color contrast, screen readers, accessible forms. Triggers: accessibility, a11y, WCAG, screen reader, keyboard navigation, ARIA, focus management, color contrast, alt text, semantic HTML, tab order, focus trap, skip link, announce. Build it in, don't bolt it on."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Accessibility Design
+
+Build accessibility into applications from the start. Accessibility is not a feature — it's a quality attribute, like performance or security. Retrofitting it is 10x harder than building it in.
+
+## Core Principle
+
+**Use semantic HTML first, ARIA second, custom JavaScript last.** A native `<button>` gives you keyboard support, focus management, and screen reader announcement for free. A `<div onClick>` gives you none of that and requires manual reimplementation of every behavior the browser provides natively.
+
+## Workflow
+
+### Step 1: Understand the Requirements
+
+Determine the target compliance level:
+
+- **WCAG 2.1 Level A**: Minimum baseline (avoid lawsuits, but still inaccessible)
+- **WCAG 2.1 Level AA**: Industry standard (recommended minimum for all projects)
+- **WCAG 2.2 Level AA**: Current standard, adds mobile and cognitive accessibility
+- **WCAG Level AAA**: Aspirational — few sites achieve this fully
+
+For most projects, **target WCAG 2.1 AA** as the minimum. Level AAA for specific features where feasible.
+
+### Step 2: Apply Semantic HTML
+
+Before reaching for ARIA, use the right HTML element:
+
+| Instead of... | Use... | You get for free... |
+|--------------|--------|---------------------|
+| `<div onClick>` | `<button>` | Focus, Enter/Space activation, role announcement |
+| `<div>` for navigation | `<nav>` | Landmark for screen reader navigation |
+| `<span>` for heading | `<h1>`-`<h6>` | Document outline, heading navigation |
+| `<div>` for list | `<ul>/<ol>` | List count announcement, list navigation |
+| `<div>` for input | `<input>` + `<label>` | Label association, auto-focus, form submission |
+| `<div>` for table | `<table>` | Row/column navigation, header association |
+| Custom dropdown | `<select>` or `<details>` | Keyboard navigation, screen reader support |
+
+See [references/accessibility-patterns.md](references/accessibility-patterns.md) for comprehensive patterns.
+
+### Step 3: Design Keyboard Navigation
+
+Every interactive element must be operable by keyboard alone:
+
+**Tab order:** Interactive elements should follow a logical reading order. Don't use `tabindex` values > 0 (they override the natural order). Use `tabindex="0"` to add non-interactive elements to the tab order when needed, and `tabindex="-1"` to make elements focusable programmatically but not in the tab sequence.
+
+**Focus visibility:** Focused elements must have a visible indicator. Never `outline: none` without providing an alternative. Use `:focus-visible` (shows focus ring only for keyboard users, not mouse clicks).
+
+**Keyboard shortcuts for common patterns:**
+
+| Pattern | Keys |
+|---------|------|
+| Buttons | Enter or Space to activate |
+| Links | Enter to follow |
+| Menus | Arrow keys to navigate, Enter to select, Escape to close |
+| Tabs | Arrow keys between tabs, Tab to move focus into panel |
+| Modals | Tab cycles within modal (focus trap), Escape to close |
+| Autocomplete | Arrow keys to navigate suggestions, Enter to select |
+
+### Step 4: Design Focus Management
+
+Focus management is critical for dynamic content. When the page changes without a full reload, focus must move to the right place:
+
+| Scenario | Focus should go to... |
+|----------|----------------------|
+| Modal opens | First focusable element inside the modal |
+| Modal closes | The element that triggered the modal |
+| Item deleted from list | Next item in list, or previous if last was deleted |
+| Error after form submit | First field with an error |
+| Page/route change | Main content area or page heading |
+| Toast notification | Do NOT move focus (announce with aria-live instead) |
+
+### Step 5: Handle Dynamic Content
+
+When content changes without page reload, screen readers need to be notified:
+
+**aria-live regions:**
+- `aria-live="polite"` — Announce when the screen reader is idle (status messages, search results count)
+- `aria-live="assertive"` — Interrupt immediately (errors, critical alerts)
+
+**Common announcements:**
+- Form errors: "3 errors found. First error: Email is required."
+- Search results: "24 results found for 'react'."
+- Toast: "Settings saved successfully."
+- Loading: "Loading your dashboard..." → "Dashboard loaded."
+
+### Step 6: Ensure Visual Accessibility
+
+**Color contrast:**
+- Normal text: 4.5:1 ratio minimum (AA)
+- Large text (18px+ or 14px+ bold): 3:1 ratio minimum (AA)
+- UI components and graphical objects: 3:1 ratio minimum
+- Don't convey information by color alone — use icons, patterns, or text labels alongside color
+
+**Typography and spacing:**
+- Body text: minimum 16px (1rem)
+- Line height: at least 1.5 for body text
+- Paragraph spacing: at least 2x font size
+- Users must be able to zoom to 200% without horizontal scrolling
+
+### Step 7: Validate
+
+Automated testing catches ~30% of accessibility issues. Manual testing catches the rest.
+
+**Automated:**
+- Run axe-core or Lighthouse accessibility audit
+- Add eslint-plugin-jsx-a11y to catch common React issues at build time
+- Include @axe-core/react in development mode for runtime warnings
+
+**Manual:**
+- [ ] Navigate the entire flow using only keyboard (no mouse)
+- [ ] Test with a screen reader (VoiceOver on Mac, NVDA on Windows)
+- [ ] Verify all images have meaningful alt text (or `alt=""` for decorative)
+- [ ] Verify color contrast with a contrast checker tool
+- [ ] Test at 200% zoom — no horizontal scroll, no overlapping text
+- [ ] Verify all form fields have associated labels
+- [ ] Verify error messages are announced to screen readers
+
+## Principles Applied
+
+- **KISS**: Use native HTML first. Every custom ARIA widget is code you have to maintain and test.
+- **Progressive enhancement**: Build the accessible version first, then enhance for visual design. Not the other way around.
+- **DRY**: Accessible patterns in shared components (Button, Input, Modal) mean every consumer gets accessibility for free.
+- **Defense in depth**: Automated linting + automated testing + manual testing. No single method catches everything.

package/skills/accessibility-design/evals/evals.json

@@ -0,0 +1,51 @@
+{
+  "skill_name": "accessibility-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building a modal dialog component in React for confirming destructive actions (like deleting a project). Make it accessible.",
+      "expected_output": "Should implement the full accessible modal pattern: role=dialog, aria-modal, focus trap, Escape to close, focus restoration, background inert, and proper labeling.",
+      "assertions": [
+        "Uses role='dialog' and aria-modal='true'",
+        "Labels the dialog with aria-labelledby pointing to the title",
+        "Implements focus trap (Tab cycles within modal)",
+        "Moves focus to the first focusable element on open",
+        "Returns focus to the trigger element on close",
+        "Closes on Escape key",
+        "Makes background content inert while open",
+        "Destructive button is NOT the default focus (Cancel is safer default)",
+        "Uses semantic HTML (button elements, not divs with onClick)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Audit this React component for accessibility issues:\n\n<div className=\"card\" onClick={() => navigate(`/project/${id}`)}>\n  <div className=\"title\">{name}</div>\n  <img src={thumbnail} />\n  <div className=\"badge\" style={{color: status === 'active' ? 'green' : 'red'}}>\n    {status}\n  </div>\n  <div className=\"actions\">\n    <div className=\"btn\" onClick={(e) => { e.stopPropagation(); onDelete(id); }}>\n      🗑️\n    </div>\n  </div>\n</div>",
+      "expected_output": "Should identify all accessibility issues: clickable div instead of link/button, missing alt on img, color-only status indicator, icon button without label, no keyboard support.",
+      "assertions": [
+        "Identifies clickable div should be an <a> or <Link> (for navigation)",
+        "Identifies missing alt attribute on the image",
+        "Identifies color-only status indicator (green/red without text or icon)",
+        "Identifies delete button as a div — should be <button>",
+        "Identifies emoji icon without accessible label (aria-label needed)",
+        "Notes that div+onClick has no keyboard support (no Enter/Space handling)",
+        "Provides corrected accessible version of the component",
+        "Corrected version uses semantic HTML (a, button, img alt)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're building a form with email, password, a terms checkbox, and a submit button. The designer wants inline validation that shows errors as you type. Make it accessible.",
+      "expected_output": "Should implement accessible form with labels, error announcements, aria-invalid, aria-describedby, and proper validation timing.",
+      "assertions": [
+        "Every input has an associated <label> with htmlFor",
+        "Error messages use aria-describedby to link to their field",
+        "Fields with errors have aria-invalid='true'",
+        "Errors are announced to screen readers (role='alert' or aria-live)",
+        "Validation is debounced (not on every keystroke)",
+        "Checkbox has an associated label (clickable text)",
+        "Submit button is a <button type='submit'>",
+        "On submit with errors, focus moves to the first field with an error"
+      ]
+    }
+  ]
+}