version: "1.0.0" name: code-style description: 'TRIGGER when: writing Python, TypeScript, Bash, or Swift implementation code. Covers repo-local conventions, task-shaped code quality, comment policy, proof rhythm, naming, Python narrative style, TypeScript/Bun boundaries, Bash operational safety, Swift platform conventions, and anti-slop extraction rules. DO NOT TRIGGER when: reading code only, editing config files, or writing prose/docs.' allowed-tools: Read, Edit, Write, Grep, Glob, Bash

Code Style

Goal: finish correct, inspectable changes fast. A style rule is useful only if it cuts bug risk, search time, review time, or proof cost.

Decision Order

1. Preserve the style of the file and nearby code, except unsafe patterns (any, swallowed errors, debug logs, unhandled promises, detached subprocesses) must not spread.
2. Obey the repo formatter, linter, type checker, and test patterns.
3. Match the task shape: behavior code, config glue, setup script, library API, CLI, UI, or one-off tool.
4. Apply the preferences below when the repo does not already decide.

Universal Rules

• Keep scope tight. Do not modify unrelated code, rename symbols, or reflow files for taste.
• Prefer boring control flow, explicit errors, and narrow side effects.
• Name things after the domain action or state they own. Avoid manager, handler, processor, utils, and helpers unless the existing repo uses them for a real boundary.
• Comments: do not add comments by default. Add only approved exceptions: novel/galaxy-brain algorithms, API docs, and crypto/security-sensitive code. Preserve useful existing operational comments; do not add routine shell narration.
• Types belong at public/module boundaries and risky IO boundaries. Do not annotate every harmless local just to look typed.
• Inline simple one-use logic. Extract only when it removes repeated risk, names a real domain step, or makes a long narrative easier to review.
• No wrapper classes/functions that only delegate.
• No clever metaprogramming, reflection, dynamic import tricks, or generated code unless they remove real complexity.

Proof Rhythm

• Bugfixes: reproduce first; add or extend a regression test whenever the existing runner or a targeted local test can cover the bug. Use manual reproduction only when a regression test would require a new external service, dependency, emulator, or unavailable runtime; state why, then prove fixed with the same reproduction.
• Behavior changes: test-first when the existing runner or a targeted local test can cover the behavior; adding a local test file/helper is not new infrastructure. If a test would require a new external service, dependency, emulator, or unavailable runtime, state why and provide a runnable proof command with expected output/state.
• Config, setup, and shell changes: define the proof command before editing; the command must assert expected output/state, not just syntax, and rerun/convergence for stateful changes. Syntax-only proof is enough only for formatting-only edits in whitespace-nonsemantic formats.
• Refactors and mechanical edits: prove behavior preservation with the narrowest existing test, typecheck, linter, formatter, parser/syntax check, or diff inspection that matches the touched surface. For whitespace-semantic formats, include a parser/syntax check or targeted test when available; state when the change is intentionally behavior-preserving.

Python

• For new Python classes, use CapWords (PascalCase); defer to existing project naming when it differs.
• Use dataclasses when the object has real state and default construction noise would distract from the task.
• Use field(default_factory=...) for mutable defaults; use __post_init__ only for derived or runtime state.
• Methods should tell one coherent story. Six to twenty-five lines is a signal, not a law.
• Use properties only for cheap, lazy, idempotent values. Do not hide network, process, or file mutations behind properties.
• Prefer Path, context managers, and structured parsers over path string gymnastics and ad hoc parsing.
• Preserve exception context; wrap errors only when adding actionable domain context.
• Use _private methods only for real internal boundaries, not to hide helper hell.
• Avoid helper hell: texts(), encode(), split(), chunks(), and similar one-liners should usually stay inline.

TypeScript

• For new TypeScript work in ~/box, default to Bun for scripts, tests, shell calls, and runtime APIs unless the project declares another package manager. Outside ~/box, follow the project's declared package manager; if none is declared, Bun is the fallback. If the Bun skill is loaded, use it for command syntax and API details without overriding this package-manager boundary.
• Prefer plain functions and typed objects before classes.
• Use unknown at IO boundaries and narrow immediately. Avoid any; if a legacy signature forces it, contain it in the smallest adapter and do not propagate it.
• Use discriminated unions for state machines and mode switches.
• Keep async lifecycles explicit. No hidden fire-and-forget work without cancellation, logging, or ownership.
• Separate domain logic from transport/UI glue so it can be tested without a browser or network.
• For CLIs and scripts, parse args once, validate early, and keep the mutation step visibly bounded.

Bash

• Scripts should start with set -euo pipefail unless sourced by design.
• Quote variables by default. Use arrays for command construction.
• Make external mutations idempotent or guarded.
• Use case for platform branching and command dispatch.
• Prefer structured tools (jq, yq, Bun/Node, Python via uv run) over regex parsing for JSON/YAML/TOML.
• Use temp files/directories with cleanup when partial writes could corrupt state.
• Keep setup flows linear: detect, explain, mutate, verify.

Swift

• Follow Apple/platform conventions over personal naming preferences.
• Use UpperCamelCase for types and lowerCamelCase for functions/properties unless existing code differs.
• Prefer small value types for data and explicit side-effect boundaries for services.
• Use protocols only when multiple implementations exist or tests need a real seam.
• Surface actionable errors at UI/CLI boundaries; keep internal failures typed or clearly contextual.

Extraction Rules

• Extract when logic repeats in multiple places, carries security/state risk, has a domain name users would recognize, or makes tests simpler.
• Keep inline when it is used once, is shorter than its name, or splitting would force the reader to jump around.
• If a function is long but reads as one operational story, keep it intact and add paragraph-shaped local variables instead of micro-helpers.

Anti-Slop

• No placeholder comments instead of implementation.
• No speculative abstractions for hypothetical future variants.
• No drive-by style churn.
• No tests that assert implementation trivia while missing user-visible behavior.
• No swallowing errors with except Exception, .catch(() => {}), || true, or try? unless the caller has a concrete fallback.