Skip to main content

​
Workflows

CI runs on CircleCI with two separate config files, each defining one workflow:
Config fileWorkflowTriggerPurpose
.circleci/config.ymlciEvery pushLint, typecheck, test (PRs); plus changesets and tag-release (main)
.circleci/release.ymlreleaseTag pushPer-package publish to npm

​
CI workflow

The ci workflow has two jobs that run on different branches:

​
check (PR branches)

Runs on every push to branches except main. Executes bun run check (lint + typecheck + build + test). No notifications — PR failures are visible in GitHub.

​
main-pipeline (main only)

Runs on pushes to main only. Executes three steps sequentially in a single job:
  1. Check — bun run check (same as PR)
  2. Changesets — bun scripts/ci-changesets.ts (consume changesets, open/update version PR)
  3. Tag Release — bun scripts/ci-tag-release.ts (create version tags for unpublished packages)
Sends a notification on failure.

​
Release workflow

Triggered by tag pushes matching @agent-facets/*@<version> or agent-facets@<version>. Runs bun scripts/ci-release.ts, which parses the tag and runs the appropriate publish pipeline. See Release Pipeline for details. Sends notifications on both failure and success.

​
Contexts

CircleCI contexts provide environment variables to jobs:
ContextVariablesUsed by
turbo-cacheTurborepo remote cache credentialscheck, main-pipeline, release
releasenpm OIDC config, GitHub app credentialsmain-pipeline, release
slack-secretsNotification webhook credentialsmain-pipeline, release

​
Config source structure

CircleCI configs are authored as modular YAML files under source directories, then packed into single files for CircleCI to consume: 
.circleci/
  src/                    # CI workflow source
    commands/             # Reusable command definitions
    jobs/                 # Job definitions
    workflows/            # Workflow definitions
    @config.yml           # Base config (version, orbs)
  release-src/            # Release workflow source (same structure)
  config.yml              # Packed CI config (generated)
  release.yml             # Packed release config (generated)
Commands in release-src/commands/ are symlinks to src/commands/ to avoid duplication.

​
Modifying CI

1

Edit source files

Edit files under .circleci/src/ or .circleci/release-src/.
2

Regenerate packed configs

bun run ci:pack
This runs circleci config pack on both source directories.
3

Verify

bun check includes a ci:check-pack task that diffs the packed output against the committed files. If they diverge, CI fails with a message to run bun run ci:pack.