swe-workflow-skills 0.1.0

package/skills/accessibility-design/references/accessibility-patterns.md

@@ -0,0 +1,321 @@
+# Accessibility Patterns
+
+## Contents
+- Common component patterns
+- Form accessibility
+- Modal and dialog patterns
+- Navigation patterns
+- Image and media accessibility
+- React-specific patterns
+
+## Common Component Patterns
+
+### Button
+```html
+<!-- GOOD: Native button — keyboard support, role, focus all built in -->
+<button type="button" onClick={handleClick}>
+  Save Changes
+</button>
+
+<!-- GOOD: Button with loading state -->
+<button type="button" disabled={isLoading} aria-busy={isLoading}>
+  {isLoading ? 'Saving...' : 'Save Changes'}
+</button>
+
+<!-- GOOD: Icon button with accessible label -->
+<button type="button" aria-label="Delete item">
+  <TrashIcon aria-hidden="true" />
+</button>
+
+<!-- BAD: Div pretending to be a button — no keyboard, no role, no focus -->
+<div className="btn" onClick={handleClick}>Save</div>
+```
+
+### Link vs Button
+- Use `<a>` for navigation (goes somewhere)
+- Use `<button>` for actions (does something)
+- Never use `<a href="#">` as a button — use a real `<button>`
+
+### Toggle / Switch
+```html
+<button
+  role="switch"
+  aria-checked={isEnabled}
+  onClick={() => setIsEnabled(!isEnabled)}
+>
+  Dark mode
+</button>
+```
+
+### Tabs
+```html
+<div role="tablist" aria-label="Account settings">
+  <button role="tab" aria-selected={activeTab === 'general'} 
+          aria-controls="panel-general" id="tab-general">
+    General
+  </button>
+  <button role="tab" aria-selected={activeTab === 'security'}
+          aria-controls="panel-security" id="tab-security">
+    Security
+  </button>
+</div>
+<div role="tabpanel" id="panel-general" aria-labelledby="tab-general"
+     hidden={activeTab !== 'general'}>
+  General settings content...
+</div>
+```
+
+Keyboard: Arrow keys between tabs, Tab moves focus into the active panel.
+
+### Accordion
+```html
+<h3>
+  <button aria-expanded={isOpen} aria-controls="section-1">
+    FAQ Question
+  </button>
+</h3>
+<div id="section-1" role="region" hidden={!isOpen}>
+  Answer content...
+</div>
+```
+
+## Form Accessibility
+
+### Labels
+Every input MUST have an associated label. No exceptions.
+
+```html
+<!-- GOOD: Explicit label with htmlFor -->
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" />
+
+<!-- GOOD: Wrapping label (implicit association) -->
+<label>
+  Email address
+  <input type="email" />
+</label>
+
+<!-- GOOD: aria-label for visually hidden label -->
+<input type="search" aria-label="Search projects" />
+
+<!-- BAD: Placeholder as label — disappears on focus, low contrast -->
+<input type="email" placeholder="Email address" />
+```
+
+### Error messages
+```html
+<label htmlFor="email">Email address</label>
+<input 
+  id="email" 
+  type="email"
+  aria-invalid={hasError}
+  aria-describedby={hasError ? "email-error" : undefined}
+/>
+{hasError && (
+  <p id="email-error" role="alert">
+    Please enter a valid email address
+  </p>
+)}
+```
+
+Key: `aria-invalid` tells screen readers the field has an error. `aria-describedby` links the error message to the field. `role="alert"` announces the error immediately.
+
+### Required fields
+```html
+<label htmlFor="name">
+  Name <span aria-hidden="true">*</span>
+</label>
+<input id="name" required aria-required="true" />
+```
+
+The `*` is visual-only (`aria-hidden`). `aria-required` is the programmatic indicator.
+
+### Form submission feedback
+```html
+<!-- Status region for form-level messages -->
+<div aria-live="polite" role="status">
+  {submitSuccess && "Your changes have been saved."}
+  {submitError && "Failed to save. Please try again."}
+</div>
+```
+
+## Modal and Dialog Patterns
+
+```html
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="modal-title"
+  aria-describedby="modal-description"
+>
+  <h2 id="modal-title">Delete Project</h2>
+  <p id="modal-description">
+    This will permanently delete "My Project" and all its data.
+  </p>
+  <button onClick={onCancel}>Cancel</button>
+  <button onClick={onConfirm}>Delete</button>
+</div>
+```
+
+**Required behaviors:**
+1. Focus moves to the first focusable element when modal opens
+2. Tab cycles within the modal (focus trap — focus cannot leave)
+3. Escape key closes the modal
+4. Focus returns to the triggering element when modal closes
+5. Background content has `aria-hidden="true"` and `inert` while modal is open
+
+### React focus trap implementation
+```typescript
+function useFocusTrap(ref: RefObject<HTMLElement>) {
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    const focusableSelector = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+    const focusable = element.querySelectorAll(focusableSelector);
+    const first = focusable[0] as HTMLElement;
+    const last = focusable[focusable.length - 1] as HTMLElement;
+
+    first?.focus();
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Tab') {
+        if (e.shiftKey && document.activeElement === first) {
+          e.preventDefault();
+          last?.focus();
+        } else if (!e.shiftKey && document.activeElement === last) {
+          e.preventDefault();
+          first?.focus();
+        }
+      }
+    };
+
+    element.addEventListener('keydown', handleKeyDown);
+    return () => element.removeEventListener('keydown', handleKeyDown);
+  }, [ref]);
+}
+```
+
+## Navigation Patterns
+
+### Skip link (required for keyboard users)
+```html
+<!-- First element in the body -->
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+<!-- ... header, nav ... -->
+<main id="main-content">
+  Page content
+</main>
+```
+
+The skip link is visually hidden until focused (keyboard user presses Tab).
+
+### Landmarks
+```html
+<header>    <!-- banner landmark -->
+  <nav aria-label="Main navigation">  <!-- navigation landmark -->
+    ...
+  </nav>
+</header>
+<main>      <!-- main landmark -->
+  <section aria-label="Dashboard">     <!-- region landmark -->
+    ...
+  </section>
+</main>
+<aside>     <!-- complementary landmark -->
+  ...
+</aside>
+<footer>    <!-- contentinfo landmark -->
+  ...
+</footer>
+```
+
+Screen reader users navigate by landmarks. Proper landmark structure lets them jump directly to the section they need.
+
+### Breadcrumbs
+```html
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/projects">Projects</a></li>
+    <li><a href="/projects/123" aria-current="page">My Project</a></li>
+  </ol>
+</nav>
+```
+
+## Image and Media Accessibility
+
+### Images
+```html
+<!-- Informative image: describe what it shows -->
+<img src="chart.png" alt="Revenue grew 25% from Q1 to Q2 2025" />
+
+<!-- Decorative image: empty alt (don't omit alt entirely) -->
+<img src="decoration.png" alt="" />
+
+<!-- Complex image: describe + link to long description -->
+<figure>
+  <img src="architecture.png" alt="System architecture overview" aria-describedby="arch-desc" />
+  <figcaption id="arch-desc">
+    The system consists of three services: API gateway, processing service, and database.
+    Requests flow from the gateway through the processor to the database.
+  </figcaption>
+</figure>
+```
+
+### Video
+- Provide captions (not just auto-generated)
+- Provide a transcript for audio content
+- Don't autoplay with sound
+- Provide pause/stop controls
+
+## React-Specific Patterns
+
+### Route change announcements
+Single-page apps don't trigger screen reader page announcements on navigation. Add an announcer:
+
+```typescript
+function RouteAnnouncer() {
+  const location = useLocation();
+  const [announcement, setAnnouncement] = useState('');
+
+  useEffect(() => {
+    // Read the page title or a descriptive heading
+    const title = document.title || 'Page loaded';
+    setAnnouncement(title);
+  }, [location]);
+
+  return (
+    <div aria-live="assertive" aria-atomic="true" className="sr-only">
+      {announcement}
+    </div>
+  );
+}
+```
+
+### Visually hidden utility (sr-only)
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+```
+Use for: skip links, form labels that are visually implied by context, additional screen reader context.
+
+### ESLint plugin
+Add `eslint-plugin-jsx-a11y` to catch common issues at development time:
+```json
+{
+  "extends": ["plugin:jsx-a11y/recommended"]
+}
+```
+This catches: missing alt text, invalid ARIA attributes, non-interactive elements with click handlers, missing form labels, and more.

package/skills/api-design/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: api-design
+description: "Design RESTful and GraphQL APIs — endpoint naming, request/response contracts, error handling, pagination, versioning, auth patterns, OpenAPI specs. Triggers: design the API, API contract, REST API, GraphQL schema, error response format, pagination, API versioning, OpenAPI, swagger, endpoints. Use architecture-design for REST-vs-GraphQL or monolith-vs-microservices decisions."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# API Design
+
+Design APIs that are consistent, predictable, and easy to consume. A well-designed API is intuitive to use without reading documentation — but has great documentation anyway.
+
+## Scope Boundary
+
+This skill designs the **contract** (endpoints, request/response shapes, error formats, pagination). For higher-level decisions (REST vs GraphQL, API gateway, authentication strategy), use the `architecture-design` skill first, then return here to design the specifics.
+
+## Workflow
+
+### Step 1: Identify Resources and Operations
+
+Start from the domain model, not the UI:
+
+- **What are the resources?** (nouns: users, orders, products, comments)
+- **What operations exist?** (CRUD + domain-specific: archive, publish, approve)
+- **What are the relationships?** (user has orders, order contains items)
+- **Who consumes this API?** (web app, mobile app, third-party, internal service)
+
+Map each resource to its operations before choosing URLs or methods.
+
+### Step 2: Design Endpoints
+
+Apply RESTful naming conventions — see [references/rest-conventions.md](references/rest-conventions.md):
+
+```
+GET    /api/v1/users          → List users
+POST   /api/v1/users          → Create user
+GET    /api/v1/users/:id      → Get user
+PATCH  /api/v1/users/:id      → Update user (partial)
+DELETE /api/v1/users/:id      → Delete user
+
+# Nested resources (when the child only makes sense in parent context)
+GET    /api/v1/users/:id/orders    → List user's orders
+POST   /api/v1/users/:id/orders    → Create order for user
+
+# Actions that don't map to CRUD
+POST   /api/v1/orders/:id/cancel   → Cancel an order
+POST   /api/v1/users/:id/verify    → Verify a user's email
+```
+
+Present the endpoint list to the user and refine before designing schemas.
+
+### Step 3: Define Request/Response Schemas
+
+For each endpoint, define:
+
+**Request**: Query parameters (for filtering/pagination), path parameters, request body with field types and validation rules.
+
+**Response**: Status code, response body shape, included relationships.
+
+Use consistent patterns across all endpoints — see [references/rest-conventions.md](references/rest-conventions.md) for standard shapes.
+
+Key decisions to make with the user:
+- **ID format**: Integer, UUID, or ULID? (be consistent)
+- **Date format**: ISO 8601 always (`2025-03-05T14:30:00Z`)
+- **Null vs absent**: Are missing fields returned as `null` or omitted?
+- **Envelope or not**: `{ data: [...], meta: {...} }` vs flat response?
+
+### Step 4: Standardize Error Responses
+
+Every API error should use the same shape. Recommend this format:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description for developers",
+    "details": [
+      {
+        "field": "email",
+        "message": "Must be a valid email address"
+      }
+    ]
+  }
+}
+```
+
+Map HTTP status codes consistently:
+- `400` — Client sent invalid data (validation errors)
+- `401` — Authentication required or invalid
+- `403` — Authenticated but not authorized for this action
+- `404` — Resource not found
+- `409` — Conflict (duplicate, state violation)
+- `422` — Valid syntax but semantically invalid (business rule violation)
+- `429` — Rate limited
+- `500` — Server error (never expose internals)
+
+### Step 5: Design Pagination, Filtering, Sorting
+
+For any list endpoint that could return many results:
+
+**Pagination** (recommend cursor-based for most cases):
+```
+GET /api/v1/orders?cursor=abc123&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "def456",
+    "has_more": true
+  }
+}
+```
+
+**Filtering**: Use query parameters with clear naming:
+```
+GET /api/v1/orders?status=pending&created_after=2025-01-01
+```
+
+**Sorting**: Use a `sort` parameter with `-` prefix for descending:
+```
+GET /api/v1/orders?sort=-created_at,total
+```
+
+### Step 6: Define Authentication and Authorization
+
+For each endpoint, specify:
+- **Authentication**: Required? What scheme? (Bearer token, API key, session)
+- **Authorization**: What roles/permissions can access this? Document per-endpoint.
+- **Public endpoints**: Explicitly mark which endpoints don't require auth.
+
+### Step 7: Produce the Specification
+
+Output the API design as one of:
+- **Markdown document** — for internal APIs and quick designs
+- **OpenAPI 3.x spec** — for formal APIs, enables codegen and tooling
+
+Use the template at [templates/api-spec.md](templates/api-spec.md) for markdown output.
+
+## Principles Applied
+
+- **KISS**: Prefer flat resource URLs over deeply nested ones. `/orders?user_id=123` is simpler than `/users/123/orders/456/items/789`.
+- **DRY**: Standardize error format, pagination, and envelope structure once. Don't reinvent per-endpoint.
+- **YAGNI**: Don't add filtering, sorting, or pagination until a list endpoint actually needs them. Add later when the need is real.
+- **Functional Independence**: Each endpoint should do one thing. Avoid "Swiss army knife" endpoints that change behavior based on query parameters.

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

