README
Norms
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 git@github.com: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 <path> | 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
Contributors
47 commits
See what people are saying
Similar repos
Languages
TypeScript
85.0%
Shell
8.3%
PowerShell
5.3%
JavaScript
1.4%
README
Norms
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 git@github.com: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 <path> | 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
See what people are saying
Similar repos
Contributors
47 commits
Languages
TypeScript
85.0%
Shell
8.3%
PowerShell
5.3%
JavaScript
1.4%