Skip to main content

​
Prerequisites

  • mise — manages tooling (Bun, lefthook) via mise.toml

​
Setup

1

Clone the repository

git clone git@github.com:agent-facets/facets.git
cd facets
2

Install tools

mise install
This installs Bun and lefthook (git hooks) as specified in mise.toml.
3

Install dependencies

bun install
Installs all workspace dependencies and sets up git hooks via lefthook.

​
Scripts

CommandDescription
bun devRun facet from source (e.g. bun dev build ./my-facet)
bun checkLint + typecheck + build + test (run this before submitting a PR)
bun run lintBiome lint only
bun run formatBiome auto-fix and format
bun run testRun tests
bun run typesTypecheck only
bun run buildBuild only

​
Pull requests

  • Keep PRs focused on a single change.
  • Run bun check before submitting — CI runs the same command.
  • Add a changeset for any user-facing changes (see below).

​
Changesets

Before submitting a PR that changes published packages, run: 
bun change
Follow the prompts to select a bump type (patch/minor/major) and write a summary. Commit the generated .md file with your PR. A good changeset describes:
  • What the change is
  • Why the change was made
  • How a consumer should update their code (if applicable)
Not every PR needs a changeset — changes to docs, CI, or other non-published files can skip this step. The changeset bot comments on every PR to indicate whether one is present.

​
Platform packages

agent-facets is distributed as per-platform npm packages under @agent-facets/cli-*. When adding new platform targets, a maintainer will run bun seed to claim package names on npm, then follow the publishing guide to configure authentication for CircleCI.