From e57a1c793030363c9c484347169922a0c92bbb68 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Fri, 14 Aug 2026 23:25:47 -0400 Subject: [PATCH] docs: refresh agent guidance --- .opencode/command/ai-deps.md | 2 +- .opencode/command/commit.md | 10 +--------- .opencode/command/rmslop.md | 2 +- .opencode/skills/effect/SKILL.md | 14 +++++++------- AGENTS.md | 10 +++++----- packages/ai/AGENTS.md | 9 ++------- packages/app/AGENTS.md | 2 +- packages/cli/AGENTS.md | 7 ++----- packages/schema/AGENTS.md | 2 +- packages/www/AGENTS.md | 2 +- 10 files changed, 22 insertions(+), 38 deletions(-) diff --git a/.opencode/command/ai-deps.md b/.opencode/command/ai-deps.md index 83783d5b9b..5a50c22749 100644 --- a/.opencode/command/ai-deps.md +++ b/.opencode/command/ai-deps.md @@ -2,7 +2,7 @@ description: "Bump AI sdk dependencies minor / patch versions only" --- -Please read @package.json and @packages/opencode/package.json. +Please read @package.json and @packages/core/package.json. Your job is to look into AI SDK dependencies, figure out if they have versions that can be upgraded (minor or patch versions ONLY no major ignore major changes). diff --git a/.opencode/command/commit.md b/.opencode/command/commit.md index e88932a244..6d5c21e6ef 100644 --- a/.opencode/command/commit.md +++ b/.opencode/command/commit.md @@ -6,15 +6,7 @@ subtask: true commit and push -make sure it includes a prefix like -docs: -tui: -core: -ci: -ignore: -wip: - -For anything in the packages/web use the docs: prefix. +Use `type(scope): summary` with one of these types: `feat`, `fix`, `docs`, `chore`, `refactor`, or `test`. The scope is optional. prefer to explain WHY something was done from an end user perspective instead of WHAT was done. diff --git a/.opencode/command/rmslop.md b/.opencode/command/rmslop.md index 02c9fc0844..25374d070f 100644 --- a/.opencode/command/rmslop.md +++ b/.opencode/command/rmslop.md @@ -2,7 +2,7 @@ description: Remove AI code slop --- -Check the diff against dev, and remove all AI generated slop introduced in this branch. +Check the diff against `origin/v2`, and remove all AI generated slop introduced in this branch. This includes: diff --git a/.opencode/skills/effect/SKILL.md b/.opencode/skills/effect/SKILL.md index 3a44fa88dc..e93be2aba2 100644 --- a/.opencode/skills/effect/SKILL.md +++ b/.opencode/skills/effect/SKILL.md @@ -1,6 +1,6 @@ --- name: effect -description: Work with Effect v4 / effect-smol TypeScript code in this repo +description: Work with Effect v4 TypeScript code in this repo --- # Effect @@ -9,10 +9,10 @@ This codebase uses Effect for typed, composable TypeScript services, schemas, an ## Source Of Truth -Use the current Effect v4 / effect-smol source, not memory or older Effect v2/v3 examples. +Use the current Effect v4 source, not memory or older Effect v2/v3 examples. -1. If `.opencode/references/effect-smol` is missing, clone `https://github.com/Effect-TS/effect-smol` there. Do this in the project, not in the skill folder. -2. Search `.opencode/references/effect-smol` for exact APIs, examples, tests, and naming patterns before answering or implementing Effect-specific code. +1. If `.opencode/references/effect` is missing, clone `https://github.com/Effect-TS/effect` there. Do this in the project, not in the skill folder. +2. Search `.opencode/references/effect` for exact APIs, examples, tests, and naming patterns before answering or implementing Effect-specific code. 3. Also inspect existing repo code for local house style before introducing new patterns. 4. Prefer answers and implementations backed by specific source files or nearby repo examples. @@ -27,12 +27,12 @@ Use the current Effect v4 / effect-smol source, not memory or older Effect v2/v3 - Keep layer composition explicit. Avoid broad hidden provisioning that makes missing dependencies hard to see. - In tests, prefer the repo's existing Effect test helpers and live tests for filesystem, git, child process, locks, or timing behavior. - Do not introduce `any`, non-null assertions, unchecked casts, or older Effect APIs just to satisfy types. -- Do not answer from memory. Verify against `.opencode/references/effect-smol` or nearby code first. +- Do not answer from memory. Verify against `.opencode/references/effect` or nearby code first. ## Testing Patterns -- Use `testEffect(...)` from `packages/opencode/test/lib/effect.ts` for tests that exercise Effect services, layers, runtime context, scoped resources, or platform integrations. +- Use `testEffect(...)` from `packages/core/test/lib/effect.ts` for tests that exercise Effect services, layers, runtime context, scoped resources, or platform integrations. - Use `it.live(...)` for filesystem, git repositories, HTTP servers, sockets, child processes, locks, real time, and other live platform behavior. -- Run tests from package directories such as `packages/opencode`; never run package tests from the repo root. +- Run tests from package directories such as `packages/core`; never run package tests from the repo root. - Prefer explicit test layers over ad hoc managed runtimes. Keep dependency provisioning visible in the test file. - Use scoped fixtures and finalizers for resources that must be cleaned up, including temporary directories, flags, databases, fibers, servers, and global state. diff --git a/AGENTS.md b/AGENTS.md index 587ae8be52..583ca5a902 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ -- After changing the public Protocol or Server `HttpApi`, run `bun run generate` from `packages/client`. Do not edit `src/generated` or `src/generated-effect` directly. +- After changing the public Protocol or Server `HttpApi`, run `bun run generate` from `packages/client`. Do not edit generated client files directly. - Keep runtime dependencies directed from Schema to Core and Protocol, then from Core and Protocol to Server. Client runtime code may depend on Schema and Protocol but never Core or Server; `sdk-next` composes Client, Core, and Server. -- Do not modify `packages/opencode` unless the user explicitly asks for V1 work. `packages/opencode` is the V1 implementation and is present for reference only. New implementation changes should land in the V2 package set: `packages/core`, `packages/cli`, `packages/server`, `packages/protocol`, `packages/schema`, and related generated client surfaces when required. +- Current implementation changes belong in `packages/core`, `packages/cli`, `packages/server`, `packages/protocol`, `packages/schema`, and related generated client surfaces when required. - The default branch in this repo is `v2`. - Base all new branches and worktrees on `v2`, or `origin/v2` when the local `v2` ref is unavailable. Do not base them on `dev`. - Local `main` ref may not exist; use `v2` or `origin/v2` for diffs. @@ -166,11 +166,11 @@ const table = sqliteTable("session", { - Avoid mocks as much as possible, you shouldn't be using globalThis.\* at all unless it's the only option. - Test actual implementation, do not duplicate logic into tests -- Tests cannot run from repo root (guard: `do-not-run-tests-from-root`); run from package dirs like `packages/opencode`. +- Tests cannot run from repo root (guard: `do-not-run-tests-from-root`); run from package directories such as `packages/core`. ## Type Checking -- Always run `bun typecheck` from package directories (e.g., `packages/opencode`), never `tsc` directly. +- Always run `bun typecheck` from package directories (for example, `packages/core`), never `tsc` directly. ## V2 Session Core @@ -179,7 +179,7 @@ const table = sqliteTable("session", { - Reusing a Session ID adopts the existing Session. While a user or synthetic inbox item is pending, reusing its ID reconciles only when Session, type, complete payload, metadata, and delivery match; conflicting reuse fails. Once delivered, retry reconciliation for those message-producing items uses the projected message and does not require retained enqueue history or the original delivery mode. Control items keep their operation-specific conflict behavior. - Keep `SessionExecution` process-global and Session-ID based. Its local implementation owns the process-local Session coordinator and discovers placement through `SessionStore` plus `LocationServiceMap.get(session.location)` only when a drain starts; no layer should take a Session ID. V2 interruption targets the active process-local ownership chain for that Session; interruption of a known but idle or locally unowned Session is a no-op, while the public API rejects an unknown Session. - Keep `SessionRunner`, model resolution, tool registry, permissions, and filesystem Location-scoped. Omitted `Location.workspaceID` means implicit-local placement; explicit workspace identity remains reserved for future placement semantics. -- Preserve one explicit `llm.stream(request)` call per Physical Attempt and reload projected history before durable continuation. A logical Step may use generic pre-output retries, one full-context retry after continuation rejection, incomplete-stream continuation, or one overflow-compaction rebuild. Generic retries retain the logical step number and do not consume another agent-step allowance. Do not bridge through legacy `SessionPrompt.loop(...)` or delegate orchestration to an in-memory tool loop. +- Preserve one explicit `llm.stream(request)` call per Physical Attempt and reload projected history before durable continuation. A logical Step may use generic pre-output retries, one full-context retry after continuation rejection, incomplete-stream continuation, or one overflow-compaction rebuild. Generic retries retain the logical step number and do not consume another agent-step allowance. Do not delegate orchestration to an in-memory tool loop. - Keep local Session drains process-local until clustering is implemented. `SessionRunCoordinator` joins explicit same-Session resumes, coalesces prompt wakeups, and allows different Sessions to run concurrently. A write-ahead execution claim marks a process-local busy period for restart recovery: terminal completion, failure, or user interruption releases it, while shutdown interruption and process death preserve it. Startup recovery resumes claimed top-level Sessions with durable per-execution attempt accounting. The claim is a recovery marker, not clustered ownership, fencing, or an exactly-once guarantee. - Keep delivery vocabulary explicit. Prompts steer by default. Steers deliver in enqueue order at safe step boundaries, stopping before compaction or move control items. At an idle boundary, steers take priority; otherwise exactly one queued item delivers before the runner reevaluates continuation. Inbox items may be cancelled or changed between queue and steer before delivery. Promoting new user input resets the selected agent's step allowance; a batch of steers resets it once. - One step is one logical LLM call; its durable record covers only the model-visible span. Do not write "provider turn", and do not use bare "turn" for a single call: "turn" is reserved for the future assistant-turn unit containing all steps from prompt promotion until the session would go idle. diff --git a/packages/ai/AGENTS.md b/packages/ai/AGENTS.md index a3dd39847f..4618b52087 100644 --- a/packages/ai/AGENTS.md +++ b/packages/ai/AGENTS.md @@ -23,14 +23,9 @@ Per-type constructors live on the type, not as top-level re-exports. Use `Messag This package is an Effect Schema-first LLM core. The Schema classes in `src/schema/` are the canonical runtime data model. Convenience functions in `src/llm.ts` are thin constructors that return those same Schema class instances; they should improve callsites without creating a second model. -Primary in-repo integration point: +Session integration lives in `packages/core/src/session`: `runner/llm.ts` owns orchestration, `model-request.ts` lowers Session state into `LLMRequest`, and `model-transport.ts` selects transport behavior. -- `packages/opencode/src/session/llm.ts` is the session-owned orchestration layer that decides whether a request uses AI SDK or this package's native route runtime. -- `packages/opencode/src/session/llm/native-request.ts` is the lowering adapter from opencode's session/AI SDK-shaped data into this package's `LLMRequest` model. -- `packages/opencode/src/session/llm/native-runtime.ts` is the execution adapter that calls raw `LLMClient.stream(request)` and bridges one provider turn of opencode tool calls through this package's typed dispatcher. -- `packages/opencode/src/session/llm/ai-sdk.ts` keeps the default AI SDK path compatible by converting AI SDK stream parts into this package's shared `LLMEvent`s. - -Keep this package independent of session concerns. Session auth, permissions, plugins, telemetry headers, and runtime selection belong in `packages/opencode/src/session/llm.ts` and its local adapters. +Keep this package independent of Session concerns. Session auth, permissions, plugins, telemetry headers, and runtime selection belong in Core. ### Request Flow diff --git a/packages/app/AGENTS.md b/packages/app/AGENTS.md index 58db295661..2af9fb558b 100644 --- a/packages/app/AGENTS.md +++ b/packages/app/AGENTS.md @@ -11,7 +11,7 @@ - `opencode dev web` proxies `https://app.opencode.ai`, so local UI/CSS changes will not show there. - For local UI changes, run the backend and app dev servers separately. -- Backend (from `packages/opencode`): `bun run --conditions=browser ./src/index.ts serve --port 4096` +- Backend (from the repository root): `bun dev serve --port 4096` - App (from `packages/app`): `bun dev -- --port 4444` - Open `http://localhost:4444` to verify UI changes (it targets the backend at `http://localhost:4096`). diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md index 73bebeb94f..2e00ca707b 100644 --- a/packages/cli/AGENTS.md +++ b/packages/cli/AGENTS.md @@ -1,7 +1,4 @@ -# V2 CLI and TUI development guide +# CLI and TUI development guide -## Migration context - -- The TUI is being ported from legacy APIs to the new V2 APIs. New and migrated TUI behavior should use `sdk.client.v2` and the location-scoped data in `packages/tui/src/context/data.tsx` instead of adding dependencies on legacy sync state. +- Use `@opencode-ai/client` and the location-scoped data in `packages/tui/src/context/data.tsx` instead of adding dependencies on legacy sync state. - Preserve established TUI behavior unless the task intentionally changes it. -- Load the `opencode-dev` skill before interactively running, debugging, or verifying opencode's V2 CLI, TUI, or server. diff --git a/packages/schema/AGENTS.md b/packages/schema/AGENTS.md index f079b42a26..29a79de39d 100644 --- a/packages/schema/AGENTS.md +++ b/packages/schema/AGENTS.md @@ -14,7 +14,7 @@ - Current contracts are unversioned: use names like `Session`, `Permission`, `Question`, and identifiers like `Permission.Request`. - Legacy contracts retained for active compatibility, persistence, or migration are explicitly `V1`: use names like `SessionV1`, `PermissionV1`, and identifiers like `PermissionV1.Request`. - Do not preserve `V2` as the permanent name for the replacement architecture. Remove `V2` from current namespaces, brands, and identifiers as the contracts are normalized. -- Retained V1 contracts should live under a dedicated `src/v1/` subtree once the V1 isolation PR runs. New/current code must not depend on that subtree. +- Retained V1 contracts live under `src/v1/`. New/current code must not depend on that subtree. - V1 coexistence is temporary. Keep compatibility entrypoints only where migration requires them, and delete the V1 subtree when the legacy runtime is retired. - `@opencode-ai/protocol` and `@opencode-ai/sdk-next` are current `/api/...` surfaces. diff --git a/packages/www/AGENTS.md b/packages/www/AGENTS.md index aecbd9cc1a..a5033c9d34 100644 --- a/packages/www/AGENTS.md +++ b/packages/www/AGENTS.md @@ -9,7 +9,7 @@ - Use parenthesized content folders for sidebar groups that must not add a URL segment. Keep ungrouped top-level pages directly under `content/docs/`. - Put static files in `public/` and reference them with root-relative paths. - The API reference is generated from `openapi.json`; do not duplicate endpoint documentation as hand-written MDX. -- Keep documentation aligned with the V2 packages. Do not use `packages/opencode` as the source of truth unless the task explicitly concerns V1. +- Keep documentation aligned with the current packages. ## Local development