Show HN: Manage coding norms across your AI agents

Notifications You must be signed in to change notification settings Fork 0 Star 1 BranchesTags Open more actions menu Latest commit History 48 Commits 48 Commits Folders and files NameName Last commit message Last commit date .cursor/rules .cursor/rules .github .github .norms .norms docs docs packages packages scripts scripts .gitattributes .gitattributes .gitignore .gitignore .vscode-test.mjs .vscode-test.mjs AGENTS.md AGENTS.md CLAUDE.md CLAUDE.md FEATURE-REQUESTS.md FEATURE-REQUESTS.md README.md README.md ROADMAP.md ROADMAP.md bun.lock bun.lock install.ps1 install.ps1 install.sh install.sh package.json package.json tsconfig.json tsconfig.json Repository files navigation Summary Define your coding rules once, store them in Git, and make every coding agent follow them. Norms stores repo-level instructions as Markdown in .norms/, resolves them, and generates the rule files each coding agent expects. In practice, you’ll usually manage norms through your coding agent. After installing Norms and running norms init in your current repo, just tell your agent to add or update a norm. It will write the norm, sync the generated rule files, and follow the updated instructions from then on. You can also manage norms directly from the CLI with norms propose and norms sync. And because norms are just Markdown, you can always edit them by hand. Canonical norm Each norm has a stable id, optional path scopes, and one clear instruction. For example, .norms/norms/testing/integration.md: --- id: testing.integration applies_to: - "packages/**" --- # Test behavior Cover user-visible behavior with integration tests. What norms can encode Norms can encode any reusable instruction you want agents to follow. Because norms are just Markdown, they can also include images, diagrams, links, code snippets, tables, and other supporting context. For example: “All new API endpoints must include an integration test.” “Use uv for Python dependencies; don’t add requirements.txt.” “Keep React components under 300 lines and move shared state into hooks.” “Every merge request must explain what changed, why, and how it was tested.” “All buttons on this website should glow red like in this picture.” Install On macOS or Linux: curl -fsSL https://raw.githubusercontent.com/gsttm/norms/main/install.sh | sh On Windows, run PowerShell: irm https://raw.githubusercontent.com/gsttm/norms/main/install.ps1 | iex Both installers verify release checksums and optionally install the VS Code extension. Quick development setup git clone [email protected]:gsttm/norms.git cd norms bun install bun test bun run build ./dist/norms.js --help In a development checkout, invoke Norms through ./dist/norms.js. Building does not install the released norms command. Basics Norm Markdown lives in .norms/norms/ and .norms/assets/ stores referenced files. norms sync generates AGENTS.md, CLAUDE.md, .cursor/rules/norms.mdc, and .github/copilot-instructions.md. Edit .norms/, never generated adapters. Command Purpose norms init Initialize Norms, starter meta-norms, and existing agent instructions. norms list List active norms and sources. norms context [path] Return norms applicable to a path. norms explain Explain scope matches and declared conflicts. norms lint [path...] Emit deterministic context for evaluation by your agent. norms status Show sync and Git state. norms propose Create or update a local norm. norms sync Restore pinned imports offline and generate agent adapters. norms sync --update Fetch configured refs and update import pins. norms check Validate config, norms, lockfile, and adapters. norms review Commit, push, and open a GitHub or GitLab review. Add --json for machine-readable output. Current adapters Norms currently outputs only AGENTS.md, CLAUDE.md, .cursor/rules/norms.mdc, and .github/copilot-instructions.md. Documentation Concepts CLI reference Repository format Code structure Development Releasing VS Code extension Team sharing specification Roadmap Resources Readme Activity Stars 1 star Watchers 0 watching Forks 0 forks Report repository