# gspot

> gspot is a command-line tool that lints AI-generated code and installs rules for AI coding agents.

## Steps for coding agents

Set up gspot in the repository of the user. Run each command at the root of the repository. gspot needs Git and
Node.js 24.15 or newer.

1. Add gspot, pinned to one version, with the package manager of the repository:
   - npm: `npm i -D -E @gspothq/cli`
   - pnpm: `pnpm add -D -E @gspothq/cli`
   - Yarn: `yarn add -D -E @gspothq/cli`
   - Bun: `bun add -d -E @gspothq/cli`
   - No `package.json`: `mise use --pin node@24 --tool-option allow_low_downloads=true npm:@gspothq/cli`

   Start the next commands with `npx gspot`, `pnpm exec gspot`, `yarn exec gspot`, `bunx gspot`, or
   `mise exec -- gspot`.
2. Run `gspot init --dry-run`. Show the user the plan: the configurations, the scopes, the tool files that gspot
   replaces, the Git hooks, and the CI workflow.
3. Ask the user two questions, and wait for the answers:
   - Is the plan right? After init, `gspot add <configuration>` and `gspot remove <configuration>` change it.
   - Which level? `recommended`, the default, finds bugs, security and accessibility problems, type errors, and
     formatting. `all` also checks naming, wording, structure, doc comments, duplication, and complexity, and it
     installs a few more tools. Suggest `recommended` for an existing codebase, and `all` for a new repository or
     one that agents write.
4. Run `gspot init --yes`. For level `all`, run `gspot set level all` next.
5. Run `gspot install`. It installs the pinned tools and turns on the Git hooks. If it names a program that it
   cannot install, tell the user. `gspot doctor` lists what is missing.
6. Run `gspot check`, and show the user its last line. Fix the findings in the files that you changed. Ask the user
   before you fix findings in other files.
7. Tell the user what gspot wrote, the level, which checks run, and which findings are left.

## Rules for daily work

- Read `AGENTS.md` and the rules it lists under `.gspot/configurations/` before you write code.
- Stages: `commit` checks run on the staged files before each commit, `push` checks before each push, `message`
  checks on the commit message, and `manual` checks only with `gspot check --only <check>`. `gspot check` alone
  runs the commit and push checks.
- Exit codes: `0` every check that ran passed, `1` findings remain, `2` a check could not run. After `2`, run
  `gspot install`, then `gspot doctor`.
- `gspot explain <check, lint rule, setting, or file>` explains it and names the commands that change it.
  `gspot check --fix` runs the formatters and other fixers. Each check has a page at
  https://generativespotting.com/reference/checks/<check>/.
- Fix the code first. Ask the user before you ignore a finding:
  `gspot ignore <check> --reason "<why>"`, with `--rule <rule>` and `--paths "<glob>"` to narrow it.
  A suppression comment needs a reason, such as
  `// eslint-disable-next-line no-console -- the command prints its result`.
- Never suppress a size or complexity limit. Split the code, or ask the user to raise the limit with
  `gspot set limits.<name> <value> --reason "<why>"`.
- Change settings only with `gspot add`, `remove`, `set`, `unset`, `ignore`, and `unignore`. Do not edit files
  under `.gspot/` or other generated files. After you edit `gspot.toml` by hand, run `gspot apply`.
- In a monorepo, each `[[scope]]` record in `gspot.toml` holds the settings of one folder. Add `--scope <path>` to
  `add`, `remove`, `set`, or `unset` to change one scope.
- Commit with the hooks on. Never use `--no-verify`.


## Documentation Sets

- [Abridged documentation](https://generativespotting.com/llms-small.txt): a compact version of the documentation for gspot, with non-essential content removed
- [Complete documentation](https://generativespotting.com/llms-full.txt): the full documentation for gspot
- [Reference](https://generativespotting.com/_llms-txt/reference.txt): every command, gspot.toml setting, configuration, check, and ESLint plugin rule

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Commands](https://generativespotting.com/reference/commands/): every command, its options, and exit codes
- [Settings](https://generativespotting.com/reference/gspot-toml/): every key of gspot.toml, its accepted values, and its default
- [JSON output](https://generativespotting.com/reference/json-output/): the fields of gspot check --json
- [Markdown pages](https://generativespotting.com/start/overview/index.md): add index.md to the address of any page for its Markdown copy
- [Agent Skill](https://generativespotting.com/.well-known/agent-skills/index.json): the steps above as an Agent Skill