open-conclave: Instructions file for Codex

AGENTS.md

Build & Test Commands

• Build: mise run build or bun build ./src/index.ts --outdir dist --target bun
• Test: mise run test or bun test
• Single Test: bun test BackgroundTask.test.ts (use file glob pattern)
• Watch Mode: bun test --watch
• Lint: mise run lint (eslint)
• Fix Lint: mise run lint:fix (eslint --fix)
• Format: mise run format (prettier)

Code Style Guidelines

Imports & Module System

• Use ES6 import/export syntax (module: "ESNext", type: "module")
• Group imports: external libraries first, then internal modules
• Use explicit file extensions (.ts) for internal imports

Formatting (Prettier)

• Single quotes (singleQuote: true)
• Line width: 100 characters
• Tab width: 2 spaces
• Trailing commas: ES5 (no trailing commas in function parameters)
• Semicolons: enabled

TypeScript & Naming

• NeverNesters: avoid deeply nested structures. Always exit early.
• Strict mode: enforced ("strict": true)
• Classes: PascalCase (e.g., BackgroundTask, BackgroundTaskManager)
• Methods/properties: camelCase
• Status strings: use union types (e.g., 'pending' | 'running' | 'completed' | 'failed' | 'cancelled')
• Explicit types: prefer explicit type annotations over inference
• Return types: optional (not required but recommended for public methods)

Error Handling

• Check error type before accessing error properties: error instanceof Error ? error.toString() : String(error)
• Log errors with [ERROR] prefix for consistency
• Always provide error context when recording output

Linting Rules

• @typescript-eslint/no-explicit-any: warn (avoid any type)
• no-console: error (minimize console logs)
• prettier/prettier: error (formatting violations are errors)

Testing

• Framework: vitest with describe & it blocks
• Style: Descriptive nested test cases with clear expectations
• Assertion library: expect() (vitest)