Polaris
luisgui1757/polaris
Regras de engenharia auto-injetadas para todos os assistentes de IA
Ver no GitHubAgent que injeta automaticamente um conjunto unificado de regras de engenharia em ferramentas de IA (Claude Code, Copilot, Codex e outras). As regras carregam-se automaticamente no startup de cada tool sem necessidade de configuração manual, garantindo coerência nos padrões de codificação em todo o time.
Instalação
npx convez-ai luisgui1757/polaris1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Padronizar comportamento de assistentes IA em repositórios de team
- Aplicar regras de codificação sem reconfiguração em cada ferramenta
- Sincronizar contrato de desenvolvimento entre Claude Code, Copilot e Codex
Veredito

Polaris resolve um problema real: a fragmentação de regras entre múltiplas ferramentas IA. Abordagem elegante (explorar auto-load nativo de cada tool) e pragmática, embora exija disciplina de team para manter as regras atualizadas e aplicadas globalmente.
README
A tradução para o português deste README ainda está na fila.
Polaris
One set of engineering rules that every AI coding assistant follows automatically, in every repo.
Polaris is a small, language-agnostic rulebook for AI coding tools (Claude Code, Codex, GitHub Copilot, opencode, pi). You install it once and the rules load themselves at startup — no slash command, no "please read the docs," no copy-paste.
The idea in one picture
core/ (the rules) ──► tools/install ──► AGENTS.md / CLAUDE.md / copilot-instructions.md
(the files your AI tool already reads on startup)
Your AI tool already auto-reads a special file when it starts. tools/install
writes the rules into that file. That's the whole trick.
Get it
git clone https://github.com/luisgui1757/polaris.git
cd polaris
Run everything below from that checkout. (Prefer to vendor a pinned copy instead
of installing? See consumers.md.)
Use it
Run these from your Polaris checkout — the commands use the repo-relative
tools/install(ormake install). On Windows, use the PowerShell port, which behaves identically and renders byte-for-byte the same block:pwsh tools/install.ps1 -Target C:\path\to\repo(-Global,-Check,-Remove,-DryRunmirror the bash flags).
1. Add the rules to a repo (and share with your team)
tools/install --target /path/to/your/repo
This writes AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md into
that repo. Commit them. Now anyone who clones it and opens any AI tool gets
the rules — automatically.
2. Add the rules to everything on your machine (just you)
tools/install --global
Writes the rules into your home config once. Now every repo you open — even ones that never heard of Polaris — carries the rules. (Per-machine; not shared.)
3. Change the rules
Edit a file in core/, then re-run tools/install (or --global).
4. Check, verify, or remove
tools/install --check # are the blocks up to date? (drift check; used in CI)
make status # where are the rules installed?
tools/install --remove # uninstall — keeps any text you wrote around the block
To confirm a tool actually loaded the rules, ask it in chat: "What does your loaded contract say under Modes?" If it can answer, the block is in context.
What the AI actually sees
The rules are short and generic — correctness, simplicity, surgical changes,
testing discipline, how modes control edit authority, and memory hygiene. They
live in core/ and get inlined into the entrypoint your tool auto-loads:
| Tool | File it auto-reads (per repo) | …and globally |
|---|---|---|
| Claude Code | CLAUDE.md | ~/.claude/CLAUDE.md |
| Codex | AGENTS.md | ~/.codex/AGENTS.md |
| GitHub Copilot | .github/copilot-instructions.md | (set in VS Code / github.com — manual) |
| opencode † | AGENTS.md | ~/.config/opencode/AGENTS.md |
| pi | AGENTS.md | ~/.pi/agent/AGENTS.md |
† opencode auto-load is documented but not yet verified on a live install —
see docs/tool-ingestion.md. The other four are confirmed.
A repo can add its own rules around the Polaris block — re-running install only touches the block, never your text.
Privacy
Polaris is meant to be shareable, so it must never leak your private projects.
make check scans the whole repo and fails if a private term or home path
slips in, reporting the location without ever printing the term. The shipped
files only ever contain generic patterns (home paths); your own private project
names live in tools/forbidden-terms.local — gitignored, never committed, and
wired in via MANIFEST.json's local_denylist key. Create it (one term per
line) to scan for your terms too. Full guarantee and limits:
docs/THREAT_MODEL.md.
Repository layout
| Path | What's there |
|---|---|
MANIFEST.json | the machine-readable contract: core read-order, term policy, byte budget — start here |
core/ | the rules themselves (read in the order MANIFEST.json → required_core_read_order) |
tools/ | installer (install, install.ps1) + checks (check, ci, lint, render, status, verify-vendor) |
scripts/ | one-shot repo safeguards (branch protection) |
docs/ | threat model, per-tool ingestion notes, release process |
templates/ | overlay + adapter templates for consumers |
schemas/ | JSON Schema for MANIFEST.json |
tests/ | the bats regression suite |
AGENTS.md, CLAUDE.md, .github/copilot-instructions.md | generated rule blocks (this repo dogfooding its own installer) — don't hand-edit |
Working on the rules? Edit core/, run tools/install, commit the
regenerated adapters. Just reading? MANIFEST.json + the files it lists are
the whole rulebook.
Develop
make ci # local gate: privacy scan + render + drift + lint + shellcheck
make test # bats tooling suite (incl. the bash/pwsh byte-identity parity)
make install-hooks # install a git pre-push hook that runs make ci for you
make safeguards # apply branch protection + merge rules to the GitHub repo
make help # list everything
CI runs the SAME make ci on GitHub, plus more that the local gate does not: it
sets POLARIS_STRICT=1 (a missing linter/bats/pwsh fails instead of skipping),
runs make test on Linux + macOS, and runs the PowerShell installer on a native
Windows (amd64) job. So local make ci is the fast pre-push check, not the
whole required gate (.github/workflows/ci.yml); main is protected by the
rulesets in .github/rulesets/ (squash-only, required ci check, linear history).
ROADMAP.md tracks remaining work and is deleted once the repo matures.
License
MIT — see LICENSE.