ordinus AGENTS.md

Ordinus Agent Guide

Mission

Ordinus is a desktop workspace for coordinating AI agents around real software work. Keep the product simple, observable, local-first, and user-controlled.

Build a command center for AI-assisted work, not a generic chatbot.

Product Principles

• Make agent activity visible: planned, running, blocked, completed.
• Give agents clear roles and responsibilities.
• Help agents coordinate instead of running disconnected conversations.
• Keep the user in control of important actions.
• Prefer a small reliable workflow over broad unfinished features.
• Avoid integrations before the core runtime model is stable.

Architecture Direction

• Electron main process owns privileged work: filesystem, database, process execution, provider runtimes, and OS integration.
• Renderer is UI only. It must not access Node, filesystem, child processes, secrets, or SQLite directly.
• Preload exposes only a small typed window.ordinus API.
• Never expose raw ipcRenderer, electron, filesystem, process, or database APIs to renderer code.
• Provider runtime must follow docs/provider-runtime-contract.md before adding CLI detection or process spawning.
• Provider commands use executable plus args, not raw shell strings.
• Runtime environment is deny-by-default; secrets are referenced, resolved in main, and never logged.
• Shared contracts live in src/shared.
• Use SQLite for durable app state, but add tables only when the product model is clear.
• Keep SQLite schema changes in Drizzle migrations under app/resources/db/migrations.
• Run migrations from the Electron main process before registering IPC handlers.
• Track applied SQL through Drizzle and app-level schema version through app_meta.schema_version.
• Do not add agent, task, provider, schedule, or inbox schemas prematurely.

Cross-Platform Development

Ordinus must work on both macOS and Windows. When making changes, account for platform differences before finishing.

• Do not assume POSIX-only paths, shell commands, environment variable syntax, executable names, file permissions, or case-sensitive filesystems.
• Use Node/Electron APIs such as path, os, and provider command executable + args arrays instead of shell-specific strings.
• Consider Windows .cmd/.exe behavior, spaces in paths, CRLF/LF differences, and macOS/Linux case sensitivity.
• For changes touching filesystem access, process execution, packaging, provider runtimes, scripts, or native dependencies, verify or explain platform impact.
• Prefer npm scripts and cross-platform tooling over shell-specific commands.