Omnis
/

Repository Development Guidelines & Agent Rules

Omnis is developed by an autonomous agent pipeline under human approval gates. These rules are binding on every contributor — human or agent. They are enforced by CI, by branch protection, and by the tests in tests/.

1. Unit Tests with Every Commit

Every commit that adds or modifies code, classes, or methods must be accompanied by corresponding unit tests. Rust code is tested with cargo test, TypeScript with the workspace test runner, and repository automation (.github/scripts/) with pytest. All applicable suites must pass locally before committing or pushing.

2. Inline Docstrings & Autogenerated Documentation

All source must carry complete API documentation inline: - Rust: /// doc comments on every public item, with # Errors and # Panics sections where applicable. cargo doc must build with zero warnings. - TypeScript: TSDoc on every exported symbol. - Python (automation): Google-style docstrings (Args:, Returns:, Raises:) with PEP 484 type annotations.

Documentation is 100% autogenerated from source and hand-written architecture notes. No static per-module markdown mirrors and no manually maintained documentation index are stored in the repository. All documentation builds must succeed with properdocs build --strict — zero warnings, zero errors — and deploy automatically to GitHub Pages.

3. Architecture Conformance

The system architecture is defined by ARCHITECTURE.md, which is the single normative source for process topology, crate boundaries, IPC contracts, and renderer separation. notes/transcript.md is non-normative reference material captured from scoping conversations; it never overrides ARCHITECTURE.md. Any deviation from ARCHITECTURE.md must be explicitly approved by the user and recorded in notes/architecture_decisions.md as a numbered ADR before it is implemented.

4. Language Consistency

All code, identifiers, comments, docstrings, commit messages, issues, and documentation must be written in English.

5. Commit Granularity & Conventional Commits

Keep commits modular, focused, and descriptive — one commit per component or coherent change. All commits across all branches must strictly follow the Conventional Commits specification: <type>(<scope>): <description> (e.g. feat(core): add substrate bus frame codec).

6. CI Readiness & Verification

Every push must maintain green status on GitHub Actions across every job in ci.yml. A red build is treated as a stop-the-line event: no further feature work proceeds until it is green.

7. Branch & Pull Request Workflow

All changes, features, refactors, and bug fixes must be developed on dedicated topic branches and submitted through GitHub Pull Requests. Direct commits and pushes to main are strictly prohibited. - Branch Naming: Lowercase, hyphen-separated, descriptive (e.g. feature/substrate-bus-codec). Branch names must NEVER contain issue numbers. - Bot-Authored PRs: Pull requests must be authored by github-actions[bot] via .github/workflows/open-pr.yml (python3 .github/scripts/open_pr.py or gh workflow run open-pr.yml) so the repository maintainer is not registered as author and can natively review and approve them. - Draft Status: Every pull request must be opened in Draft (--draft) and remain in draft throughout development and review until explicitly approved. - Up-to-Date with Main: Every pull request branch must contain the latest main before merge (strict: true required status checks). - Required CI Checks: All required checks must pass green before merging. - Branch Protection: main must remain protected at all times with required status checks, branch up-to-date enforcement, and pull request review enforcement.

8. Automated Formatting & Linting

Formatting is not a review topic — it is automated. rustfmt for Rust, the workspace formatter for TypeScript, and black (line length 100) for Python automation. The GitHub Actions bot formats the codebase on every push across branches and commits any adjustments. Lints (cargo clippy -D warnings) are blocking.

