archstone 1.0.3 → 1.1.0

package/README.md

@@ -1,20 +1,53 @@
 <div align="center">
 
-# archstone
+<br />
 
-**TypeScript architecture foundation for backend services.**
-Stop re-implementing DDD boilerplate. Focus on your domain.
+# Archstone
 
-[![npm](https://img.shields.io/npm/v/archstone?style=flat-square&color=black)](https://www.npmjs.com/package/archstone)
-[![license](https://img.shields.io/badge/license-MIT-black?style=flat-square)](./LICENSE)
-[![typescript](https://img.shields.io/badge/TypeScript-5-black?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![bun](https://img.shields.io/badge/Bun-runtime-black?style=flat-square&logo=bun)](https://bun.sh)
+### The TypeScript foundation for serious backend services.
+
+Build on Domain-Driven Design and Clean Architecture — without writing the same boilerplate on every project.
+
+<br />
+
+[![npm version](https://img.shields.io/npm/v/archstone?style=for-the-badge&logo=npm&color=CB3837&logoColor=white)](https://www.npmjs.com/package/archstone)
+[![license](https://img.shields.io/badge/license-MIT-22C55E?style=for-the-badge)](./LICENSE)
+[![typescript](https://img.shields.io/badge/TypeScript-5-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![bun](https://img.shields.io/badge/Bun-ready-F9F1E1?style=for-the-badge&logo=bun&logoColor=black)](https://bun.sh)
+
+<br />
 
 </div>
 
 ---
 
-Archstone gives you the structural pieces of **Domain-Driven Design** and **Clean Architecture** — entities, value objects, aggregates, domain events, use cases, and repository contracts — so every project starts from a solid, consistent foundation.
+## Why archstone?
+
+Every backend project in DDD needs the same structural pieces — and most teams rewrite them from scratch each time. Archstone gives you a **battle-tested, zero-dependency set of base classes and contracts** so you can skip the boilerplate and go straight to modeling your domain.
+
+```ts
+// ❌ Before — scattered, inconsistent, no error contract
+class User { id: string }
+function createUser() { throw new Error('not found') }
+
+// ✅ After — structured, predictable, type-safe
+class User extends AggregateRoot<UserProps> { ... }
+async function createUser(): Promise<Either<NotFoundError, User>> { ... }
+```
+
+---
+
+## Features
+
+- **`Either`** — functional error handling; use cases never throw
+- **`Entity` / `AggregateRoot`** — identity-based domain objects with built-in event support
+- **`ValueObject`** — equality by value, not reference
+- **`UniqueEntityId`** — UUID v7 identity, consistent across your entire domain
+- **`WatchedList`** — track additions and removals in collections without overwriting persistence
+- **`UseCase`** — typed contract for application logic
+- **Repository contracts** — define your interface in the domain; implement in infrastructure
+
+---
 
 ## Install
 
@@ -24,43 +57,39 @@ bun add archstone
 npm install archstone
 ```
 
-## At a Glance
+> Zero runtime dependencies. Pure TypeScript.
 
-| Building block | What it does |
-|---|---|
-| `Entity` / `AggregateRoot` | Identity-based domain objects; aggregates raise domain events |
-| `ValueObject` | Equality by value, not reference |
-| `UniqueEntityId` | UUID v7 identity wrapper |
-| `WatchedList` | Tracks additions and removals in a collection |
-| `Either` | Functional error handling — no throwing in use cases |
-| `UseCase` | Contract for application use cases returning `Either` |
-| `Repository` | CRUD interface contracts — implementations live in infra |
+---
 
 ## Usage
 
-### Either — handle errors without throwing
+### `Either` — stop throwing, start returning
 
 ```ts
 import { Either, left, right } from 'archstone/core'
 
-type Result = Either<UserNotFoundError, User>
+type FindUserResult = Either<UserNotFoundError, User>
 
-async function findUser(id: string): Promise<Result> {
+async function findUser(id: string): Promise<FindUserResult> {
   const user = await repo.findById(id)
+
   if (!user) return left(new UserNotFoundError(id))
   return right(user)
 }
 
+// The caller always handles both cases — no surprises
 const result = await findUser('123')
 
 if (result.isLeft()) {
   console.error(result.value) // UserNotFoundError
 } else {
-  console.log(result.value)   // User
+  console.log(result.value)   // User ✓
 }
 ```
 
-### Entity & AggregateRoot — model your domain
+---
+
+### `Entity` & `AggregateRoot` — model your domain
 
 ```ts
 import { AggregateRoot } from 'archstone/domain/enterprise'
@@ -81,13 +110,17 @@ class Order extends AggregateRoot<OrderProps> {
       ...props,
       createdAt: props.createdAt ?? new Date(),
     })
+
+    // Raise domain events from inside the aggregate
     order.addDomainEvent(new OrderCreatedEvent(order))
     return order
   }
 }
 ```
 
-### ValueObject — equality by value
+---
+
+### `ValueObject` — equality that makes sense
 
 ```ts
 import { ValueObject } from 'archstone/core'
@@ -105,10 +138,13 @@ class Email extends ValueObject<EmailProps> {
 
 const a = Email.create('user@example.com')
 const b = Email.create('user@example.com')
-a.equals(b) // true
+
+a.equals(b) // ✅ true — compared by value, not reference
 ```
 
-### WatchedList — track collection changes
+---
+
+### `WatchedList` — persist only what changed
 
 ```ts
 import { WatchedList } from 'archstone/core'
@@ -121,62 +157,74 @@ const tags = new TagList([existingTag])
 tags.add(newTag)
 tags.remove(existingTag)
 
-tags.getNewItems()     // [newTag]
-tags.getRemovedItems() // [existingTag]
+// Send only the diff to your repository — not the whole list
+tags.getNewItems()     // → [newTag]
+tags.getRemovedItems() // → [existingTag]
 ```
 
+---
+
 ### Domain Events — decouple side effects
 
 ```ts
 import { DomainEvents } from 'archstone/domain/enterprise'
 
-// Register a handler
+// Register handlers anywhere in your infrastructure layer
 DomainEvents.register(
   (event) => sendWelcomeEmail(event as UserCreatedEvent),
   UserCreatedEvent.name,
 )
 
-// Dispatch after persisting the aggregate
+// Dispatch after persistence — events stay inside the aggregate until then
 await userRepository.create(user)
 DomainEvents.dispatchEventsForAggregate(user.id)
 ```
 
-### Repository Contracts — keep infra out of your domain
+---
+
+### Repository Contracts — keep infrastructure out of your domain
 
 ```ts
 import { Repository, Creatable } from 'archstone/domain/application'
 
-// Compose the interface you need
+// Define your contract in the application layer
 export interface UserRepository extends Repository<User> {
   findByEmail(email: string): Promise<User | null>
 }
 
-// Or only what you need
+// Compose only what you need
 export interface AuditRepository extends Creatable<AuditLog> {}
+
+// Implement anywhere in infrastructure — domain stays clean
 ```
 
+---
+
 ## Package Exports
 
-```
-archstone/core              → Either, ValueObject, UniqueEntityId, WatchedList, Optional
-archstone/domain            → all domain exports
-archstone/domain/enterprise → Entity, AggregateRoot, DomainEvent, DomainEvents, EventHandler
-archstone/domain/application → UseCase, UseCaseError, repository contracts
-```
+| Import | Contents |
+|---|---|
+| `archstone/core` | `Either`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional` |
+| `archstone/domain` | All domain exports |
+| `archstone/domain/enterprise` | `Entity`, `AggregateRoot`, `DomainEvent`, `DomainEvents`, `EventHandler` |
+| `archstone/domain/application` | `UseCase`, `UseCaseError`, repository contracts |
 
-## Layer Architecture
+---
+
+## Architecture
 
 ```
 src/
-├── core/                   # Zero domain knowledge — pure utilities
-│   ├── either.ts
-│   ├── value-object.ts
-│   ├── unique-entity-id.ts
-│   ├── watched-list.ts
-│   └── types/optional.ts
+├── core/                    # Zero domain knowledge — pure language utilities
+│   ├── either.ts            # Left / Right functional result type
+│   ├── value-object.ts      # Value equality base class
+│   ├── unique-entity-id.ts  # UUID v7 identity wrapper
+│   ├── watched-list.ts      # Change-tracked collection
+│   └── types/
+│       └── optional.ts      # Optional<T, K> helper type
 │
 └── domain/
-    ├── enterprise/         # Pure domain model — no framework deps
+    ├── enterprise/          # Pure domain model — zero framework dependencies
     │   ├── entities/
     │   │   ├── entity.ts
     │   │   └── aggregate-root.ts
@@ -185,7 +233,7 @@ src/
     │       ├── domain-events.ts
     │       └── event-handler.ts
     │
-    └── application/        # Use cases & repository contracts
+    └── application/         # Orchestration — use cases & repository contracts
         ├── use-cases/
         │   ├── use-case.ts
         │   └── use-case.error.ts
@@ -199,8 +247,30 @@ src/
 
 ---
 
+## Agent Skills
+
+Archstone ships with a built-in skill for AI coding agents — giving them full knowledge of DDD conventions, layer boundaries, and usage patterns so you don't have to explain them in every project.
+
+**Install with Claude Code:**
+
+```bash
+bun x skills add joao-coimbra/archstone
+```
+
+**Or copy from the installed package:**
+
+```bash
+cp -r node_modules/archstone/skills/archstone .claude/skills/
+```
+
+The skill covers: entities, aggregates, value objects, use cases, repository contracts, domain events, Either error handling, and testing patterns — all with examples and common-mistake callouts.
+
+---
+
 <div align="center">
 
+**Built with care for the TypeScript community.**
+
 [Contributing](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · [MIT License](./LICENSE)
 
 </div>

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "archstone",
   "description": "TypeScript architecture foundation for backend services based on Domain-Driven Design and Clean Architecture",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "type": "module",
   "private": false,
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -73,11 +74,10 @@
     "build": "bunup",
     "dev": "bunup --watch",
     "test": "bun test",
-    "lint": "biome check src/",
-    "prepublishOnly": "bun run build",
     "check": "ultracite check",
     "fix": "ultracite fix",
-    "prepare": "husky || true"
+    "prepublishOnly": "bun run build",
+    "prepare": "bunx husky"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.5",

package/skills/archstone/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: archstone
+description: 'Apply Archstone DDD and Clean Architecture conventions. Use when developers: (1) Create domain entities, aggregates, or value objects, (2) Write application use cases, (3) Define repository contracts, (4) Work with domain events or event handlers, (5) Ask about Either, UniqueEntityId, WatchedList, or UseCaseError. Triggers on: "entity", "aggregate", "value object", "use case", "repository", "domain event", "Either", "UniqueEntityId", "archstone".'
+---
+
+## Critical: Follow Archstone Conventions
+
+Everything you know about DDD patterns may differ from how Archstone implements them. Always follow the rules below — do not apply generic DDD patterns that contradict them.
+
+When working with Archstone:
+
+1. Check `node_modules/archstone/` for the installed version
+2. All entities must extend `Entity<Props>` or `AggregateRoot<Props>` — never use plain classes
+3. All value objects must extend `ValueObject<Props>`
+4. Use cases must implement `UseCase<Input, Output>` and **never throw** — always return `Either`
+5. Repository contracts are interfaces only — implementations belong in infrastructure
+6. Domain events are raised inside aggregates and dispatched after persistence — never before
+7. Use `UniqueEntityId` for all entity identifiers — never a plain `string`
+8. The left side of `Either` must `implement UseCaseError` — not `extend Error`
+
+If you are unsure about a pattern, check [Conventions Reference](references/conventions.md) before writing code.
+
+## Layer Boundaries
+
+Always respect the layer rules. Never place infrastructure code in `domain/`, and never import concrete implementations into use cases.
+
+See [Layer Rules](references/layers.md) for details.
+
+## Entities & Aggregates
+
+Use a static `create()` factory. Pass `id` as the second constructor argument. Use `Optional<T, K>` for auto-generated fields. See [Entity Patterns](references/entity.md).
+
+## Value Objects
+
+Use a static `create()` factory with validation. Value object `create()` may throw — wrap calls inside use cases with `try/catch` and return `left()`. See [Value Object Patterns](references/value-object.md).
+
+## Use Cases
+
+Implement `UseCase<Input, Output>`. Return `left()` for errors, `right()` for success. Error classes must `implement UseCaseError`. See [Use Case Patterns](references/use-case.md).
+
+## Repository Contracts
+
+Define as interfaces only. Use `Repository<T>` or compose `Findable`, `Creatable`, `Saveable`, `Deletable`. Note: `findById` takes `string` — pass `entity.id.toValue()`. See [Repository Patterns](references/repository.md).
+
+## Domain Events
+
+Raise inside the aggregate via `addDomainEvent()`. Dispatch after persistence via `DomainEvents.dispatchEventsForAggregate(aggregate.id)`. Define handlers as classes implementing `EventHandler`. See [Domain Event Patterns](references/domain-events.md).
+
+## Testing
+
+Use `bun:test`. Co-locate test files as `*.spec.ts`. Use in-memory repository implementations. See [Testing Patterns](references/testing.md).
+
+## References
+
+- [Conventions](references/conventions.md) — quick rules summary
+- [Imports](references/imports.md) — import paths for all exports
+- [Layers](references/layers.md) — layer boundary rules
+- [Entity Patterns](references/entity.md) — Entity and AggregateRoot examples
+- [Value Object Patterns](references/value-object.md) — ValueObject examples
+- [Use Case Patterns](references/use-case.md) — UseCase and Either examples
+- [Repository Patterns](references/repository.md) — repository interface and in-memory examples
+- [Domain Event Patterns](references/domain-events.md) — EventHandler and dispatch examples
+- [Testing Patterns](references/testing.md) — bun:test and in-memory repo examples

package/skills/archstone/references/conventions.md

@@ -0,0 +1,23 @@
+# Archstone Conventions — Quick Reference
+
+## Always
+
+- Extend `Entity<Props>` or `AggregateRoot<Props>` for domain entities
+- Extend `ValueObject<Props>` for value objects
+- Use `UniqueEntityId` for all entity identities — never `string`
+- Use static `create()` factory — never instantiate directly
+- Return `Either<UseCaseError, Value>` from use cases — never throw
+- Define repositories as interfaces only
+- Raise domain events inside aggregates via `addDomainEvent()`
+- Dispatch domain events **after** persistence
+
+## Never
+
+- Never throw inside a use case — use `left()`
+- Never use `extends Error` for use case errors — use `implements UseCaseError`
+- Never place repository implementations in `domain/`
+- Never import concrete classes into use cases
+- Never dispatch domain events before persistence
+- Never call `clearEvents()` manually — `dispatchEventsForAggregate` handles it
+- Never pass `UniqueEntityId` to `findById()` — it takes `string`; use `.toValue()`
+- Never use `===` to compare value objects — use `.equals()`

package/skills/archstone/references/domain-events.md

@@ -0,0 +1,78 @@
+# Domain Event Patterns
+
+## Rules
+
+- Raise events inside the aggregate via `this.addDomainEvent()`
+- Dispatch **after** successful persistence — never before
+- Define handlers as classes implementing `EventHandler` with `setupSubscriptions(): void`
+- Register handlers in the infrastructure composition root before the first request
+- Dispatch via `DomainEvents.dispatchEventsForAggregate(aggregate.id)` — argument is `UniqueEntityId`
+- `clearEvents()` is called internally by `dispatchEventsForAggregate` — do not call manually
+- Test isolation: call `DomainEvents.clearHandlers()` and `DomainEvents.clearMarkedAggregates()` in `beforeEach`
+
+## Raising Events (inside aggregate)
+
+```ts
+class User extends AggregateRoot<UserProps> {
+  static create(props: Optional<UserProps, 'createdAt'>, id?: UniqueEntityId): User {
+    const user = new User(
+      { ...props, createdAt: props.createdAt ?? new Date() },
+      id ?? new UniqueEntityId(),
+    )
+    user.addDomainEvent(new UserCreatedEvent(user))
+    return user
+  }
+}
+```
+
+## Defining a Handler
+
+```ts
+import type { EventHandler } from 'archstone/domain/enterprise'
+import { DomainEvents } from 'archstone/domain/enterprise'
+
+class OnUserCreated implements EventHandler {
+  constructor(private readonly mailer: Mailer) {}
+
+  setupSubscriptions(): void {
+    DomainEvents.register(
+      (event) => this.handle(event as UserCreatedEvent),
+      UserCreatedEvent.name,
+    )
+  }
+
+  private async handle(event: UserCreatedEvent): Promise<void> {
+    await this.mailer.send(event.user.email.value)
+  }
+}
+```
+
+## Dispatching (in repository, after persistence)
+
+```ts
+async create(user: User): Promise<void> {
+  await this.db.insert(user)
+  DomainEvents.dispatchEventsForAggregate(user.id) // UniqueEntityId, not string
+}
+```
+
+## Composition Root Registration
+
+```ts
+// Called once at app startup — in infrastructure, never in domain
+new OnUserCreated(mailer).setupSubscriptions()
+```
+
+## Common Mistakes
+
+```ts
+// ❌ dispatching before persisting
+DomainEvents.dispatchEventsForAggregate(user.id)
+await this.db.insert(user) // wrong order
+
+// ❌ passing string
+DomainEvents.dispatchEventsForAggregate(user.id.toValue()) // use UniqueEntityId
+
+// ❌ calling clearEvents() manually
+user.clearEvents() // dispatchEventsForAggregate handles this
+```

package/skills/archstone/references/entity.md

@@ -0,0 +1,75 @@
+# Entity & AggregateRoot Patterns
+
+## Rules
+
+- Extend `Entity<Props>` for identity-only entities
+- Extend `AggregateRoot<Props>` for entities that raise domain events
+- Always use a static `create()` factory — constructor stays `protected`
+- Include `id` as an optional field in `Props` and pass it as the second constructor argument
+- Use `Optional<T, K>` for auto-generated fields (e.g. `'id' | 'createdAt'`)
+- Use `UniqueEntityId` — never a plain `string`
+
+## Entity Example
+
+```ts
+import { Entity } from 'archstone/domain/enterprise'
+import { UniqueEntityId, type Optional } from 'archstone/core'
+
+interface ProductProps {
+  name: string
+  price: number
+  createdAt: Date
+}
+
+class Product extends Entity<ProductProps> {
+  get name()  { return this.props.name }
+  get price() { return this.props.price }
+
+  static create(props: Optional<ProductProps, 'createdAt'>, id?: UniqueEntityId): Product {
+    return new Product(
+      { ...props, createdAt: props.createdAt ?? new Date() },
+      id ?? new UniqueEntityId(),
+    )
+  }
+}
+```
+
+## AggregateRoot Example
+
+```ts
+import { AggregateRoot } from 'archstone/domain/enterprise'
+import { UniqueEntityId, type Optional } from 'archstone/core'
+
+interface OrderProps {
+  customerId: UniqueEntityId
+  total: number
+  createdAt: Date
+}
+
+class Order extends AggregateRoot<OrderProps> {
+  get customerId() { return this.props.customerId }
+  get total()      { return this.props.total }
+
+  static create(props: Optional<OrderProps, 'createdAt'>, id?: UniqueEntityId): Order {
+    const order = new Order(
+      { ...props, createdAt: props.createdAt ?? new Date() },
+      id ?? new UniqueEntityId(),
+    )
+    order.addDomainEvent(new OrderCreatedEvent(order))
+    return order
+  }
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ plain class
+class Order { id: string }
+
+// ❌ id not passed as second constructor arg
+return new Order(props) // id goes as second arg: new Order(props, id)
+
+// ❌ string id
+interface OrderProps { id: string } // use UniqueEntityId
+```

package/skills/archstone/references/imports.md

@@ -0,0 +1,13 @@
+# Archstone Import Reference
+
+| What | Import path |
+|---|---|
+| `Either`, `left`, `right` | `archstone/core` |
+| `ValueObject` | `archstone/core` |
+| `UniqueEntityId` | `archstone/core` |
+| `WatchedList` | `archstone/core` |
+| `Optional` | `archstone/core` |
+| `Entity`, `AggregateRoot` | `archstone/domain/enterprise` |
+| `DomainEvents`, `EventHandler` | `archstone/domain/enterprise` |
+| `UseCase`, `UseCaseError` | `archstone/domain/application` |
+| `Repository`, `Findable`, `Creatable`, `Saveable`, `Deletable` | `archstone/domain/application` |

package/skills/archstone/references/layers.md

@@ -0,0 +1,34 @@
+# Layer Rules
+
+## core/
+
+Zero domain knowledge. Contains only pure language utilities.
+
+Exports: `Either`, `left`, `right`, `ValueObject`, `UniqueEntityId`, `WatchedList`, `Optional`
+
+## domain/enterprise/
+
+Pure domain model. No framework or infrastructure dependencies.
+
+Contains: entities, aggregates, value objects, domain events, event handlers.
+
+## domain/application/
+
+Orchestration layer. Use cases and repository contracts only.
+
+Contains: use case interfaces, use case error contracts, repository interfaces.
+
+## Infrastructure (outside domain/)
+
+Database adapters, HTTP handlers, ORMs, email services — all live here.
+
+Repository implementations belong here, not in `domain/`.
+
+## Rule
+
+```
+core/ ← no deps
+domain/enterprise/ ← imports from core/ only
+domain/application/ ← imports from core/ and domain/enterprise/
+infrastructure/ ← imports from all layers, implements domain/application/ contracts
+```

package/skills/archstone/references/repository.md

@@ -0,0 +1,65 @@
+# Repository Patterns
+
+## Rules
+
+- Contracts are **interfaces only** — never place implementations in `domain/`
+- Extend `Repository<T>` for full CRUD, or compose granular interfaces:
+  - `Findable<T>` — `findById(id: string)` — takes `string`, not `UniqueEntityId`
+  - `Creatable<T>` — `create(entity: T)`
+  - `Saveable<T>` — `save(entity: T)`
+  - `Deletable<T>` — `delete(entity: T)` — takes full entity, not an id
+- Import via barrel: `archstone/domain/application`
+- Implementations belong in infrastructure
+- Inject as the **interface type** in use cases
+
+## Contract Example
+
+```ts
+import type { Repository, Creatable } from 'archstone/domain/application'
+
+// Full CRUD + custom method
+export interface UserRepository extends Repository<User> {
+  findByEmail(email: string): Promise<User | null>
+}
+
+// Compose only what you need
+export interface AuditRepository extends Creatable<AuditLog> {}
+```
+
+## In-Memory Implementation (for tests)
+
+```ts
+export class InMemoryUserRepository implements UserRepository {
+  public items: User[] = []
+
+  async findById(id: string) {
+    return this.items.find(u => u.id.toValue() === id) ?? null
+  }
+
+  async findByEmail(email: string) {
+    return this.items.find(u => u.email.value === email) ?? null
+  }
+
+  async create(user: User)  { this.items.push(user) }
+
+  async save(user: User) {
+    const i = this.items.findIndex(u => u.id.equals(user.id))
+    if (i >= 0) this.items[i] = user
+  }
+
+  async delete(user: User) {
+    this.items = this.items.filter(u => !u.id.equals(user.id))
+  }
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ concrete class in use case
+constructor(private repo: PrismaUserRepository) {}
+
+// ❌ UniqueEntityId to findById
+await repo.findById(user.id)           // wrong
+await repo.findById(user.id.toValue()) // correct
+```

package/skills/archstone/references/testing.md

@@ -0,0 +1,50 @@
+# Testing Patterns
+
+## Rules
+
+- Use `bun:test` — import `test`, `expect`, `beforeEach` from `bun:test`
+- Test files: `*.spec.ts` co-located with the source file they test
+- Use in-memory repository implementations for use case tests — never mock databases
+
+## Use Case Test Example
+
+```ts
+import { test, expect, beforeEach } from 'bun:test'
+import { GetUserUseCase } from './get-user'
+import { InMemoryUserRepository } from '@/test/repositories/in-memory-user-repository'
+
+let repo: InMemoryUserRepository
+let useCase: GetUserUseCase
+
+beforeEach(() => {
+  repo = new InMemoryUserRepository()
+  useCase = new GetUserUseCase(repo)
+})
+
+test('returns user when found', async () => {
+  const user = User.create({ name: 'João' })
+  await repo.create(user)
+
+  const result = await useCase.execute({ userId: user.id.toValue() })
+
+  expect(result.isRight()).toBe(true)
+  expect(result.value).toEqual(user)
+})
+
+test('returns error when user not found', async () => {
+  const result = await useCase.execute({ userId: 'non-existent' })
+
+  expect(result.isLeft()).toBe(true)
+})
+```
+
+## Domain Event Isolation
+
+```ts
+import { DomainEvents } from 'archstone/domain/enterprise'
+
+beforeEach(() => {
+  DomainEvents.clearHandlers()
+  DomainEvents.clearMarkedAggregates()
+})
+```

package/skills/archstone/references/use-case.md

@@ -0,0 +1,59 @@
+# UseCase + Either Patterns
+
+## Rules
+
+- Implement `UseCase<Input, Output>`
+- Output is always `Either<UseCaseError, Value>` — **never throw**
+- Error classes must `implement UseCaseError` (requires `message: string`) — not `extends Error`
+- Wrap value object construction in `try/catch` and return `left()`
+- Inject repositories via constructor typed as the **interface**
+
+## Example
+
+```ts
+import type { UseCase, UseCaseError } from 'archstone/domain/application'
+import { Either, left, right } from 'archstone/core'
+
+class UserNotFoundError implements UseCaseError {
+  message = 'User not found.'
+}
+
+class InvalidEmailError implements UseCaseError {
+  message = 'Invalid email address.'
+}
+
+type Input  = { userId: string; newEmail: string }
+type Output = Either<UserNotFoundError | InvalidEmailError, User>
+
+class UpdateUserEmailUseCase implements UseCase<Input, Output> {
+  constructor(private readonly repo: UserRepository) {} // interface, not concrete
+
+  async execute({ userId, newEmail }: Input): Promise<Output> {
+    const user = await this.repo.findById(userId)
+    if (!user) return left(new UserNotFoundError())
+
+    try {
+      const email = Email.create(newEmail)
+      user.updateEmail(email)
+    } catch {
+      return left(new InvalidEmailError())
+    }
+
+    await this.repo.save(user)
+    return right(user)
+  }
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ extends Error
+class UserNotFoundError extends Error {} // implement UseCaseError instead
+
+// ❌ throwing
+if (!user) throw new Error('not found') // return left(new UserNotFoundError())
+
+// ❌ concrete repo
+constructor(private repo: PrismaUserRepository) {} // use the interface
+```

package/skills/archstone/references/value-object.md

@@ -0,0 +1,57 @@
+# ValueObject Patterns
+
+## Rules
+
+- Extend `ValueObject<Props>`
+- Static `create()` factory with validation — may throw on invalid input (intentional)
+- Never mutate `this.props` — return a new instance instead
+- Compare with `.equals()` — never `===`
+
+## Example
+
+```ts
+import { ValueObject } from 'archstone/core'
+
+interface EmailProps { value: string }
+
+class Email extends ValueObject<EmailProps> {
+  get value() { return this.props.value }
+
+  static create(raw: string): Email {
+    if (!raw.includes('@')) throw new Error('Invalid email address')
+    return new Email({ value: raw.toLowerCase().trim() })
+  }
+
+  withDomain(domain: string): Email {
+    const [local] = this.props.value.split('@')
+    return new Email({ value: `${local}@${domain}` })
+  }
+}
+
+const a = Email.create('user@example.com')
+const b = Email.create('user@example.com')
+a.equals(b) // true
+```
+
+## Handling throws in use cases
+
+Since `create()` may throw, wrap it inside use cases:
+
+```ts
+try {
+  const email = Email.create(rawEmail)
+  user.updateEmail(email)
+} catch {
+  return left(new InvalidEmailError())
+}
+```
+
+## Common Mistakes
+
+```ts
+// ❌ comparing with ===
+if (user.email === other.email) {} // use .equals()
+
+// ❌ mutating props
+this.props.value = newValue // return new Email({ value: newValue })
+```