AGENTS.md

1# Migrations Tooling — Agent Guide
2 
3Start with **[README.md](README.md)** — it is the single source of truth for this
4project: gem layout and namespaces, the `disco` CLI, converters, the schema DSL,
5and the install / test / lint workflow.
6 
7This file is reserved for **agent-specific** guidance that does not belong in the
8README (conventions, gotchas, do/don't notes for automated contributors).
9 
10## Gotchas
11 
12- **Samovar reserves `name` on commands.** `Nested#parse` instantiates a
13  sub-command with `name:` (its invocation name), which Samovar stores and exposes
14  as `name`. So don't declare a positional `one :name` on a `disco` command — when
15  the argument is omitted the accessor silently reads back the command's own name
16  (e.g. a `schema add` command would read back `"add"`) instead of `nil`. Name the
17  positional something else (`one :table_name, …`).
18 
19- **Samovar positionals are never required.** Don't use `one :x, required: true` —
20  it raises during parsing, before `call` runs, which breaks the `-h/--help`
21  handling. Leave positionals optional and validate them at the top of `call` with
22  `require_positional!` (see `Migrations::CLI::Command`); it raises a presentable
23  error, so the user gets a clean message instead of a backtrace.
24 
25- **Don't give command groups a `-h/--help` option.** The option hoisting in
26  `Command#parse` moves recognized flags to the front, so a group-level help
27  option steals `--help` from the subcommands — `group sub --help` would run
28  the subcommand instead of printing its help. Leave groups without options;
29  a bare `group --help` surfaces as an unparsable token, which `Bootstrap`
30  turns into usage with exit 0.
31