Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 4 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[submodule "effect"]
path = repos/effect
url = https://github.com/Effect-TS/effect.git
shallow = true
3 changes: 3 additions & 0 deletions .vscode/extensions.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"recommendations": ["VoidZero.vite-plus-extension-pack"]
}
33 changes: 33 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,41 @@
{
"editor.codeActionsOnSave": {
"source.fixAll.oxc": "explicit"
},
"editor.defaultFormatter": "oxc.oxc-vscode",
"editor.formatOnSave": true,
"editor.formatOnSaveMode": "file",
"explorer.fileNesting.enabled": true,
"explorer.fileNesting.expand": false,
"explorer.fileNesting.patterns": {
"*.ts": "${capture}.test.ts, ${capture}.spec.ts",
"*.tsx": "${capture}.test.tsx, ${capture}.spec.tsx"
},
"files.watcherExclude": {
"**/repos/**": true
},
"js/ts.preferences.autoImportFileExcludePatterns": ["${workspaceFolder}/repos/**"],
"npm.scriptRunner": "vp",
"oxc.fmt.configPath": "./vite.config.ts",
"oxc.lint.customization": {
"require-yield": {
"severity": "off"
}
},
"oxc.typeAware": true,
"search.exclude": {
"**/repos/**": true
},
"[javascript]": {
"editor.defaultFormatter": "oxc.oxc-vscode"
},
"[javascriptreact]": {
"editor.defaultFormatter": "oxc.oxc-vscode"
},
"[typescript]": {
"editor.defaultFormatter": "oxc.oxc-vscode"
},
"[typescriptreact]": {
"editor.defaultFormatter": "oxc.oxc-vscode"
}
}
22 changes: 20 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,24 @@
# AGENTS.md

- Never commit or push unless asked for.
- For custom code we write, prefer self-contained domain classes over floating functions.
- For scripts, use `Bun.file(...).text()` or `Bun.file(...).json()` and `Bun.write(...)` for file I/O instead of `node:fs/promises` `readFile` or `writeFile`.
- Put production behavior in `Context.Service`; do not add floating functions, classes, clients, factories, or singletons.
- For scripts, use `Bun.file(...).text()` or `Bun.file(...).json()` for reads.
- For script writes, use `Bun.write(...)`; reserve `node:fs/promises` for application adapters.
- Keep `./src/agents/instructions.ts`, the README.md "Agent?" section, and this file's instructions block in sync when editing any of them.

## Effect reference

- Run `vp run effect:reference` when `repos/effect/LLMS.md` is missing before writing Effect code.
- Read `repos/effect/LLMS.md`, then use `repos/effect` as read-only reference material.
- Import Effect from package dependencies; never import application code from `repos/effect`.
- Import Effect APIs as named imports from `effect`; do not use deep Effect imports.
- Keep private pure helpers as local const arrows inside a service `make`.
- Keep private effectful helpers as named `Effect.fn("Service.method")(function* (...) {})` values.
- Return public operations from the service `make` as a readonly object using `as const`.
- Keep `ConfigService` APIs data-only; move callable behavior to a capability or platform service.
- Export production layers with descriptive names ending in `Layer`; close internal dependencies in the layer graph.
- Model recoverable operational failures with `Schema.TaggedErrorClass` names ending in `Error`.
- Use `Effect.acquireRelease`, scoped layers, retries, and schedules at the reliability seams that need them.
- Keep `Effect.run*` and `ManagedRuntime` calls at approved application, script, or compatibility boundaries.
- Keep existing focused libraries behind Effect service adapters instead of replacing them.
- Do not create barrel files; import from the module that owns each symbol.
114 changes: 66 additions & 48 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@ src/
providers/
tooling/
utils/
define.ts
```

Each domain may contain these layers:
Expand All @@ -29,9 +28,8 @@ Each domain may contain these layers:
types -> config -> repo -> service -> runtime -> ui
```