@@ -0,0 +1,48 @@
+{
+  "skill_name": "api-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to design the API for a blog platform. We have users, posts, comments, and tags. Posts can have multiple tags. Comments are threaded (replies to other comments). Users can be authors or admins. The frontend is a Next.js app. Design the REST API.",
+      "expected_output": "Should identify all resources, design endpoints with proper RESTful naming, define request/response schemas, standardize errors, and include pagination for list endpoints.",
+      "assertions": [
+        "Identifies all resources (users, posts, comments, tags)",
+        "Uses plural nouns in URLs (/posts, /comments, /tags)",
+        "Handles the M:N relationship for posts and tags appropriately",
+        "Designs threaded comments without excessive URL nesting",
+        "Defines standard error response format",
+        "Includes pagination for list endpoints",
+        "Specifies auth requirements per endpoint",
+        "Distinguishes author vs admin permissions",
+        "Produces a complete API specification document"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "design api endpoints for user registration, login, password reset, and profile management",
+      "expected_output": "Should design auth-related endpoints following security best practices, not expose sensitive information in responses, and use appropriate HTTP methods.",
+      "assertions": [
+        "POST for registration, login, and password reset (not GET)",
+        "Does not return password hash or sensitive data in responses",
+        "Includes email verification flow",
+        "Password reset uses a token-based flow (not sending password via email)",
+        "Login response includes token and token expiry",
+        "Profile endpoints require authentication",
+        "Standardized error responses for auth failures (401 vs 403)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We have an existing API with these endpoints:\nGET /getUsers\nGET /getUserById?id=123\nPOST /createUser\nPOST /updateUser\nGET /deleteUser?id=123\n\nThis doesn't feel right. Can you redesign it following proper REST conventions?",
+      "expected_output": "Should identify specific violations (verbs in URLs, GET for delete, query params for identity) and redesign using proper REST conventions.",
+      "assertions": [
+        "Identifies that URLs use verbs instead of nouns",
+        "Identifies that DELETE uses GET method",
+        "Identifies that identity is in query params instead of path",
+        "Redesigns to: GET /users, GET /users/:id, POST /users, PATCH /users/:id, DELETE /users/:id",
+        "Explains WHY each change matters (not just 'this is the convention')",
+        "Notes that this is a breaking change requiring versioning or migration plan"
+      ]
+    }
+  ]
+}

