CI Architecture

CircleCI workflow structure, job definitions, and configuration management.

Workflows

CI runs on CircleCI with three workflows across two separate config files.

Config	Trigger	Workflows
.circleci/development.yml	Pushes	ci
.circleci/release.yml	Tags	release + release-cli

Workflow	Trigger Filter	Purpose
ci	Any branch including main	Lint, typecheck, test (PRs); plus changesets and tag-release (main)
release	Tags: @agent-facets/*@*	Library package publish to npm
release-cli	Tags: agent-facets@*	CLI matrix publish to npm

CI workflow

The ci workflow has two jobs that run on different branches, check and main-pipeline.

check (PR branches)

Runs on every push to branches except main. We use Turborepo for caching and incremental builds.

1. Load artifacts from remote cache
2. Validate via bun check with remote caching
3. Save artifacts to remote turbo cache

main-pipeline (main only)

Runs on pushes to main only. Executes three steps sequentially in a single job:

1. Check

   Run bun check with caching (same as PR branches)

2. Changesets

   bun scripts/release/version.ts (consume changesets, open/update version PR)

3. Tag Release

   bun scripts/release/tag.ts (create version tags for unpublished packages)

4. Sends maintainer notification on failure

Release workflows

Triggered explicitly via CircleCI API v2 by scripts/release/tag.ts after pushing tags (see Release Pipeline for why we don’t rely on tag-push webhooks). The tag pattern determines which workflow within the release pipeline runs.

release (library packages)

Triggered by scoped tags matching @agent-facets/*@<version>. Each tag publishes one library package.

1. Parses the package name and version from the tag
2. Skips private packages
3. Builds via turbo
4. Publishes the package to npm
5. Creates a GitHub Release
6. Sends maintainer notification

release-cli (CLI)

Triggered by unscoped tags matching agent-facets@<version>. Uses a three-stage matrix pipeline.

1. Build CLI

   Cross-compiles all 12 platform binaries, persists build output to workspace

2. Publish Platform Packages 12 total

   Each matrix instance publishes one platform binary directly to latest in its own executor

3. Finalize CLI

Both workflows send failure notifications via the notify-failure reusable command.

Notifications

1. Failure notifications – any release workflow failure notifies maintainers
2. Success notifications – when any package successfully publishes to npm

Contexts

CircleCI contexts provide environment variables to jobs.

Context	Variables	Used by
turbo-cache	TURBO_API, TURBO_TOKEN (TURBO_TEAM lives in mise.toml)	check, main-pipeline, all release jobs
bot-context	npm OIDC config, GitHub app credentials, CircleCI API token	main-pipeline, all release jobs
slack-secrets	Notification webhook credentials	main-pipeline, all release jobs

turbo-cache provides the consumer-side credentials for the self-hosted Turborepo remote cache. The cache server itself is deployed from the sibling facet-cafe repo at infra/turbo-cache.ts — an SST AWS Lambda backed by an S3 bucket, fronted by a CloudFront router. The current production URL is https://turbo-cache.facet.cafe (the main SST stage); the bearer token is held in 1Password and mirrored into both the turbo-cache CircleCI context (as TURBO_TOKEN) and the AWS-side TurboToken SST secret. To verify the cache is healthy, curl https://turbo-cache.facet.cafe/v8/artifacts/status should return {"status":"enabled",...}.

bot-context includes CIRCLECI_API_TOKEN (a personal API token with write access to the project), which scripts/release/tag.ts uses to explicitly trigger release pipelines via the CircleCI v2 API. See Release Pipeline troubleshooting for rotation steps.

Config source structure

CircleCI configs are authored as modular YAML files under source directories. Running bun ci:pack will compile them into single files for CircleCI to consume.

.circleci

development CI

commands

jobs

workflows

@config.yml

release CD

commands contents are symlinks to ../development/commands/*

jobs

workflows

@config.yml

development.yml packed CI config (generated)

release.yml packed CD config (generated)

Commands in release/commands/ are symlinks to development/commands/

This is because the CircleCI config pack tool does not support imports or other forms of code sharing.

Modifying CI

1. Edit source files

   Edit files under .circleci/development/ or .circleci/release/.

2. Regenerate packed configs

   bun run ci:pack
   

   This runs circleci config pack on both source directories.

3. Commit & Verify

   Commit the changes and verify that the CircleCI config works in your PR