Only create a layer directory when the domain has code for it. Every domain exposes a
deliberate public API from `index.ts`. Cross-domain and app imports use that API instead of
importing domain internals.
Only create a layer directory when the domain has code for it. Every service and type is exported
from the concrete module that owns it. Cross-domain and app imports name that module directly.

## Domain ownership

Expand Down Expand Up @@ -63,76 +61,96 @@ Top-level responsibilities:
| `providers` | Domain-independent process, filesystem, clock, environment, and terminal access |
| `utils` | Pure domain-independent code with at least two real consumers |
| `tooling` | Architecture enforcement and development tooling |
| `define.ts` | Construction vocabulary for behavior-bearing layers and app roots |

External data is parsed at `repo`, `runtime`, or `app` boundaries before it enters domain
behavior. Keep Rig's public SDK Promise-based and Zod-based while internal architecture moves.

## Domain dependency graph

Domain edges are explicit and acyclic. A domain may depend only on the domains declared here:

| Domain | Allowed domain dependencies |
| ------------- | ------------------------------------- |
| `collections` | none |
| `registry` | `settings` |
| `scheduling` | `settings`, `tools` |
| `settings` | none |
| `tools` | `collections`, `registry`, `settings` |
| `updates` | `settings` |

Across an allowed domain edge, code imports only `types`, `service`, or `runtime` contracts at
the same or an earlier layer. Config and repository implementations remain private to their
owning domain. The architecture model rejects undeclared edges even when they would be acyclic.

## Effect v4 reliability harness

Rig keeps its existing libraries and uses Effect v4 as the internal orchestration harness. Effect
owns dependency composition, typed operational failures, resource lifetimes, cancellation,
retries, schedules, and tracing. Commander, Ink, Zod, Bun SQLite, and other focused libraries stay
in place behind Effect services when they already solve their responsibility well.

- Model capabilities with `Context.Service`; use stable `@rendotdev/rig/...` service identities.
- Export production implementations with descriptive camel-case names ending in `Layer`.
- Name alternatives `testLayer`, `bunLayer`, `sqliteLayer`, or another role-specific `Layer` name.
- Model recoverable operational failures with `Schema.TaggedErrorClass` and an `Error` suffix.
- Use `Schema.Class` and branded schemas for domain entities and value objects when migrating them.
- Use `Effect.acquireRelease`, `Layer.scoped`, or `Scope` for every owned closeable resource.
- Capture service dependencies while constructing the layer; service methods do not leak them.
- Run Effects at application or compatibility boundaries; do not call `Effect.run*` inside Effects.
- Adapt existing Promise and Zod APIs at the boundary instead of forcing downstream tools to move.
- Retry only transient, idempotent operations; cap attempts and use an explicit `Schedule` policy.
- Preserve the final failure cause when retries are exhausted and record retry attempts in spans.
- Keep private pure transformations as local const arrows inside their owning service `make`.
- Keep React rendering and the public Zod SDK compatible while services own their supporting behavior.

The pinned Effect source lives under `repos/effect` as a shallow, read-only git submodule. Run
`vp run effect:reference` when it is missing from a fresh checkout. Production code imports the
installed `effect` packages, never files under `repos/effect`. Agents should read the referenced
`LLMS.md`, patterns, source, and tests before relying on remembered APIs.

## Dependency rules

Within a domain, a layer may import itself and the layers listed below:

| Source | Allowed targets |
| --------- | ------------------------------------------------------------------- |
| `types` | `types`, `utils` |
| `config` | `types`, `config`, `utils` |
| `repo` | `types`, `config`, `repo`, `providers`, `utils` |
| `service` | `types`, `config`, `repo`, `service`, `providers`, `utils` |
| `runtime` | `types`, `config`, `service`, `runtime`, `providers`, `utils` |
| `ui` | `types`, `config`, `service`, `runtime`, `ui`, `providers`, `utils` |
| Source | Allowed targets |
| --------- | ------------------------------------------------------------- |
| `types` | `types`, `utils` |
| `config` | `types`, `config`, `utils` |
| `repo` | `types`, `config`, `repo`, `providers`, `utils` |
| `service` | `types`, `config`, `repo`, `service`, `providers`, `utils` |
| `runtime` | `types`, `config`, `service`, `runtime`, `providers`, `utils` |
| `ui` | `types`, `config`, `service`, `runtime`, `ui`, `utils` |

