Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (69 loc) · 4.11 KB

AGENTS.md

File metadata and controls

91 lines (69 loc) · 4.11 KB
Raw

Agent guidance

Guidance for AI agents (Claude Code, Copilot, Cursor, etc.) working in this repository. See CONTRIBUTING.md for the full contributor workflow.

Committing

Run the pre-commit hook before committing (pre-commit run --all-files, or let it run on staged files via git commit). Fix any issues it reports so the commit lands clean — CI runs the same checks.

Local development shortcuts

Use just for common tasks; run just --list for grouped recipes.

  • just ensure — install/check prerequisites
  • just run-ios / just run-android — build/run mobile apps
  • just dev / just dev-mobile — start the omnigent dev pod
  • just electron-dev / just electron-build — Electron desktop shell
  • just lint / just lint-all — run pre-commit
  • just normalize-locks — rewrite lockfile registries to PyPI/npmjs.org

Pull requests

When you open a pull request, fill in the repo's PR template at .github/pull_request_template.md (case-sensitive on Linux — note the lowercase filename). Keep every section and checkbox row so reviewers can skim them.

  • Summary — what changed and why.
  • Test Plan — how you verified it.
  • Demo — a video or images showing the change. Expected on contributor PRs for UI / frontend changes (check the "UI / frontend change" box under Type of change) so reviewers can see the new behaviour without checking out the branch. Use N/A for non-visual changes.
  • Type of change / Test coverage — check all that apply (at least one each).
  • Coverage notes — required if you checked "Manual verification completed" or "Not applicable".

Generate the description from the actual diff and this session's context — lead with the motivation, then the change. Don't pass a --body that skips these sections.

Finishing a task

When you finish a task, print instructions to the user on how to test it: the commands to run, the inputs to provide, or the steps to reproduce so they can verify the result themselves. Don't leave the user guessing how to confirm the work — tell them exactly what to do.

Deprecating features

When deprecating a feature, note the version in which it is expected to be removed so we can clean it up when that version ships. Call out the deprecation version in code (e.g. a @deprecated tag or comment naming the target release) and in the PR/commit description, so there's a clear marker to act on later.

Code comments

Keep comments short and focused on the code, not on the change history.

  • Keep them brief — prefer one or two lines. Avoid comments longer than three lines; if you need more, the code likely needs refactoring or a doc string, not a wall of inline commentary.
  • Describe the scenario, not the PR — explain what the code handles or why it exists, in terms a future reader needs. Don't reference PR numbers, issue numbers, or ticket IDs (e.g. #1646, fixes JIRA-123); the scenario should be clear without chasing external links.

Database query names

Application stores use make_named_managed_session_maker and give every session a stable semantic operation name. The session-level name must describe the caller's intent rather than repeat SQL syntax; use a nested query_name_scope only when one transaction needs distinct names for important subqueries. Because the named session covers implicit flush and commit, don't add an explicit flush() only to make a query name observable.

Framework-owned instructions

Keep runtime lifecycle and metadata instructions separate from portable agent instructions:

  • Agent-spec and per-request instructions are user-authored. Framework-owned instructions are additive runtime behavior and are appended after them in omnigent/runtime/prompt.py.
  • Keep the canonical instruction text and lifecycle gate in the owning framework module. Harness adapters should only transport the composed instructions; do not duplicate policy across adapters or add lifecycle metadata to AgentSpec.
  • If framework instructions grow beyond a small ordered list, introduce a structured FrameworkInstructions value at the prompt-composition boundary.