package/skills/api-design/references/rest-conventions.md

@@ -0,0 +1,147 @@
+# REST API Conventions
+
+## Contents
+- URL naming rules
+- HTTP methods mapping
+- Standard response shapes
+- Pagination patterns
+- Versioning strategies
+- HATEOAS (when to use it)
+
+## URL Naming Rules
+
+- Use **plural nouns** for resources: `/users`, `/orders`, `/products`
+- Use **kebab-case** for multi-word resources: `/order-items`, `/payment-methods`
+- Use **path parameters** for identity: `/users/:id`
+- Use **query parameters** for filtering: `/users?role=admin`
+- Use **verbs only for actions** that aren't CRUD: `/orders/:id/cancel`, `/reports/generate`
+- **Max 2 levels** of nesting: `/users/:id/orders` is fine, `/users/:id/orders/:oid/items/:iid/comments` is too deep — flatten it
+
+## HTTP Methods Mapping
+
+| Method | Meaning | Idempotent | Safe | Request Body |
+|--------|---------|------------|------|-------------|
+| GET | Read resource(s) | Yes | Yes | No |
+| POST | Create resource or trigger action | No | No | Yes |
+| PUT | Full replace of resource | Yes | No | Yes |
+| PATCH | Partial update of resource | Yes | No | Yes (partial) |
+| DELETE | Remove resource | Yes | No | No (usually) |
+
+**PUT vs PATCH**: PUT replaces the entire resource (client sends all fields). PATCH updates only the fields provided. For most APIs, PATCH is more practical and less error-prone. Use PUT only when the client genuinely manages the full state.
+
+## Standard Response Shapes
+
+### Single resource
+```json
+{
+  "data": {
+    "id": "usr_abc123",
+    "type": "user",
+    "name": "Jane Smith",
+    "email": "jane@example.com",
+    "created_at": "2025-03-05T14:30:00Z"
+  }
+}
+```
+
+### Collection
+```json
+{
+  "data": [
+    { "id": "usr_abc123", "name": "Jane Smith" },
+    { "id": "usr_def456", "name": "Bob Jones" }
+  ],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTAwfQ",
+    "has_more": true,
+    "total_count": 342
+  }
+}
+```
+
+### Created resource (201)
+```json
+{
+  "data": {
+    "id": "usr_ghi789",
+    "name": "New User",
+    "created_at": "2025-03-05T15:00:00Z"
+  }
+}
+```
+
+With `Location` header: `Location: /api/v1/users/usr_ghi789`
+
+### Deleted (204)
+No body. Status 204 No Content.
+
+### Error
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User with id 'usr_xyz' not found"
+  }
+}
+```
+
+## Pagination Patterns
+
+### Cursor-based (recommended for most cases)
+
+Client sends: `?cursor=abc&limit=20`
+Server returns: `{ pagination: { next_cursor: "def", has_more: true } }`
+
+Advantages: Stable under inserts/deletes, efficient with indexes.
+Disadvantage: Can't jump to page N directly.
+
+Cursor is usually a base64-encoded identifier (e.g., `btoa(JSON.stringify({id: lastId}))`). Treat it as opaque — clients should never construct cursors.
+
+### Offset-based (for simple cases)
+
+Client sends: `?page=3&per_page=20`
+Server returns: `{ pagination: { page: 3, per_page: 20, total_count: 342, total_pages: 18 } }`
+
+Advantages: Can jump to any page, easy to implement.
+Disadvantage: Unstable when data changes between pages, slow for large offsets.
+
+Use offset only when the dataset is small/stable and users need random page access.
+
+## Versioning Strategies
+
+| Strategy | Example | When to Use |
+|----------|---------|-------------|
+| URL path | `/api/v1/users` | Default. Clear, cacheable, easy to route. |
+| Header | `Accept: application/vnd.api+json;version=2` | When URL path isn't desirable (rare). |
+| Query param | `/api/users?version=1` | Avoid. Caching and routing are harder. |
+
+Recommended: URL path versioning (`/api/v1/`). Only create v2 when breaking changes are necessary. Additive changes (new fields, new endpoints) don't require a new version.
+
+**Breaking changes** that require a new version:
+- Removing or renaming a field
+- Changing a field's type
+- Changing the meaning of a status code
+- Removing an endpoint
+
+**Non-breaking changes** (safe within same version):
+- Adding a new field to a response
+- Adding a new endpoint
+- Adding a new query parameter
+- Adding a new optional field to a request body
+
+## HATEOAS
+
+Hypermedia (links in responses) is useful for discoverability in public APIs:
+
+```json
+{
+  "data": { "id": "ord_123", "status": "pending" },
+  "links": {
+    "self": "/api/v1/orders/ord_123",
+    "cancel": "/api/v1/orders/ord_123/cancel",
+    "items": "/api/v1/orders/ord_123/items"
+  }
+}
+```
+
+For internal APIs: skip it — your clients already know the URL structure. For public APIs: consider it — it makes the API more self-documenting.