DinoStack / rules

---
description: "Code quality gates, tool discipline, package management, and browser verification for software engineering tasks."
globs: ["*.ts", "*.tsx", "*.js", "*.jsx", "*.py", "*.go", "*.rs", "*.java", "*.rb", "*.swift", "*.kt"]
alwaysApply: false
---

## Documentation Lookups

**When investigating, diagnosing, or reasoning about library, framework, or SDK behavior, look up current documentation using Context7 before forming conclusions.** Training data may be outdated - API signatures, configuration options, default behaviors, and error messages change across versions.

Use Context7 (`resolve-library-id` -> `query-docs`) for:
- Verifying API signatures, method parameters, or return types
- Checking configuration options or default values
- Understanding error messages or behavioral changes across versions
- Any assumption about library behavior that influences a diagnosis or recommendation

Do not rely on training knowledge for library-specific details when Context7 is available. This applies to all agents: investigators, debuggers, architects, and engineers.

## Tool Discipline

**Prefer the dedicated tools for reads, listing, and search when they are available; use Bash as the sanctioned fallback when they are not.** `Read` is always present and is the primary tool for reading file contents - always prefer it over `cat`/`head`/`tail`/`sed`. For listing and searching, prefer `Glob` and `Grep` when the harness exposes them - they avoid permission prompts and give cleaner output:
- Read files: `Read` tool (always available; never `cat`, `head`, `tail`, `sed`).
- List/find files: `Glob` tool when available; otherwise Bash `find` (or `rg --files`).
- Search content: `Grep` tool when available; otherwise Bash `rg` (preferred) or `grep`.

Reserve `Bash` for: builds, installs, git operations, network calls, process management, listing/searching when `Glob`/`Grep` are unavailable, and anything no dedicated tool covers.

`sg` (AST-grep) for structural symbol-level searches is always run via Bash - no dedicated harness tool wraps it. This is independent of the `Glob`/`Grep` availability question above: Bash-based search is sanctioned generally (via `rg`/`grep`/`find`), and `sg` is the specific tool for structural AST queries. Check availability with `which sg 2>/dev/null` before use.

**Optional raw-speed tip:** the `Grep` tool already uses Claude Code's bundled ripgrep (`@vscode/ripgrep`, present since v1.0.84) - no install needed for correctness. For faster raw `rg` in Bash on large trees, install system ripgrep (`brew install ripgrep`) and set `USE_BUILTIN_RIPGREP=0` to swap the bundled binary for the system one. This is a performance-only setup choice; the methodology does not require it.

**Agent-ergonomic tool selection**

When choosing between tool options for the same job, prefer the option that minimizes token cost and latency for agent consumers:

- **Prefer token-efficient output.** Text and tabular tool output is cheaper for models to consume than JSON dumps with identical semantic content. When a tool offers multiple output formats, pick the one that gives the model the signal it needs with the least surrounding structure.
- **Prefer CLI over MCP server when the CLI is cheaper.** An MCP server adds a protocol layer that inflates token cost and latency with no functional gain when a CLI covers the same job. Concrete reference: the GitHub MCP server costs approximately 3x the tokens and 2x the latency of the `gh` CLI for the same GitHub operations. AE uses `gh` for all GitHub operations (see AGENTS.md) - this is the principle in action.
- **Measure before adopting.** Do not assume a new tool or MCP server is cost-neutral. Before integrating either, benchmark its token/latency profile against the alternative.

These rules complement the existing tool hierarchy above (Read/Glob/Grep over Bash). Together they form AE's tool-selection standard: reach for the tool whose output-to-signal ratio is best for the model reading it.

## Module Manifests

**Non-trivial modules should carry a manifest header.** Any source file that exports a public symbol consumed by another module, is over ~50 lines of non-trivial logic, or implements a side-effecting operation (network, disk, database, external service) is encouraged to include a manifest comment or docstring at the top of the file. See `content/rules/module-manifest.md` for required fields, examples, and exemptions. Skeptic reports manifest gaps as **Minor**.

## DRY and Abstraction

**Do not Repeat Yourself. Engineers must actively scan their own output for duplication before declaring work complete.**

- **Repeated logic** — any block that appears more than once with identical or near-identical structure must be extracted into a helper, utility, or shared component.
- **Copy-paste with tweaks** — copying code and changing only names or constants is a strong signal for abstraction, not a valid implementation strategy.
- **Existing utilities first** — before writing new code, grep the codebase for functions that already solve the sub-problem. Prefer calling an existing utility over reimplementing it.
- **Follow established patterns** — if the codebase has a convention for this class of problem (validation schemas, error wrappers, React hooks, data transformers), use it.
- **Intentional exceptions** — if duplication is genuinely appropriate (the two paths are about to diverge significantly, or extraction would obscure meaning), state the reason explicitly in the output.
- **Unnecessary abstraction** - the counterweight to the "Repeated logic" rule above: an abstraction serving only a single call site, or built only for a hypothetical future requirement, is itself a finding, not a virtue. Do not extract a helper, wrapper, or config layer until a second real caller exists or a stated requirement needs it.

**Precedence: exactly one rule governs each state.** (1) One call site, no second call site anywhere (in this diff or the codebase), nothing extracted - no finding. (2) That same single call site with an abstraction extracted anyway - "Unnecessary abstraction" governs, never "Repeated logic" (which requires the block to actually appear more than once). (3) A second occurrence of the block arrives in the same diff, or the pattern already exists elsewhere in the codebase - the block now appears more than once either way, so "Repeated logic" governs and "Unnecessary abstraction" does not apply (a real second occurrence is not a hypothetical future requirement). No state satisfies both rules at once. Note "call site" and "occurrence of the block" are not synonyms: a correctly extracted helper called from two places is two call sites but one occurrence, so it is not state (3) and produces no finding.

The Skeptic review layer enforces both directions: duplication and missed abstractions are **Major** findings that block sign-off unless justified; an unnecessary abstraction is **Minor** by default, **Major** when it adds a public surface (a new exported function, module, or API with only one caller).

## Code Quality Gates

**After writing or modifying code, run the project's lint, typecheck, and test commands.** All must pass with zero errors before work is complete.

- **Greenfield projects:** zero warnings from the start
- **Existing codebases:** do not introduce new warnings; flag pre-existing issues to the user
- Never suppress or disable rules to pass gates - fix the code. Suppression comments (`@ts-ignore`, `noqa`, etc.) require explicit user approval
- **New projects (via `/ds-init-project`):** set up pre-commit hooks (husky + lint-staged for JS/TS, pre-commit framework for Python)
- **Existing projects without tooling:** run whatever checks are available and recommend setup to the user

Read `content/references/code-standards-detail.md` §Per-Language Strict Defaults, §Browser Verification, and §Discovery-Based Check Discipline when implementing or modifying code.

## Package Management

**Dependency versioning rules** - when adding a new dependency, upgrading an existing one, or encountering a bug in an already-installed outdated dependency: read `content/references/code-standards-detail.md` §Package Management for the latest-stable-version default, the no-hardcoded-version rule, the no-monkey-patch rule, and the existing-constraint exception.