Additional rules:

- Cross-domain imports use `domains/<domain>/index.ts` or a deliberate layer `index.ts`.
- `app` imports domain public APIs, providers, utilities, and `define.ts`.
- Providers import only providers, utilities, `define.ts`, and external packages.
- Import cross-domain symbols from the module that owns them; barrel files are forbidden.
- `app` imports domain types, services, runtimes, UI, providers, and utilities.
- Close config and repo dependencies inside exported domain layers before app wiring consumes them.
- Providers import only providers, utilities, and external packages.
- Utilities import only utilities and external packages.
- Tooling imports only tooling, utilities, and external packages.
- Domains and providers never import `app`.
- Production code never imports `tooling`.
- Migrated code cannot import a legacy source root.
- Legacy code may import migrated public APIs while its vertical is being moved.
- Domain `repo`, `service`, and `runtime` layers may use Providers; types, config, and UI may not.
- Every production module must classify under this model; there is no legacy source escape hatch.

`src/tooling/architecture/architecture.ts` is the executable source of truth. Custom Oxlint
rules and structural tests consume the same model.

## Definition vocabulary

Use helpers that match the owning architectural layer:

- `defineRepo` in `repo`.
- `defineService` in `service`.
- `defineRuntime` in `runtime`.
- `defineProvider` in `providers`.
- `defineUIComponent` and `defineUIHook` in `ui`.
- `defineApp` at executable app roots.
- `defineSingleton` for intentional shared behavior with stable `params` and `deps`.
- `defineType`, `defineConfig`, and `defineUtil` for named data-only definitions.
- Plain TypeScript for type-only declarations.

Repository, service, runtime, and provider definitions are classes that extend their matching
helper. Replace `params` and `deps` through the constructor in deterministic tests. Singleton,
component, hook, and app definitions keep their implementation inline in the definition object.

## Migration sequence

Rig currently has legacy roots listed in the shared architecture model. They are temporary,
explicit migration allowances rather than permanent exceptions.
## Mechanical enforcement

1. Move one business capability into `domains/<domain>/<layer>`.
2. Add the domain or layer public `index.ts`.
3. Update outside consumers to use the public API.
4. Replace legacy construction with the owning layer helper and direct class implementation.
5. Remove the migrated legacy root or narrow its allowance.
6. Run `vp run ci` before moving the next high-risk runtime seam.
- `src/tooling/architecture/architecture.ts` owns the layer and domain matrices.
- Oxlint rejects invalid source locations and dependency edges with concrete remediation.
- Structural tests parse every production import with the TypeScript AST and validate the real graph.
- CI runs architecture lint, structural tests, Effect diagnostics, dead-code analysis, and behavior tests.
- Human review feedback becomes a documented invariant or a mechanical rule when it can recur.

## Taste invariants

- Production files contain at most 400 meaningful lines.
- Test files contain at most 600 meaningful lines.
- Functions and methods contain at most 80 meaningful lines.
- Blank and comment-only lines do not count toward these limits.
- Existing oversized files use exact migration ceilings and cannot grow.
- Migration ceilings shrink or disappear as each file is split.
- Split by responsibility and layer; avoid generic helper buckets.
- Assign compound `if` conditions to descriptive boolean constants.
- Boundary diagnostics include concrete remediation for the next agent run.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Do not implement anything yet. Ask the user which workflow they want to implemen

## Agent?

<!-- Keep in sync with src/agents/instructions.ts -->
<!-- Keep in sync with src/domains/tools/config/agent-instructions.ts -->

> Are you an AI agent looking for how to use rig? Assume the following:

Expand Down
Loading