build-package git:20260315.a07056dA

Immutable. This exact content is served forever at /api/v1/blob/2e70914551f6709b.

---
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
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:

### Step 1: Identify the spec file

Look up the package in the build order table. Read the corresponding spec file from `spec/docs/`. The spec files are:

| 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 CLAUDE.md package map           |
| testing       | No dedicated spec — see CLAUDE.md package map           |
| benchmarks    | No dedicated spec — see CLAUDE.md package map           |
| health        | No dedicated spec — see CLAUDE.md package map           |
| reactive-intelligence | No dedicated spec — see CLAUDE.md package map   |

### Step 2: Read the full spec

Read the entire spec file. Pay special attention to:

- **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 3: Create package.json

Create `packages/$ARGUMENTS/package.json` with the dependencies from the spec. Use this template:

```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"
  },
  "dependencies": {
    "effect": "^3.10.0"
  },
  "devDependencies": {
    "typescript": "^5.7.0",
    "bun-types": "latest"
  }
}
```

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.

### Step 4: Create tsconfig.json

```json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "tests"]
}
```

### Step 5: Implement files in Build Order

For each file in the spec's Build Order:

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`

### Step 6: Create the runtime factory

Create `src/runtime.ts` with a `createXxxLayer()` function that composes all services.

### Step 7: Create index.ts

Create `src/index.ts` that re-exports all public types, errors, services, and the layer factory.

### Step 8: Write tests

Create test files as specified. Use `bun:test` (`describe`, `it`, `expect`). Test with the Effect test runtime:

```typescript
import { Effect, Layer } from "effect";
import { describe, it, expect } from "bun:test";

describe("MyService", () => {
  const testLayer = createMyLayer();

  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);

    expect(result).toBe("expected");
  });
});
```

### Step 9: Run tests

```bash
bun test packages/$ARGUMENTS
```

All tests must pass before moving to the next package.

### Step 10: Build and verify

```bash
bun install
bun run --filter "@reactive-agents/$ARGUMENTS" build
```

This runs `tsup` to compile ESM + DTS output into `dist/`. The compiled output is what downstream packages consume.

## Critical Reminders

- **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.