Skip to content

AGENTS.md

Latest commit

 

History

History
115 lines (87 loc) · 3.9 KB

AGENTS.md

File metadata and controls

115 lines (87 loc) · 3.9 KB
  • To regenerate the JavaScript SDK, run ./packages/sdk/js/script/build.ts.
  • ALWAYS USE PARALLEL TOOLS WHEN APPLICABLE.
  • The default branch in this repo is dev.
  • Local main ref may not exist; use dev or origin/dev for diffs.
  • Prefer automation: execute requested actions without confirmation unless blocked by missing info or safety/irreversibility.

Git Sync And Merge Safety

  • When syncing with origin or upstream, preserve fork-specific behavior by default. Do not silently replace PRO/custom repo names, package names, release URLs, workflow wiring, branding, or fork-only features with upstream defaults unless the user explicitly asks for that.
  • Before non-trivial merges or rebases, create a local backup branch if git writes are allowed.
  • Fetch remotes explicitly and separately. Do not assume origin and upstream point to the same history or release setup.
  • Prefer merges over rebases for shared branch sync work unless the user explicitly asks for history rewriting.
  • Treat conflicts in fork-specific files as "local changes win" unless there is a strong reason to manually combine both sides.
  • For conflicted files that mix upstream fixes with local customizations, manually merge them so upstream bugfixes land without dropping local product behavior.
  • After merge resolution, run the most relevant typecheck/tests before pushing.
  • Do not delete, rename, or revert fork-specific features just to make an upstream sync easier. Escalate only if the upstream change genuinely conflicts with required local behavior.
  • If GitHub shows the fork is behind upstream, verify with local refs after git fetch upstream before making assumptions from the web UI banner alone.

Style Guide

General Principles

  • Keep things in one function unless composable or reusable
  • Avoid try/catch where possible
  • Avoid using the any type
  • Use Bun APIs when possible, like Bun.file()
  • Rely on type inference when possible; avoid explicit type annotations or interfaces unless necessary for exports or clarity
  • Prefer functional array methods (flatMap, filter, map) over for loops; use type guards on filter to maintain type inference downstream
  • In src/config, follow the existing self-export pattern at the top of the file (for example export * as ConfigAgent from "./agent") when adding a new config module.

Reduce total variable count by inlining when a value is only used once.

// Good
const journal = await Bun.file(path.join(dir, "journal.json")).json()

// Bad
const journalPath = path.join(dir, "journal.json")
const journal = await Bun.file(journalPath).json()

Destructuring

Avoid unnecessary destructuring. Use dot notation to preserve context.

// Good
obj.a
obj.b

// Bad
const { a, b } = obj

Variables

Prefer const over let. Use ternaries or early returns instead of reassignment.

// Good
const foo = condition ? 1 : 2

// Bad
let foo
if (condition) foo = 1
else foo = 2

Control Flow

Avoid else statements. Prefer early returns.

// Good
function foo() {
  if (condition) return 1
  return 2
}

// Bad
function foo() {
  if (condition) return 1
  else return 2
}

Schema Definitions (Drizzle)

Use snake_case for field names so column names don't need to be redefined as strings.

// Good
const table = sqliteTable("session", {
  id: text().primaryKey(),
  project_id: text().notNull(),
  created_at: integer().notNull(),
})

// Bad
const table = sqliteTable("session", {
  id: text("id").primaryKey(),
  projectID: text("project_id").notNull(),
  createdAt: integer("created_at").notNull(),
})

Testing

  • Avoid mocks as much as possible
  • 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.

Type Checking

  • Always run bun typecheck from package directories (e.g., packages/opencode), never tsc directly.