agentleFS
muratgurmuratgur/ordinus/AGENTS.md

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.

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
  1. Distinctive:

    Keep the user in control of important actions.

    line 14
  2. Distinctive:

    Prefer a small reliable workflow over broad unfinished features.

    line 15
  3. Distinctive:

    Avoid integrations before the core runtime model is stable.

    line 16
  4. Very specific:

    Never expose raw ipcRenderer, electron, filesystem, process, or database APIs to renderer code.

    line 23
  5. Distinctive:

    Use SQLite for durable app state, but add tables only when the product model is clear.

    line 28
  6. Very specific:

    Keep SQLite schema changes in Drizzle migrations under app/resources/db/migrations.

    line 29
  7. Distinctive:

    Run migrations from the Electron main process before registering IPC handlers.

    line 30
  8. Distinctive:

    Do not add agent, task, provider, schedule, or inbox schemas prematurely.

    line 32
  9. Distinctive:

    Do not assume POSIX-only paths, shell commands, environment variable syntax, executable names, file permissions, or case-sensitive …

    line 38
  10. Very specific:

    Use Node/Electron APIs such as path, os, and provider command executable + args arrays instead of shell-specific strings.

    line 39
  11. Very specific:

    Consider Windows .cmd/.exe behavior, spaces in paths, CRLF/LF differences, and macOS/Linux case sensitivity.

    line 40
  12. Distinctive:

    Prefer npm scripts and cross-platform tooling over shell-specific commands.

    line 42
  13. Very specific:

    Run npm scripts from app/ unless a task explicitly targets repository-level docs or skills.

    line 62
  14. Very specific:

    When a task touches Electron security, IPC, persistence, UI, shadcn components, or provider runtime, consult the matching project skill …

    line 67
  15. Distinctive:

    Keep changes small and verifiable.

    line 68
  16. Distinctive:

    Prefer typed IPC handlers and Zod validation in main/shared.

    line 70
  17. Distinctive:

    Keep preload lightweight and sandbox-friendly.

    line 71
  18. Distinctive:

    Avoid third-party runtime imports in preload unless there is a strong reason.

    line 72
  19. Distinctive:

    Use shadcn/ui reusable components for UI primitives.

    line 73
  20. Very specific:

    Prefer the shadcn CLI when adding registry components.

    line 74
  21. Very specific:

    Keep components.json, tailwind.config.ts, TypeScript aliases, and component imports aligned.

    line 75
  22. Distinctive:

    Do not introduce large product features until the foundation is stable.

    line 76
  23. Very specific:

    Keep release builds signed.

    line 77
  24. Distinctive:

    Use interface text that explains product state, not implementation details.

    line 86
  25. Distinctive:

    Before finishing meaningful changes, run:

    line 90

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
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.

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.md and SECURITY.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 *:local scripts.

UI Direction

  • DESIGN.md is 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, read DESIGN.md and 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 ci when dependency installation or CI behavior changes
  • npm run typecheck
  • npm run lint
  • npm run build

For UI primitive or shadcn changes, also run:

  • npm run ui:info
  • npm run ui:check

For Electron, preload, database, or runtime changes, also smoke test:

  • npm run dev or 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.