Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (54 loc) · 2.53 KB

AGENTS.md

File metadata and controls

79 lines (54 loc) · 2.53 KB
Raw

AGENTS.md

Rules for any agent (human or AI) working in this repository.

Branching & PRs

  • Branch from main for all changes
  • PRs always target main
  • Always add @guy-shahine and @akadenia-leaf as reviewers — Guy is the code owner for all files (CODEOWNERS: * @guy-shahine)
  • Check gh pr list before creating a new PR — never duplicate an open PR

PR Titles

Conventional Commits with an optional scope, enforced by check_pr_title_style.yml:

type(optional-scope): lowercase subject
  • Scope is optional — feat: add new feature is valid
  • Disallowed scope: core
  • Allowed types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

Examples:

✅  feat(helpers): add string truncation utility
✅  fix(api): handle empty response body
✅  chore(deps): upgrade dependencies to latest
✅  feat: add new feature without scope
❌  feat(core): disallowed scope

Git Commits

  • All commits must be signed — use SSH or GPG signing (git config commit.gpgsign true)
  • Use conventional commit messages matching the PR title format
  • Always start from a freshly synced branch — run git fetch origin && git checkout -b your-branch origin/main before creating any branch. Never branch from a stale local checkout.

Pre-Push Checklist — MANDATORY

Before every push, run all three and fix any failures:

pnpm run lint
pnpm test
pnpm run build

Never use --no-verify. No exceptions.

Releases

Releases are handled automatically by semantic-release on push to main:

  • feat(...) commits → minor version bump
  • fix(...) commits → patch version bump
  • BREAKING CHANGE in commit body → major version bump
  • Release is published to npm as @akadenia/<package>

Do not manually bump versions in package.json.

TypeScript

  • Keep TypeScript at ^5.x — do not upgrade to TypeScript 6.x until ts-jest adds support
  • Build with pnpm run build (compiles to dist/)

README / Documentation

  • Maximum heading depth is h3 (###) — never use #### or deeper in README.md
  • The README is mirrored as MDX on akadenia.com, which only supports h1–h3. h4+ headings break the MDX parser and the website build.
  • Use bold text instead of h4 for sub-sections under h3.

Testing

  • Tests live in __tests__/, run with jest
  • All tests must pass before pushing

Note: Integration tests require Azurite (local Azure emulator). Use pnpm test:with-azurite for full test suite, or pnpm test for unit tests only.