poly-orchestrator

poly as the Orchestrator

Treat poly as the single lint and format gate for the repository. Do not invoke ruff, oxlint, taplo, rumdl, or the rest directly — poly compiles them in as backends, and covers everything else via the tree-sitter generic tier, the quality metric tier, and its built-in ast-grep rule pack, behind one binary, one config, and one report.

Adopt it

• One poly.toml. Configure every language and rule in a single per-repo file (poly.local.toml for local overrides, extends to share a base). Layering is tool default → poly's opinionated overrides → your poly.toml. In a monorepo a nested poly.toml deep-merges on top of its ancestors for the files beneath it.
• poly migrate — absorb existing tool configs into poly.toml instead of hand-writing it. It imports ruff, typos, taplo, and markdownlint configs, and turns a lefthook or pre-commit config into [hooks], [hooks.builtin] and [tools] entries; there is no eslint or prettier importer (an existing .oxlintrc.json / .oxfmtrc.json is read directly, so it needs none). The default is a dry-run report — pass --write to apply (--allow-dirty on a dirty tree), --recurse for a monorepo, --verify to re-run poly afterwards, and --strip-superseded to also remove pyproject.toml sections for tools ruff replaces. It deletes a source only when nothing in it was lost. --to-v2 rewrites an existing v1 poly.toml ([lint.<lang>.<tool>], [rules], per-file-ignores, …) into the v2 schema ([engines.<id>], [workspace] run, per_file_ignores), keeping comments.
• poly hooks install — wire the git-hook shims so poly runs the configured stages on every commit, replacing a .pre-commit-config.yaml or lefthook setup. It installs the hook types your poly.toml configures; --hook-type picks specific ones. A foreign hook already there is kept as <hook>.legacy and run before poly; a lefthook hook is kept but not run (--replace-lefthook discards it), and --overwrite discards any preserved hook. poly hooks uninstall restores what was there before; poly hooks run [stage] runs a stage by hand (--all-files for the whole tree, -v to show passing jobs' output).
• External tools — enable any catalog tool with [tools.<name>] enabled = true (golangci-lint, actionlint, hadolint, helm, tflint, buf, …). Pin version and set install = "auto" to have poly download a checksum-verified release when it is missing; by default it never downloads anything.
• poly config show prints the effective merged config; poly lock [--upgrade] [--check] pins symbolic remote extends refs and Git hook sources into poly.lock; poly config schema prints the JSON Schema for poly.toml. An unknown key in an engine table is an unknown-config-key warning that suggests the nearest valid key (--verbose lists every key the table reads).
• Components. Only the Linux musl release binary is bundled (every engine linked in). Every other release binary is a core build that downloads engines as signed components on first use (poly rules is unavailable there): poly components list|status|sync|install, and --offline / POLY_OFFLINE=1 forbids downloads. [components] in poly.toml sets install and on_missing; [engines.typos] enabled = true opts into spell-checking.
• poly doctor reports which poly is running, every poly on PATH, and the config in effect — the first thing to run when two machines disagree.