Skip to content

AGENTS.md

Latest commit

 

History

History
44 lines (35 loc) · 3.54 KB

AGENTS.md

File metadata and controls

44 lines (35 loc) · 3.54 KB
Raw

Repository instructions

Release versioning

  • Development continues on 0.x. Breaking changes (!, BREAKING CHANGE, or BREAKING-CHANGE) produce a minor bump in 0.x and a major bump from stable 1.x onward. Breaking changes take precedence over all other commit types regardless of commit order.
  • The first stable release requires an explicit maintainer decision and must use 1.0.1. The accidental 1.0.0 is reserved forever; do not reuse it or its prerelease numbers. Request 1.0.1 explicitly instead of major or premajor when leaving 0.x.
  • Keep the historical v1.0.0 tag, but exclude it from the release baseline, bump recommendation, changelog range, and contributor range. The recovery release is 0.10.0, calculated from the restored 0.9.0 baseline without reverting product code.
  • Without breaking changes, feat and revert produce a minor bump; fix, perf, refactor, and ci produce a patch bump. Patch releases preserve compatibility at every version; from stable 1.x onward, minor releases must also preserve public TypeScript types and runtime behavior.
  • docs, test, chore, build, and style without breaking changes do not trigger a release on their own.
  • Keep breaking-change markers and migration notes; the pre-1.0 minor-bump policy does not make incompatible changes backward compatible.
  • Configure whatBump directly under @release-it/conventional-changelog. Verify version-policy changes through the installed release-it CLI in isolated fixtures, including the historical v1.0.0 tag and the explicit 1.0.1 transition.
  • Preview with npm run release:preview and npm run release:notes. These stop before writes; do not use an ordinary release or a dry run merely to inspect the next version or notes.

Changelog

  • Never edit CHANGELOG.md manually, including adding Unreleased entries or changing formatting.
  • CHANGELOG.md is generated by release-it using @release-it/conventional-changelog, configured in .release-it.cjs.
  • Leave changelog updates to the release workflow; do not run a release just to refresh the changelog.
  • Include only feat, fix, perf, refactor, and revert commits in generated changelogs and GitHub Release Notes. Features is the section title for feat, not a separate commit type. Exclude all other types and untyped commits, including their breaking-change notes.
  • Apply the release-note filter in writerOpts.transform; narrowing the preset's type list alone is insufficient. Keep version calculation independent of this filter.

Codebase Knowledge Graph (codebase-memory-mcp)

This project uses codebase-memory-mcp to maintain a knowledge graph of the codebase. ALWAYS prefer MCP graph tools over grep/glob/file-search for code discovery.

Priority Order

  1. search_graph — find functions, classes, routes, variables by pattern
  2. trace_path — trace who calls a function or what it calls
  3. get_code_snippet — read specific function/class source code
  4. query_graph — run Cypher queries for complex patterns
  5. get_architecture — high-level project summary

When to fall back to grep/glob

  • Searching for string literals, error messages, config values
  • Searching non-code files (Dockerfiles, shell scripts, configs)
  • When MCP tools return insufficient results

Examples

  • Find a handler: search_graph(name_pattern=".*OrderHandler.*")
  • Who calls it: trace_path(function_name="OrderHandler", direction="inbound")
  • Read source: get_code_snippet(qualified_name="pkg/orders.OrderHandler")