Skip to content

AGENTS.md

Latest commit

 

History

History
189 lines (139 loc) · 8.64 KB

AGENTS.md

File metadata and controls

189 lines (139 loc) · 8.64 KB

AGENTS.md

Build & Test Commands

  • Build: bun run build
  • Test: bun run test or bun test
  • Single Test: bun test <filename-glob> (e.g. bun test agent-fallback.test.ts)
  • Watch Mode: bun test --watch
  • Lint: bun run lint (eslint)
  • Typecheck: bun run typecheck (tsc --noEmit)
  • Fix Lint: bun run lint:fix (eslint --fix)
  • Format: bun run format (prettier)
  • E2E: OMA_E2E=true bun test ./test/e2e/oma-workflow.e2e.ts
  • Web Server: oma serve (starts web UI, default port 32023)
  • Web Server (custom): oma serve --port 8080 --host 0.0.0.0
  • Web Build: cd packages/web && bun run build
  • Web Tests: bun test test/web/

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)

Project Context

  • Type: ES Module package for Bun modules
  • Target: Bun runtime, ES2021+
  • Purpose: Independent agentic coding runtime
  • Kernel: packages/kernel/src/ — all core infrastructure
  • Web: packages/web/ — Hono + React SPA web interface (server + client + shared contracts)
    • Server: Hono HTTP/WebSocket/SSE, JWT auth, RuntimeManager
    • Client: React 19, Zustand, react-markdown, Shiki, Tailwind CSS
  • Storage: repo-local .oma/ for project artifacts; XDG state for sessions/tasks/memory

Agent Hierarchy

OMA uses a three-layer primitive/lead/worker hierarchy. All agents are registered in src/agents/helper/catalog.ts and enforced by the RoutingService in the kernel.

Layer: Primitive (2 agents)

Primitives are the entry points for user-facing commands and the top of the delegation chain.

Agent File Description
cto src/agents/primitive/executive.ts Strategic orchestrator. Routes commands to leads and workers. Owns background tasks and governance.
brainstorm src/agents/primitive/brainstorm.ts Meta-prompt specialist. Surfaces contradictions, patterns, risks, and options before committing to implementation.

Layer: Lead (8 agents)

Leads coordinate clusters of workers within a domain. They receive task bundles from cto and delegate to workers. Leads do not write code or mutate state directly.

Agent File Domain
planner src/agents/lead/catalog.ts Plan creation, validation, and advisory orchestration
coder src/agents/lead/catalog.ts Code implementation coordination
tester src/agents/lead/catalog.ts Test authoring and validation coordination
advisor src/agents/lead/catalog.ts Architecture and review advisory
qa src/agents/lead/catalog.ts Quality assurance coordination
quick src/agents/lead/catalog.ts Fast, bounded single-task execution
router src/agents/lead/catalog.ts Request routing and load balancing
reliability src/agents/lead/catalog.ts End-to-end assurance and coverage

Layer: Worker (20 agents)

Workers are execution units. They implement bounded tasks, produce artifacts, and report completion or blockers. Workers do not re-delegate.

Coder Workers (6) — src/agents/worker/coder.ts

Agent Description
coder-backend Backend and infrastructure implementation
coder-frontend Frontend and UI implementation
coder-security Security-focused implementation
coder-junior Junior-level or small scoped tasks
coder-deepagent Deep reasoning and complex multi-file implementation
coder-qa QA-focused implementation and test authoring

Explorer Workers (2) — src/agents/worker/explorer.ts

Agent Description
explorer Repo investigation and cross-file analysis
librarian External research and documentation lookup

Workflow Workers (12) — src/agents/worker/workflow.ts aggregator (src/agents/worker/workflow/*.ts)

Agent Description
debugger Root-cause analysis and targeted bug fixes
architect Architecture review and design guidance
build-resolver Build failure diagnosis and resolution
security-reviewer Security analysis and vulnerability assessment
e2e-runner End-to-end test execution
harness-optimizer Test harness improvement and optimization
writer Documentation, roadmap, and artifact writing
plan-advisor Plan quality review and improvement suggestions
plan-validator Implementation readiness validation for plans
reviewer Code and diff review
validator Unit and integration test authoring
gitmaster Git workflow, docs, release, and CI management

Routing Service

The RoutingService in packages/kernel/src/routing-service.ts enforces delegation rules deterministically:

  • cto may delegate to any lead or directly to selected workers.
  • Leads may delegate only to workers in their permission matrix.
  • Workers may not delegate further.
  • Cross-layer delegation that violates the permission matrix is rejected at runtime.

Each agent definition includes a permission.task map that declares which agent IDs it may invoke:

permission: {
  task: {
    '*': 'deny',
    'plan-advisor': 'allow',
    'plan-validator': 'allow',
  }
}

Storage Paths

OMA uses a two-tier storage split:

The web UI accesses the same .oma/ project artifacts and XDG state paths via RuntimeManager.

Repo-local .oma/ — project artifacts:

  • .oma/oma.jsonc — project config
  • .oma/plans/active.md, .oma/plans/active.json — active plan
  • .oma/roadmap/roadmap.md, .oma/roadmap/roadmap.json — roadmap
  • .oma/prompts/ — prompt artifacts

XDG state — runtime/app-owned per-project state:

  • $XDG_STATE_HOME/oma/projects/<project-id>/sessions/<session-id>/
  • $XDG_STATE_HOME/oma/projects/<project-id>/tasks/<id>.json
  • $XDG_STATE_HOME/oma/projects/<project-id>/memory/

Fallback base: ~/.local/state/oma/projects/<project-id>/.

Path constants are exported from packages/kernel/src/paths.ts and re-exported from packages/kernel/src/index.ts.