9. Issue Binding, Branch Auto-Deletion & Project Board Taxonomy

  • Issue Binding: Every pull request must bind a tracked GitHub issue using closing keywords in the PR description (e.g. Closes #123, Fixes #123, Resolves #123).
  • Branch Auto-Deletion: Merging closes the bound issue and deletes the remote branch (delete_branch_on_merge: true and --delete-branch); the local branch must be pruned.
  • Project Board Status Taxonomy: All issues and pull requests are automatically added to the Omnis GitHub Project with automated status movements:
  • Backlog: Staged items planned for future consideration.
  • ToDo: Approved requests or plans ready for implementation.
  • In Progress: Active branches, pull requests, or ongoing development.
  • Blocked: Items impeded by external dependencies, blockers, or agent quota exhaustion.
  • Done: Completed and merged pull requests and resolved issues.
  • Superseded: Items rendered obsolete or outranked by subsequent architectural decisions.
  • Dropped: Items closed without implementation or cancelled.

10. Pre-Implementation Planning & Plan Review

Before implementation begins on any task, the implementation plan must be documented in a dedicated child issue with the Plan label, natively linked as a sub-issue of its parent Request issue (--parent <request_id>). The plan must detail objectives, architectural and code changes, and verification steps. - Implementation Review Gate: Prior to merging the bound pull request, an implementation review must be conducted and commented on the child Plan issue confirming the implementation matches the plan exactly (Matches Plan: Yes). - Plan Alignment: If the implementation diverged from the plan, an alignment comment (Plan Alignment:) detailing all deviations must be posted and explicitly approved before the pull request can be merged. CI enforces the presence of both the plan and the pre-merge review on all bound issues.

11. Pull Request Review Approval Enforcement & Auto-Merge

Pull requests require official GitHub review approval before merging. main protection requires at least 1 approving review (required_approving_review_count: 1) on the last commit (dismiss_stale_reviews: true), without blocking the last pusher (require_last_push_approval: false). - Native Approval: Because PRs are authored by github-actions[bot], the maintainer can select Approve in the GitHub UI, comment /approve, approve, lgtm, or run gh pr review <id> --approve. - Auto-Merge Activation: .github/workflows/pr-approval-automerge.yml and .github/scripts/handle_pr_approval.py listen for approvals from the maintainer, mark the draft PR ready (gh pr ready), submit proxy approval if required, and activate auto-merge with branch auto-deletion (gh pr merge --auto --merge --delete-branch). - Post-Merge Reconciliation: On merge, automation sets the project status of the PR and all bound issues to Done, applies the Done label, removes In Progress, and verifies bound issues are closed.

12. User Request Decomposition, Verbatim Prompting & Confirmation Gate

Every incoming user prompt or task must immediately be converted into one or more tracked GitHub issues labeled Request before any planning, branching, or code changes begin. - Issue Template: Use .github/ISSUE_TEMPLATE/request.yml for structured request filing. - Decomposition: A single user message containing multiple distinct tasks must be decomposed into multiple focused Request issues. - Verbatim Wording: Each Request issue body must contain the exact, verbatim wording of the user request. - Interpretation Section: Below the verbatim wording, each Request issue must include an ### Interpretation section specifying how the request is understood, the architectural scope, and the proposed verification. - Confirmation Gate: The interpretation requires explicit user confirmation (commenting approve) before any implementation plan is made. - Child Plan Issues: Once confirmed, a child issue with the Plan label is created and natively linked via GitHub sub-issues (--parent <request_id>) containing the detailed implementation plan. All subsequent branches and pull requests bind to the plan issue.

13. Specification Sequence & When Issues May Exist

Specification proceeds in one direction, and each stage is locked before the next begins:

notes/transcript.md  →  ARCHITECTURE.md  →  ADRs (notes/architecture_decisions.md)  →  ROADMAP.md  →  issues
  • An issue may only be filed for work that is settled. Settled means one of two things: an approved ADR resolving the decision the work depends on, or a concrete mechanical task whose outcome is not in question (for example, "create the Bun workspace and add these named dependencies").
  • Speculative epic and decision issues are prohibited. Filing an issue for an unanswered question moves the argument into the tracker, where it fragments across comment threads instead of converging in the document that owns it. Open questions live in ARCHITECTURE.md §8 until an ADR closes them; planned work lives in ROADMAP.md until its gate opens.
  • Large settled bodies of work are tracked as epic-labelled issues: a container carrying the scope statement, the acceptance criteria for the area, and a checklist of child Request issues. Epics are never implemented directly — only their children are.
  • ROADMAP.md is the authoritative list of epics and their sequencing, and is updated whenever an epic is added, split, completed, or dropped.

14. Harness-Agnostic Containerized Agent & Conversational CI Lifecycle

An autonomous AI agent runs containerized in GitHub Actions (docker/Dockerfile.agent). It is harness-agnostic: no pipeline code knows which coding-agent CLI is executing. - Harness registry: .github/scripts/harnesses.py declares each CLI — Antigravity (agy), Claude Code (claude), OpenAI Codex (codex), Kimi (kimi), Grok (grok), Cursor (cursor-agent), and opencode (opencode) — as a binary, an argv template, and a model chain. Adding a harness is a data change; changing one is a configuration change. - No hardcoded invocation: every field is overridable at runtime through the AGENT_HARNESS_CONFIG repository variable, and the order through AGENT_HARNESS_CHAIN, so an upstream flag rename never requires a code change or a container rebuild. - Graceful degradation: harnesses whose binary is absent from PATH, or whose credentials are unset, are skipped rather than failed. An image carrying four of seven CLIs is a working image with a shorter fallback chain. - Fallback across harnesses, not just models: quota exhaustion on one harness escalates to the next harness in the chain. Only when every harness and model is exhausted does the agent checkpoint and block. - Authentication: Provider credentials are supplied through repository secrets only. The runner performs a pre-flight token exchange on every run; no credentials are ever committed. - Auto-Detection & Interpretation: Incoming unlabelled issues are automatically tagged Request, classified with type and area labels, and answered with an interpretation comment. - Conversational Feedback Loop: The agent monitors comments on Request issues, Plan issues, and Pull Requests, responds to human feedback, and executes requested adjustments. Bot and agent comments are ignored to prevent self-reply loops. - Autonomous Implementation & Review: On plan approval (approve), the agent creates the branch, implements code and tests, opens a bot-authored Draft PR, and runs an autonomous review loop bounded by MAX_REVIEW_ITERATIONS. - Quota Exhaustion: On provider quota exhaustion the agent saves a checkpoint, moves the item to Blocked, comments the resume instructions, and exits cleanly. Commenting resume continues from the checkpoint.

15. Conventional Commits & Taxonomy Enforcement

  • Format: <type>(<scope>): <description> (e.g. feat(term): add cell matrix buffer).
  • Allowed Types: feat, fix (mapped from bug), chore, docs, refactor, test, ci.
  • Allowed Area Scopes & Labels:
  • area:core: Microkernel, process topology, IPC/substrate bus, daemon lifecycle, config.
  • area:ui: DOM renderer, layout topology, theming, profiles, settings surfaces.
  • area:term: Terminal cell-grid renderer, ANSI/TrueColor pipeline, PTY integration.
  • area:agents: Harness orchestration, provider adapters, personas, approvals.
  • area:browser: Embedded browser engine, CDP bridge, semantic and pixel render modes.
  • area:data: Schema, persistence, migrations, sync, local-first storage.
  • area:ext: Extension host, plugin API, compatibility shims.
  • area:ci: GitHub Actions workflows, containers, runner scripts, repository automation.
  • area:docs: Documentation, ProperDocs configuration, architecture notes.

16. Security & Secrets

No credential, token, refresh token, cookie, or private key is ever committed, echoed into workflow logs, or written into issue or PR bodies. All secrets live in GitHub repository secrets or the local OS keychain. Workflow logs must be assumed public.

Omnis