Build
How to build, deploy, and publish in this monorepo.
Local Build
npm run build # Build all packages (core deps first)
npm run build -w packages/<name> # Build a specific package
npm run build -w workspaces/<name> # Build a specific workspace
npm run build:core-deps # Build types, errors, fabric (dependency order)
npm run clean # Remove all dist/ directories
Build order matters: types -> errors -> fabric -> everything else. The top-level npm run build handles this automatically via build:core-deps.
Typecheck and Lint
npm run typecheck # Typecheck all workspaces
npm run typecheck -w packages/<name> # Typecheck a specific package
npm run lint # Lint everything (quiet mode)
npm run format # Auto-fix lint + sort package.json
CI/CD Workflows
NPM Check (npm-check.yml)
Runs on pushes to feature branches. Validates code quality before merge.
| Trigger |
Branches/Tags |
| Push |
branch/*, claude/*, codex/*, devin/*, fix/*, feat/* |
| Tag |
check-* |
Jobs (all parallel):
- Lint: Node 24,
npm run lint
- Typecheck: Node 24,
npm run typecheck (continue-on-error)
- Unit Test: Matrix [Node 22, 24, 25],
npm test with optional Datadog tracing
- LLM Client Test: Conditional, only when
packages/llm/** changes
NPM Deploy (npm-deploy.yml)
Publishes packages to npm. Skips already-published versions automatically.
| Trigger |
Effect |
Push to main |
Publish stable versions |
Tag deploy-* |
Publish stable versions |
Tag dev-* |
Publish with --tag dev (only -dev.N versions) |
Tag rc-* |
Publish with --tag rc (only -rc.N versions) |
Stack Deployments
CDK infrastructure deploys via separate workflows:
| Workflow |
Trigger |
Environment |
deploy-env-sandbox.yml |
branch/*, claude/*, feat/*, fix/*, sandbox/* branches; sandbox-* tags; only workspaces/** path changes |
sandbox |
deploy-env-development.yml |
main branch, development/* branches, development-* tags; only workspaces/** path changes |
development |
deploy-env-production.yml |
production-* tags, v0.*/v1.* tags |
production |
deploy-stacks.yml |
Manual (workflow_dispatch) |
sandbox/development/production |
deploy-stack-documentation.yml |
main/feat/*/sandbox/* branches when workspaces/documentation/** changes; stack-documentation-*/sandbox-* tags; manual |
sandbox/development/production |
Branching Strategy
| Branch Pattern |
Purpose |
Triggers |
main |
Stable releases |
npm-deploy, stack deploy to development |
feat/* |
Feature development |
npm-check, stack deploy to sandbox |
fix/* |
Bug fixes |
npm-check, stack deploy to sandbox |
branch/* |
General work |
npm-check, stack deploy to sandbox |
claude/* |
AI agent work |
npm-check, stack deploy to sandbox |
codex/* |
AI agent work |
npm-check |
devin/* |
AI agent work |
npm-check |
sandbox/* |
Sandbox testing |
stack deploy to sandbox |
development/* |
Development testing |
stack deploy to development |
Tags
| Tag Pattern |
Purpose |
check-* |
Trigger npm-check manually |
deploy-* |
Trigger npm publish (stable) |
dev-* |
Publish with dev dist-tag |
rc-* |
Publish with rc dist-tag |
sandbox-* |
Deploy stacks to sandbox |
development-* |
Deploy stacks to development |
production-* |
Deploy stacks to production |
v0.*, v1.* |
Deploy stacks to production |
stack-documentation-* |
Deploy documentation stack only |
Publishing Packages
Packages publish automatically when merged to main. The workflow:
- Iterates over all
packages/*/
- Skips
private: true packages
- Compares local version to npm registry
- Publishes only if version is new (with
--provenance)
To publish a pre-release:
- Bump version to include
-rc.0 or -dev.0 suffix
- Run
npm i --package-lock-only
- Push a tag:
git tag rc-description && git push origin rc-description
Completion Criteria
See .claude/skills/green/SKILL.md.
1---2name: build-43description: Build commands, CI/CD workflows, branching strategy, npm publishing4---5
6# Build
7
8How to build, deploy, and publish in this monorepo.
9
10## Local Build
11
12```bash
13npm run build # Build all packages (core deps first)
14npm run build -w packages/<name> # Build a specific package
15npm run build -w workspaces/<name> # Build a specific workspace
16npm run build:core-deps # Build types, errors, fabric (dependency order)
17npm run clean # Remove all dist/ directories
18```
19
20Build order matters: `types` -> `errors` -> `fabric` -> everything else. The top-level `npm run build` handles this automatically via `build:core-deps`.
21
22## Typecheck and Lint
23
24```bash
25npm run typecheck # Typecheck all workspaces
26npm run typecheck -w packages/<name> # Typecheck a specific package
27npm run lint # Lint everything (quiet mode)
28npm run format # Auto-fix lint + sort package.json
29```
30
31## CI/CD Workflows
32
33### NPM Check (`npm-check.yml`)
34
35Runs on pushes to feature branches. Validates code quality before merge.
36
37| Trigger | Branches/Tags |
38|---------|---------------|
39| Push | `branch/*`, `claude/*`, `codex/*`, `devin/*`, `fix/*`, `feat/*` |
40| Tag | `check-*` |
41
42Jobs (all parallel):
43- **Lint**: Node 24, `npm run lint`
44- **Typecheck**: Node 24, `npm run typecheck` (continue-on-error)
45- **Unit Test**: Matrix [Node 22, 24, 25], `npm test` with optional Datadog tracing
46- **LLM Client Test**: Conditional, only when `packages/llm/**` changes
47
48### NPM Deploy (`npm-deploy.yml`)
49
50Publishes packages to npm. Skips already-published versions automatically.
51
52| Trigger | Effect |
53|---------|--------|
54| Push to `main` | Publish stable versions |
55| Tag `deploy-*` | Publish stable versions |
56| Tag `dev-*` | Publish with `--tag dev` (only `-dev.N` versions) |
57| Tag `rc-*` | Publish with `--tag rc` (only `-rc.N` versions) |
58
59### Stack Deployments
60
61CDK infrastructure deploys via separate workflows:
62
63| Workflow | Trigger | Environment |
64|----------|---------|-------------|
65| `deploy-env-sandbox.yml` | `branch/*`, `claude/*`, `feat/*`, `fix/*`, `sandbox/*` branches; `sandbox-*` tags; only `workspaces/**` path changes | sandbox |
66| `deploy-env-development.yml` | `main` branch, `development/*` branches, `development-*` tags; only `workspaces/**` path changes | development |
67| `deploy-env-production.yml` | `production-*` tags, `v0.*`/`v1.*` tags | production |
68| `deploy-stacks.yml` | Manual (`workflow_dispatch`) | sandbox/development/production |
69| `deploy-stack-documentation.yml` | `main`/`feat/*`/`sandbox/*` branches when `workspaces/documentation/**` changes; `stack-documentation-*`/`sandbox-*` tags; manual | sandbox/development/production |
70
71## Branching Strategy
72
73| Branch Pattern | Purpose | Triggers |
74|---------------|---------|----------|
75| `main` | Stable releases | npm-deploy, stack deploy to development |
76| `feat/*` | Feature development | npm-check, stack deploy to sandbox |
77| `fix/*` | Bug fixes | npm-check, stack deploy to sandbox |
78| `branch/*` | General work | npm-check, stack deploy to sandbox |
79| `claude/*` | AI agent work | npm-check, stack deploy to sandbox |
80| `codex/*` | AI agent work | npm-check |
81| `devin/*` | AI agent work | npm-check |
82| `sandbox/*` | Sandbox testing | stack deploy to sandbox |
83| `development/*` | Development testing | stack deploy to development |
84
85## Tags
86
87| Tag Pattern | Purpose |
88|-------------|---------|
89| `check-*` | Trigger npm-check manually |
90| `deploy-*` | Trigger npm publish (stable) |
91| `dev-*` | Publish with `dev` dist-tag |
92| `rc-*` | Publish with `rc` dist-tag |
93| `sandbox-*` | Deploy stacks to sandbox |
94| `development-*` | Deploy stacks to development |
95| `production-*` | Deploy stacks to production |
96| `v0.*`, `v1.*` | Deploy stacks to production |
97| `stack-documentation-*` | Deploy documentation stack only |
98
99## Publishing Packages
100
101Packages publish automatically when merged to `main`. The workflow:
102
1031. Iterates over all `packages/*/`
1042. Skips `private: true` packages
1053. Compares local version to npm registry
1064. Publishes only if version is new (with `--provenance`)
107
108To publish a pre-release:
1091. Bump version to include `-rc.0` or `-dev.0` suffix
1102. Run `npm i --package-lock-only`
1113. Push a tag: `git tag rc-description && git push origin rc-description`
112
113## Completion Criteria
114
115See `.claude/skills/green/SKILL.md`.
majiayu000