ordinus
AGENTS.md111 starsChanged 5 months agoMITView on GitHub
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. Ordinus must work on both macOS and Windows. When making changes, account for platform differences before finishing.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository12 other files it gives its agents.
- lavishSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- documentation-and-adrsSkill
- electron-secure-boundarySkill
- grill-meSkill
- idea-discoverySkill
- ipc-contract-designSkill
- ordinus-ui-systemSkill
- provider-runtime-adapterSkill
- shadcn-project-workflowSkill
- sqlite-minimal-persistenceSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
25 rules. About 0 are common, 16 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Keep the user in control of important actions.
- Distinctive: line 15
Prefer a small reliable workflow over broad unfinished features.
- Distinctive: line 16
Avoid integrations before the core runtime model is stable.
- Very specific: line 23
Never expose raw ipcRenderer, electron, filesystem, process, or database APIs to renderer code.
- Distinctive: line 28
Use SQLite for durable app state, but add tables only when the product model is clear.
- Very specific: line 29
Keep SQLite schema changes in Drizzle migrations under app/resources/db/migrations.
- Distinctive: line 30
Run migrations from the Electron main process before registering IPC handlers.
- Distinctive: line 32
Do not add agent, task, provider, schedule, or inbox schemas prematurely.
- Distinctive: line 38
Do not assume POSIX-only paths, shell commands, environment variable syntax, executable names, file permissions, or case-sensitive …
- Very specific: line 39
Use Node/Electron APIs such as path, os, and provider command executable + args arrays instead of shell-specific strings.
- Very specific: line 40
Consider Windows .cmd/.exe behavior, spaces in paths, CRLF/LF differences, and macOS/Linux case sensitivity.
- Distinctive: line 42
Prefer npm scripts and cross-platform tooling over shell-specific commands.
- Very specific: line 62
Run npm scripts from app/ unless a task explicitly targets repository-level docs or skills.
- Very specific: line 67
When a task touches Electron security, IPC, persistence, UI, shadcn components, or provider runtime, consult the matching project skill …
- Distinctive: line 68
Keep changes small and verifiable.
- Distinctive: line 70
Prefer typed IPC handlers and Zod validation in main/shared.
- Distinctive: line 71
Keep preload lightweight and sandbox-friendly.
- Distinctive: line 72
Avoid third-party runtime imports in preload unless there is a strong reason.
- Distinctive: line 73
Use shadcn/ui reusable components for UI primitives.
- Very specific: line 74
Prefer the shadcn CLI when adding registry components.
- Very specific: line 75
Keep components.json, tailwind.config.ts, TypeScript aliases, and component imports aligned.
- Distinctive: line 76
Do not introduce large product features until the foundation is stable.
- Very specific: line 77
Keep release builds signed.
- Distinctive: line 86
Use interface text that explains product state, not implementation details.
- Distinctive: line 90
Before finishing meaningful changes, run:
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.ordinusAPI. - Never expose raw
ipcRenderer,electron, filesystem, process, or database APIs to renderer code. - Provider runtime must follow
docs/provider-runtime-contract.mdbefore 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 commandexecutable + argsarrays instead of shell-specific strings. - Consider Windows
.cmd/.exebehavior, 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.
Current Stack
- Electron + electron-vite
- React + TypeScript
- Tailwind + shadcn/ui components
- Drizzle + better-sqlite3
- Zod for contracts and validation
- npm
Repository Layout
- Electron app code lives under
app/. - Product docs live under
docs/. - Project skills live under
.codex/skills/. - GitHub Actions workflows live under
.github/workflows/. - Issue templates live under
.github/ISSUE_TEMPLATE/. - Open-source contribution and security policy live in
CONTRIBUTING.mdandSECURITY.md. - Run npm scripts from
app/unless a task explicitly targets repository-level docs or skills. - Packaging and release rules live in
docs/packaging-release.md.
Implementation Rules
- When a task touches Electron security, IPC, persistence, UI, shadcn components, or provider runtime, consult the matching project skill under
.codex/skills. - Keep changes small and verifiable.
- Preserve the secure Electron boundary.
- Prefer typed IPC handlers and Zod validation in main/shared.
- Keep preload lightweight and sandbox-friendly.
- Avoid third-party runtime imports in preload unless there is a strong reason.
- Use shadcn/ui reusable components for UI primitives.
- Prefer the shadcn CLI when adding registry components. Run it from
app/. - Keep
components.json,tailwind.config.ts, TypeScript aliases, and component imports aligned. - Do not introduce large product features until the foundation is stable.
- Keep release builds signed. Local unsigned Windows workarounds must stay in explicit
*:localscripts.
UI Direction
DESIGN.mdis the canonical design system for renderer UI. When a task touches UI layout, styling, shadcn components, status surfaces, empty states, forms, task views, provider views, or user-facing product copy, readDESIGN.mdand align with it.- Ordinus should feel calm, practical, and work-focused.
- Avoid marketing-page layouts.
- Avoid decorative clutter.
- Prioritize clear status, readable history, and obvious next actions.
- Use interface text that explains product state, not implementation details.
Testing Expectations
Before finishing meaningful changes, run:
npm ciwhen dependency installation or CI behavior changesnpm run typechecknpm run lintnpm run build
For UI primitive or shadcn changes, also run:
npm run ui:infonpm run ui:check
For Electron, preload, database, or runtime changes, also smoke test:
npm run devor a packaged app when relevant.
Out of Scope for Now
- Cloud sync
- Hosted accounts
- Marketplace features
- Complex permissions
- Deep third-party integrations
- Premature multi-agent automation before single-agent workflows are solid
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

