v0.3.0

✨ New Features

Code Rules now has a public package for reading Code Rules libraries

Third-party tools can now read a Code Rules library exactly as the Code Rules tool itself reads it. The new github.com/fabricahq/code-rules/coderules package parses library release tags and their release records, rule files, group metadata, and the canonical group list. (#94)

⬆️ Improvements

• The documentation now answers questions about a single rule's version: where to find a rule's current version, how a rule gets a new version, and how to update one rule in your project. (#92)

Pull Requests

✨ Features

• Add a public coderules package for reading libraries by @josh-padnick in #94

📖 Documentation

• Make a single rule's version easy to find, change, and upgrade in the docs by @josh-padnick in #92
• Skip migration steps until Code Rules is announced, and fix a contributing link by @josh-padnick in #90

🧹 Chores

• Follow public-rules release 1 and turn our conventions into local rules by @josh-padnick in #93

Full Changelog: v0.2.0...v0.3.0

v0.2.0

✨ New Features

Per-rule versions

Each rule in a library now has its own semantic version, starting at 1.0.0. The version describes how the rule's obligation changed:

• major when work that complied before could now fail
• minor when the change adds guidance
• patch when the change clarifies existing guidance

Generated rules show each imported rule's version, so agents and reviewers can cite the exact version they followed. See Version your rules. (#71, #76)

Change notes

Library authors can now record each rule change with code-rules library change. It writes a small note in changes/ with the size of the change and a one-line summary for the projects that update:

code-rules library change practices/testing/verify-retry-limits \
  --bump minor \
  --summary 'Add a Python example of the retry-limit test.'

Each note is its own file, so pull requests that change the same rule never conflict. Use --retire, with --replaced-by when a better rule replaces it, to retire a rule. (#71, #73)

Library releases

Libraries now have releases. A library release publishes a set of rule changes together, as a numbered snapshot of your library at one moment.

When your pending changes are ready to share, run code-rules library release. Each changed rule gets its new version, and projects can review and adopt those versions with code-rules project update. For libraries on GitHub.com, it also creates a GitHub Release page that lists the changes rule by rule with your summaries, so the people who use your library can see what changed before they update. Preview what it will publish first:

code-rules library release --dry-run
code-rules library release

It publishes only from your default branch, when it matches the remote and code-rules library check passes, so a release always contains reviewed changes. If a run stops partway, run it again to finish. See Publish a library release. (#71, #75)

Review and adopt updates with code-rules project update

code-rules project update previews every newer rule version, new rule, and retirement with the author's summaries, then applies exactly what it showed after you confirm. Without a terminal it only previews, so pass --yes to apply in scripts and CI.

team
  major     practices/testing/verify-retry-limits  1.3.0 -> 2.0.0
            Require a test at the limit for every retry policy.
  new       practices/testing/verify-retries       1.0.0
            Add the rule.
  pinned    practices/testing/verify-backoff       1.3.0
            Newest version: 2.0.0.
            Reason: Waiting on the author's response to acme/.code-rules#45.

• Update one library with code-rules project update team, or one rule with code-rules project update team:RULE.
• Pin a rule to an exact version, with a reason, under the source's pins in .code-rules/config.yaml, or with code-rules project update --keep SOURCE:RULE --reason '...'. Updates never move a pinned rule.
• Decline a new rule with code-rules project update --exclude SOURCE:RULE --reason '...'.
• Replace a forked rule with a fork of the library's newest version with code-rules project update --update-fork SOURCE:RULE. This overwrites your edits to the fork.

See Update rules. (#71, #77, #83)

Fork a library rule

code-rules project add rule ID --from LIBRARY@VERSION copies one version of a library rule and its assets into local/, so your project controls its text. It adds attribution and an exclusion that records the forked version as basedOn. code-rules project update then lists the library's later changes to the rule, so you can decide whether your fork needs them. (#71, #78)

⬆️ Improvements

• After a library's first library release, code-rules library check fails when a changed, new, or deleted rule has no change note, or a note doesn't match a change. When it passes, it previews the versions the next library release will publish. code-rules library init now also writes .github/workflows/code-rules.yml, which runs code-rules library check on every pull request. See Check changes in CI. (#71, #73)
• Import single rules without the rest of their group with the source's rules list, or code-rules project add library --rules RULE. (#71, #74)
• Import exactly what one library release published with ref: release/<number>. (#71, #74)
• Library authors can choose group IDs from the canonical group list, so tools can show the same technology or practice together across libraries. (#86)
• code-rules project init now ends by telling you to connect your coding agent, and the managed .code-rules/README.md shows the section to add to AGENTS.md, CLAUDE.md, or your agent's instruction file. code-rules project init --help explains what init creates and what running it again does. (#70)
• Code Rules never shows text from Git, Git servers, or gh, which can contain credentials. Its errors name the likely cause and give an error code instead, and it hides credentials in repository addresses it displays. (#71, #83)
• Human output, prompts, and errors show control characters as visible escapes, so text from a library can't rewrite what your terminal displays. (#71, #81)
• An invalid answer at a prompt lists the valid answers, and a missing required input without a terminal names the flag to pass. (#71)
• Projects import only the shared assets/ files that their selected rules link to, instead of the whole directory. (#71, #79)

🐛 Squashed Bugs

• Error messages started with a blank line, and new rule drafts had an extra blank line after their metadata. Both are gone. (#71, #83)
• The notice in generated/provenance.json said to run project commands from the project root, although they work from any subdirectory of a Git repository. It now says so. (#71, #76)

⛓️‍💥 Breaking Changes

This release changes the project configuration format, vendored snapshots, generated files, and JSON output, and projects now follow a library's rule versions only after it publishes a release/<number> tag; because Code Rules is still in initial development and hasn't been announced, we're not including upgrade instructions. (#71)

Pull Requests

✨ Features

• Document per-rule versioning by @josh-padnick in #71
• Tell users how to connect their coding agent after project init by @josh-padnick in #70
• Add the canonical group list by @josh-padnick in #86

📖 Documentation

• Rewrite README as a product landing page by @josh-padnick in #57
• Remove stale maintainer notes and bring maintainer and agent docs up to date by @josh-padnick in #84

🤖 CI

• Upgrade Release Planner to v0.4.2 by @josh-padnick in #64
• Upgrade Release Planner to v0.4.3 by @josh-padnick in #66

🧹 Chores

• Keep quick-exiting children's terminal output in terminalfixture by @josh-padnick in #65
• Keep preview installer tests within their time limits under load by @josh-padnick in #80
• Use Fabrica's public rules when building Code Rules by @josh-padnick in #69

Full Changelog: v0.1.0...v0.2.0

v0.1.0

🚀 Introducing Code Rules!

Meet Code Rules, the package manager for engineering best practices. This first release lets you share rules across projects, customize them for each project, and generate guidance your coding agents can follow.

• Write your own rules. Set up a project with code-rules project init, then add project-only groups and rules.

• Import shared rules. Add rule libraries from Git, pin them to a version, and pick, exclude, or replace their rules.

• Generate guidance, and check it in CI. code-rules project sync builds guidance optimized for reading by your agents.

• Publish your own libraries. Create, validate, and share a rule library with code-rules library.

• Install on macOS and Linux with Homebrew or the install script.

  brew install fabricahq/tap/code-rules

To get started, see the Code Rules docs.