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

Code Conventions

The style law

These five rules are absolute, and this skill is where they live. Nothing else in the repo restates them — a second copy is how one of them quietly becomes wrong.

ES modules only — no CommonJS require / module.exports.
async/await wherever possible — not raw promise chains.
Arrow functions only — never a function declaration. const method = async () => …
Named exports, at the bottom of the file — no default exports, no inline export const; the export statement is the last thing in the file.
Params go in an interface, so a method's signature stays on one line instead of many.

Biome enforces what it can. The rest you check by eye — these are exactly the rules an AI-generated diff slips past.

Barrel files

AVOID barrel files (index.ts that re-exports) as much as possible.
If an existing barrel file is found, do NOT add more re-exports. Instead, add a // TODO: remove barrel file comment so it can be cleaned up later.
Always import directly from the source file.

Exports

NEVER export something that isn't used elsewhere. If it's reusable, move it to a shared file; if it's only used within the file, drop the export.

Constants

NEVER put constants inside React components or helper functions.
ALWAYS place constants in a dedicated constants folder/file.

Cross-feature imports

AVOID cross-feature imports as much as possible.
If a cross-feature import is unavoidable, add a // TODO: refactor cross-feature import comment so it can be addressed later.

Control flow

PREFER early return over deep nesting or else blocks.
NEVER use complex inline ternaries like a ? (b ? c : d) : e — extract to a function with early returns.

Naming conventions

File names: camelCase preferred (e.g. envConfig.ts, useProjectData.ts). Exception: React component files use PascalCase (e.g. ProjectCard.tsx, SignUpFormUI.tsx)
Component names: PascalCase (e.g. ProjectCard, SignUpForm)
Hook names: always prefixed with use (e.g. useAuth, useProjectData)

Testing

Pure logic MUST have unit tests in the same PR.
ALWAYS use exact assertions (toBe, toEqual, toStrictEqual, and framework equivalents like Playwright's toHaveValue / toHaveAttribute).
NEVER use a fuzzy, range, or substring matcher when the exact value is known — approximation (toBeCloseTo), comparison (toBeGreaterThan, toBeLessThan), and containment (toContain) all hide the value you meant to assert. expect(items).toHaveLength(3) — not toBeGreaterThan(0).
Only use them for genuinely non-deterministic values (timestamps, random IDs) — never as a way to avoid pinning down a value you could know.

Más de este repositorio

mismo repositorio

ci-loop

shinaBR2/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`).

2026-07-213

parallel-workflow

shinaBR2/sworld

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.

2026-07-203

task-tracker

shinaBR2/sworld

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.

2026-07-203

dev-environment-gotchas

shinaBR2/sworld

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.

2026-07-203

analyze

shinaBR2/sworld

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.

2026-07-193

architecture

shinaBR2/sworld

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.

2026-07-193

Code Conventions

The style law

These five rules are absolute, and this skill is where they live. Nothing else in the repo restates them — a second copy is how one of them quietly becomes wrong.

ES modules only — no CommonJS require / module.exports.

async/await wherever possible — not raw promise chains.

Arrow functions only — never a function declaration. const method = async () => …

Named exports, at the bottom of the file — no default exports, no inline export const; the export statement is the last thing in the file.

Params go in an interface, so a method's signature stays on one line instead of many.

Biome enforces what it can. The rest you check by eye — these are exactly the rules an AI-generated diff slips past.

Barrel files

AVOID barrel files (index.ts that re-exports) as much as possible.

If an existing barrel file is found, do NOT add more re-exports. Instead, add a // TODO: remove barrel file comment so it can be cleaned up later.

Always import directly from the source file.

Exports

NEVER export something that isn't used elsewhere. If it's reusable, move it to a shared file; if it's only used within the file, drop the export.

Constants

NEVER put constants inside React components or helper functions.

ALWAYS place constants in a dedicated constants folder/file.

Cross-feature imports

AVOID cross-feature imports as much as possible.

If a cross-feature import is unavoidable, add a // TODO: refactor cross-feature import comment so it can be addressed later.

Control flow

PREFER early return over deep nesting or else blocks.

NEVER use complex inline ternaries like a ? (b ? c : d) : e — extract to a function with early returns.

Naming conventions

File names: camelCase preferred (e.g. envConfig.ts, useProjectData.ts). Exception: React component files use PascalCase (e.g. ProjectCard.tsx, SignUpFormUI.tsx)

Component names: PascalCase (e.g. ProjectCard, SignUpForm)

Hook names: always prefixed with use (e.g. useAuth, useProjectData)

Testing

Pure logic MUST have unit tests in the same PR.

ALWAYS use exact assertions (toBe, toEqual, toStrictEqual, and framework equivalents like Playwright's toHaveValue / toHaveAttribute).

NEVER use a fuzzy, range, or substring matcher when the exact value is known — approximation (toBeCloseTo), comparison (toBeGreaterThan, toBeLessThan), and containment (toContain) all hide the value you meant to assert. expect(items).toHaveLength(3) — not toBeGreaterThan(0).

Only use them for genuinely non-deterministic values (timestamps, random IDs) — never as a way to avoid pinning down a value you could know.