build-package · diff
git:20260408.6cd4538 to git:20260410.db53cb3
90 added, 100 removed. Audit A to A.
---
name: build-package
- description: Build a specific Reactive Agents package from its spec. Guides you through the complete build process for any package in the monorepo.
- disable-model-invocation: true
+ description: Add a new package to the Reactive Agents monorepo. Covers scaffolding, package.json, tsconfig, layer wiring, and index exports. Use when creating a net-new @reactive-agents/* package.
argument-hint: <package-name>
---
- # Build Package: $ARGUMENTS
-
- ## Pre-Flight Checks
-
- 1. Verify the monorepo is set up (root `package.json` with workspaces exists). If not, follow `spec/docs/00-monorepo-setup.md` first.
- 2. Verify all dependency packages for this package are already built and passing tests.
-
- ## Build Process
-
- Follow these steps exactly for the `$ARGUMENTS` package:
+ # Add New Package: $ARGUMENTS
- ### Step 1: Identify the spec file
+ All 22 core packages exist. Use this skill only when creating a genuinely new package.
- Look up the package in the build order table. Read the corresponding spec file from `spec/docs/`. The spec files are:
+ ## Step 1: Determine the layer
- | Package | Spec File |
- | ------------- | ------------------------------------------------------ |
- | core | `layer-01-core-detailed-design.md` |
- | llm-provider | `01.5-layer-llm-provider.md` |
- | memory | `02-layer-memory.md` |
- | reasoning | `03-layer-reasoning.md` |
- | verification | `04-layer-verification.md` |
- | cost | `05-layer-cost.md` |
- | identity | `06-layer-identity.md` |
- | orchestration | `07-layer-orchestration.md` |
- | tools | `08-layer-tools.md` |
- | observability | `09-layer-observability.md` |
- | interaction | `layer-10-interaction-revolutionary-design.md` |
- | runtime | `layer-01b-execution-engine.md` |
- | guardrails | `11-missing-capabilities-enhancement.md` (Package 1) |
- | eval | `11-missing-capabilities-enhancement.md` (Package 2) |
- | prompts | `11-missing-capabilities-enhancement.md` (Package 3) |
- | cli | `11-missing-capabilities-enhancement.md` (Extension 7) |
- | a2a | `14-v0.5-comprehensive-plan.md` (Sprint 1) |
- | gateway | No dedicated spec — see AGENTS.md package dependency tree and package map |
- | testing | No dedicated spec — see AGENTS.md package dependency tree and package map |
- | benchmarks | No dedicated spec — see AGENTS.md package dependency tree and package map |
- | health | No dedicated spec — see AGENTS.md package dependency tree and package map |
- | reactive-intelligence | No dedicated spec — see AGENTS.md package dependency tree and package map |
+ Identify which dependency layer your package belongs to (from `architecture-reference`):
- ### Step 2: Read the full spec
+ | Your package depends on | Layer |
+ |------------------------|-------|
+ | Nothing (or only external npm) | Layer 0 |
+ | `core` only | Layer 1 |
+ | `core` + `llm-provider` | Layer 2 |
+ | Multiple Layer 1–2 packages | Layer 3 |
+ | All packages (facade) | Layer 4 |
- Read the entire spec file. Pay special attention to:
+ Packages can only depend on packages in lower layers.
- - **Package Structure** section — create all directories exactly as shown
- - **Build Order** section — implement files in this exact numbered sequence
- - **package.json** section — use exact dependencies listed
+ ## Step 2: Scaffold directory structure
- ### Step 3: Create package.json
+ ```bash
+ mkdir -p packages/$ARGUMENTS/src/services
+ mkdir -p packages/$ARGUMENTS/tests
+ ```
- Create `packages/$ARGUMENTS/package.json` with the dependencies from the spec. Use this template:
+ ## Step 3: Create package.json
```json
{
"name": "@reactive-agents/$ARGUMENTS",
"version": "0.0.1",
"type": "module",
"main": "src/index.ts",
"types": "src/index.ts",
"scripts": {
"build": "tsup",
"typecheck": "tsc --noEmit",
- "test": "bun test"
+ "test": "bun test --timeout 15000"
},
"dependencies": {
- "effect": "^3.10.0"
+ "effect": "^3.10.0",
+ "@reactive-agents/core": "workspace:*"
},
"devDependencies": {
"typescript": "^5.7.0",
- "bun-types": "latest"
+ "bun-types": "latest",
+ "tsup": "^8.0.0"
}
}
```
- Add internal dependencies as needed (e.g., `"@reactive-agents/core": "workspace:*"`).
-
- **Note:** Do not hardcode version numbers — Changesets manages versioning across the monorepo. Use `"0.0.1"` as a placeholder; the actual version will be set by `changeset version` at release time.
+ Add additional `@reactive-agents/*` workspace dependencies based on your layer assignment.
- ### Step 4: Create tsconfig.json
+ ## Step 4: Create tsconfig.json
```json
{
"extends": "../../tsconfig.json",
"compilerOptions": {
- "rootDir": "src",
- "outDir": "dist"
+ "outDir": "dist",
+ "rootDir": "src"
},
- "include": ["src/**/*.ts"],
- "exclude": ["node_modules", "dist", "tests"]
+ "include": ["src/**/*", "tests/**/*"]
}
```
- ### Step 5: Implement files in Build Order
+ ## Step 5: Create tsup.config.ts
- For each file in the spec's Build Order:
+ ```typescript
+ import { defineConfig } from "tsup";
- 1. Read the exact code from the spec
- 2. Create the file, following the spec code closely
- 3. Ensure all imports reference the correct packages
- 4. Verify Effect-TS patterns are followed:
- - Types use `Schema.Struct`
- - Errors use `Data.TaggedError`
- - Services use `Context.Tag` + `Layer.effect`
- - State uses `Ref`
- - No `throw`, no raw `await`
+ export default defineConfig({
+ entry: ["src/index.ts"],
+ format: ["esm"],
+ dts: true,
+ clean: true,
+ sourcemap: true,
+ });
+ ```
- ### Step 6: Create the runtime factory
+ ## Step 6: Create errors.ts
- Create `src/runtime.ts` with a `createXxxLayer()` function that composes all services.
+ ```typescript
+ // packages/$ARGUMENTS/src/errors.ts
+ import { Data } from "effect";
- ### Step 7: Create index.ts
+ export class $ARGUMENTSError extends Data.TaggedError("$ARGUMENTSError")<{
+ readonly message: string;
+ readonly cause?: unknown;
+ }> {}
- Create `src/index.ts` that re-exports all public types, errors, services, and the layer factory.
+ export type $ARGUMENTSErrors = $ARGUMENTSError;
+ ```
- ### Step 8: Write tests
+ ## Step 7: Create your first service
- Create test files as specified. Use `bun:test` (`describe`, `it`, `expect`). Test with the Effect test runtime:
+ Follow `.agents/skills/implement-service/SKILL.md` for the service template.
+ ## Step 8: Create runtime.ts (layer factory)
+
```typescript
- import { Effect, Layer } from "effect";
- import { describe, it, expect } from "bun:test";
+ // packages/$ARGUMENTS/src/runtime.ts
+ import { Layer } from "effect";
+ import { MyServiceLive } from "./services/my-service.js";
+ import { DependencyServiceLive } from "@reactive-agents/core";
- describe("MyService", () => {
- const testLayer = createMyLayer();
+ export const create$ARGUMENTSLayer = () =>
+ Layer.mergeAll(
+ MyServiceLive.pipe(Layer.provide(DependencyServiceLive)),
+ );
+ ```
- it("should do work", async () => {
- const result = await Effect.gen(function* () {
- const svc = yield* MyService;
- return yield* svc.doWork("input");
- }).pipe(Effect.provide(testLayer), Effect.runPromise);
+ ## Step 9: Create index.ts
- expect(result).toBe("expected");
- });
- });
+ ```typescript
+ // packages/$ARGUMENTS/src/index.ts
+ export { MyService, MyServiceLive } from "./services/my-service.js";
+ export { create$ARGUMENTSLayer } from "./runtime.js";
+ export type { $ARGUMENTSErrors } from "./errors.js";
```
- ### Step 9: Run tests
+ ## Step 10: Register in workspace
- ```bash
- bun test packages/$ARGUMENTS
+ Add to root `package.json` workspaces array if using explicit list:
+
+ ```json
+ "packages/$ARGUMENTS"
```
- All tests must pass before moving to the next package.
+ ## Step 11: Update architecture-reference and AGENTS.md
- ### Step 10: Build and verify
+ After creating the package, update:
- ```bash
- bun install
- bun run --filter "@reactive-agents/$ARGUMENTS" build
- ```
+ - `.agents/skills/architecture-reference/SKILL.md` — add to package list and dependency graph
+ - `AGENTS.md` — add to package count and dependency tree
+ - `README.md` — add to packages table
+ - `.agents/MEMORY.md` — update current package count
- This runs `tsup` to compile ESM + DTS output into `dist/`. The compiled output is what downstream packages consume.
+ ## Step 12: Write tests and build
- ## Critical Reminders
+ ```bash
+ # Write at least one test (see agent-tdd skill)
+ bun test packages/$ARGUMENTS --timeout 15000
- - **Copy from the spec** — the spec contains exact code to implement. Do not invent patterns.
- - **Follow the Build Order** — files have dependencies on each other. Order matters.
- - **Check dependency packages exist** — if the spec imports from `@reactive-agents/core`, that package must be built first.
- - **One package at a time** — complete and test one package before starting the next.
+ # Build
+ bun run build --filter @reactive-agents/$ARGUMENTS
+
+ # Typecheck
+ bun run typecheck --filter @reactive-agents/$ARGUMENTS
+ ```