convez.ai
AgenteDevOps & InfraestruturaIntermediário
luisgui1757

Polaris

luisgui1757/polaris

Regras de engenharia auto-injetadas para todos os assistentes de IA

Ver no GitHub
BomPluginScore · de 0 a 100

Agent 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/polaris

1 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

Estrelas
0
Forks
0
Acompanhando
1
Saúde
85%
Último commit
há 2 dias
Versão
v0.4.0
Issues abertas
3
Contribuidores
1

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 (or make 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, -DryRun mirror 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:

ToolFile it auto-reads (per repo)…and globally
Claude CodeCLAUDE.md~/.claude/CLAUDE.md
CodexAGENTS.md~/.codex/AGENTS.md
GitHub Copilot.github/copilot-instructions.md(set in VS Code / github.com — manual)
opencode †AGENTS.md~/.config/opencode/AGENTS.md
piAGENTS.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

PathWhat's there
MANIFEST.jsonthe 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.mdgenerated 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.

Ver o original no GitHub

Bom para

Relacionados