sworld

The post-PR CI gate loop — a strict sequential state machine that drives an open PR to settled: merge status → conflicts → unresolved review threads → CI checks, fixing/pushing/waiting/restarting until every gate is green, then reporting ready (never auto-merging). Use whenever the user says "do the loop", "run the loop", "the CI loop", "check the PR", or invokes /ci-loop. On merge it runs `cleanup` for teardown. It does NOT do the pre-PR self-review (that's `parallel-workflow`'s gate) and never touches issue status (that's the tracker's — see `task-tracker`).

Enforces the parallel subtask workflow using tracker issues, git worktrees, and PRs. Auto-triggers when working with git, branches, worktrees, PRs, tracker issues/tasks, codegen, or CI.

The single source of truth for WHICH task tracker we use and HOW to talk to it. Load this whenever you need to create, read, update, relate, or comment on a task/issue/project, or whenever another skill says "the task tracker", "the tracker issue", "the issue's state", or points at `task-tracker`. It owns the tool (Linear, via the `linear` CLI — never the Linear MCP), auth, the SWorld team and `SWO` key, the project-is-an-app model, the Backlog→Todo→In Progress→In Review→Done lifecycle, and the exact issue/relation/document command forms. Reach for it any time a workflow step runs a `linear …` command or names a tracker concept, even when the triggering skill refers to "the issue" only generically.

Known traps in the sworld local dev/build tooling — stale package dists, turbo cache masking bundle changes, Node version pinning, pnpm's dependency cooldown, CodeGraph setup, and bundle-size vs error-tracking tradeoffs. Auto-triggers when a dev server fails to resolve a core/ui subpath, a build "works" but the change isn't visible, adding/upgrading a dependency, or trimming bundle size for perf.

The audit pass on an already-scoped ticket and its sub-issue breakdown, run BEFORE any code. Use it as the first move whenever picking up, starting, resuming, or "analysing" a non-trivial tracker issue — especially a large-feature parent with sub-issues — to catch missing requirements and a breakdown that has drifted out of sync before you build against it. Reach for it the moment you're about to start an issue, when a plan "looks done" but nobody has re-checked it, or when the user says "analyse this issue / take a look at this breakdown / is this plan right". This is the backward/audit direction on a *spec* — distinct from `product-planning`/`grill-me` (forward, idea → breakdown) and `self-review` (analysing *code*). Not needed for a trivial, single-issue bug or a one-line change with no breakdown to audit.

Enforces frontend architecture patterns including server state management, data transformation, and GraphQL conventions. Auto-triggers when working with API calls, data fetching, react-query, GraphQL, or data transformations.

Enforces general code conventions and best practices. Auto-triggers when writing or editing any TypeScript/TSX files.

Work out the true dependency graph of a change from the code — which pieces are isolated, which are genuinely blocked by another, and which block others. Auto-triggers when breaking a feature into sub-tasks, deciding whether a `blockedBy` edge is real, sequencing work into waves, asking "can these run in parallel?", or judging what breaks if a signature/schema/contract changes. Owns the investigation and the real-vs-fake test; `writing-task-specs` renders the result into a spec and `task-tracker` records the edge.

Owner's cross-app product/UX principles — generous spacing, input-vs-view app affordances, and the Listen app's design north star. Auto-triggers when designing or reviewing layout, spacing, navigation affordances (FAB/drawer/dashboard), or any UI work in apps/listen.

Enforces Playwright E2E conventions — canonical locators, semantic selectors, cross-page input→navigate→consume flow, exact assertions, dynamic mocks — and how to debug a runtime-only browser error by driving a headless Playwright probe. Auto-triggers when writing or editing any *.spec.ts file under e2e/ or its helpers/mocks, or when reaching for Playwright to read the browser console for a bug with no build/lint signal.

The load-bearing rule for WHERE frontend code lives — packages/ui is the single source of truth for all UI, and the universal-vs-site folder split governs both ui and core. Auto-triggers when creating or placing a component, deciding which package or folder new frontend code belongs in, adding app-local styles, importing from @mui/material inside an app, or reviewing where code landed.

Cross-cutting Hasura/database-layer principles — the single-gateway rule (nothing talks to Postgres except Hasura), when a write needs a database-level concurrency-safe pattern versus a plain read-then-write, and the three layers that validate data. Auto-triggers when designing a new mutation/Action, deciding how a write should be structured, or reasoning about concurrent writes or data validation. Complements `architecture` (frontend query/transformer conventions) and `backend-architecture` (the Cloud Run/Cloud Task service pipeline) — this skill owns only the database-layer decisions neither of those covers.

How to break work into the smallest possible, independently reviewable and revertible PRs, and how to size and sequence them. Use when planning or scoping a feature, deciding how to split a change, staring at a diff that's growing large, or asking "how should I break this down?" Fires whenever a change is heading past quick-review size, and can be invoked on demand to plan a decomposition.

This skill should be used whenever the user asks to "create a PR", "open a pull request", "raise a PR", "push and PR", "write a PR description", or "draft a PR". Also use when updating an existing PR's title or description. Enforces the conventional commit title format and the lean Summary + Test plan body.

The single place all code review happens in this repo. Use as the mandatory pre-PR gate in the parallel workflow — reviewing the LOCAL working diff vs origin/main before the PR is created (commits are pushed freely as backup; the PR is what's gated) — and whenever the user asks to "review this", "look at this branch", "what do you think of this", "give me feedback on this", "is this ready to merge", or any variant where current work is being evaluated. The target is ALWAYS the local diff, never a remote PR. Owns both halves of a review — the mechanical bug hunt and the judgment pass — scaled to risk across four depth bands, ending in a clear merge recommendation. The harshest band covers a "thermo-nuclear review", "deep code quality audit", or any request for an especially strict maintainability/abstraction-quality pass.

Run the harshest band of code review — an extremely strict maintainability pass focused on abstraction quality, file-size growth, and spaghetti-condition creep. Use when the user asks for a "thermo-nuclear review", "thermonuclear code review", "deep code quality audit", or an especially harsh / strict maintainability review.

This skill should be used whenever the user asks to "create a ticket", "write a task", "scope this out", "break this down", "raise a bug", "create a parent", "plan this feature", or any variant where work is being captured. Also use when the user describes a problem, bug, or feature idea and the natural next step is a written spec. Enforces the task-spec shapes (bug, small feature, large feature scoping, product/user story) and the conventions around parent/sub-task breakdown as tracker issues and projects (see `task-tracker` for the tracker itself and its commands).

Create new skills and iteratively improve existing ones. Use when users want to create a skill from scratch, edit or refine an existing skill, test a skill by running it against realistic prompts, or sharpen a skill's description so it triggers reliably.

The single owner of the mechanical git cleanup after a PR merges — remove its throwaway worktree, delete its local branch, and fast-forward local `main` — plus the standalone "keep local `main` fresh" refresh. Use whenever a PR has merged and its worktree/branch need tearing down, or the user says "cleanup", "clean up the worktree", "refresh main", "update main", "pull main", or invokes /cleanup. Other skills (`ci-loop`, `wait-for-pr-merge`) point here for these steps and carry none of the commands. It never touches issue status (that's the tracker's — see `task-tracker`) and never fixes CI, conflicts, or review comments (that's the loop — see `ci-loop`).

Poll one or more PRs until each merges (or closes), running the `cleanup` skill on each PR the moment it merges (issue status is the tracker's — see `task-tracker`). Use whenever the user says "wait for PR X to merge", "wait for PRs X and Y to merge", "watch these PRs until they merge", "let me know when PR X lands", "poll PR X", or invokes /wait-for-pr-merge. This is post-READY watching only — it does NOT fix CI, conflicts, or review comments (that is "the loop"; see `ci-loop`).

Deep, first-principles product planning — the rigorous thinking pass that happens *before* tickets and code. Use whenever planning or scoping a feature, thinking through a product idea, or deciding how to approach something: "let's plan this", "I want to build/add X", "how should we approach Y", "scope this out", or when bringing a rough idea or a parent task to work through. Reach for it proactively the moment a new feature, a change to how something works, or a domain concept is on the table — especially when the real risk is whether the *concept* is understood, not how to code it. It interrogates whether the thinking is genuinely clear, captures the concept as documentation up-front, weighs architecture, and shapes a high-level parent — conducting grill-me, writing-task-specs and micro-prs as it goes. Not for trivial, well-understood changes that should go straight to code — though its critical-thinking instinct still applies even then.

Interview the user relentlessly about every aspect of a plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one by one. Use when the user wants their plan stress-tested, asks to be "grilled" on a design, wants help thinking through a decision tree, or wants every assumption and edge case surfaced before any code is written.

Enforces MUI component and styling conventions. Auto-triggers when writing or editing any TSX/TS files that use MUI components, styling, or theming.

The jargon-free "plain words" writing rule and the block templates that apply it — the mandatory opening summary a reader with zero context can understand in ten seconds, with no code, file paths, symbol names, or unexplained acronyms. Referenced by `writing-task-specs` (ticket "In plain words" / "Why this matters" blocks) and `pr-descriptions` (PR summary and user-facing test plan) rather than duplicated in each. Auto-triggers whenever drafting any of those, or any other doc that needs to read cleanly for a non-technical reader.

The sworld backend architecture — four services (gateway, io, compute, hasura), the Hasura Event → Cloud Task → handler pipeline, task lifecycle, notification flow, and when to use Cloud Tasks vs direct actions. Auto-triggers when working in sworld-backend, planning backend features, touching Hasura Actions/Events, creating Cloud Task handlers, or designing any server-side video/audio processing flow.

How to perform sworld operational tasks from the sworld-backend repo — GCS asset layout, operator CLIs, direct prod DB access, and the recurring "create audios" ingestion task. Auto-triggers when uploading media, ingesting mp3/video files, touching prod data directly, or working in sworld-backend/src/cli.

Stack-aware security & vulnerability reviewer for this codebase — tuned to our actual stack: Auth0 (authentication), Hasura (authorisation), Hono backend (separate sworld-backend repo), Vite/React SPA (frontend), and Postgres. Use whenever asked to review security, audit for vulnerabilities, check for security weaknesses or misconfigurations, threat-model a change, or assess the security posture of the app — and reach for it proactively when touching anything on a trust boundary: authentication, Auth0/JWT claims, Hasura permissions or metadata, role assignment, webhook/Action/Event handlers, the admin secret, secrets/env vars (especially VITE_-prefixed), CORS, or deploy config. This is the stack-specific complement to the generic built-in `security-review` command: that one reviews an arbitrary diff with generic rules; this one knows how our five trust boundaries are wired and what traps live in each.

How errors from GraphQL mutations flow through three layers (global MutationCache, hook-level onError, call-site onError) and which layer should display them to the user. Auto-triggers when writing or editing mutation hooks (packages/core mutation-hooks), queryClient.ts, or any onError handler — and whenever deciding where to surface a mutation error (toast vs inline), handling Hasura or Hono Action errors, or using extractGraphQLErrorMessage.

Enforces the mutation data flow pattern — how data moves between server, client state, UI, and back to server via payload builders and generic mutation hooks. Auto-triggers when working with mutations, payload builders, or form data transformations.

Enforces React conventions and best practices. Auto-triggers when writing or editing any TSX/TS files with React components, hooks, or logic.

Best-practice process for keeping JavaScript/Node supply-chain attacks low-impact when working on pnpm, npm, or yarn projects. Use this skill whenever installing, adding, updating, or pinning dependencies; running pnpm/npm/yarn install; resyncing or regenerating a lockfile; setting up a new Astro or Node project; auditing whether a project is safe from a compromised package; editing package.json or a lockfile; or whenever the user mentions supply-chain attacks, compromised npm packages, malicious postinstall scripts, pinning versions, or lockfile hygiene — even if they don't explicitly ask for a "safe install". Default to consulting this before running any install command so the safe procedure is followed rather than a blind re-resolve.