runa/AGENTS.md

Project Guidelines

Project overview

Runa (short for Rune Actors) is an experimental Rust project whose long-term goal is a persistent, live programming world built around isolated Rune actors. The current workspace contains Rune 0.14.2 feasibility experiments and a minimal single-worker actor runtime. Verified capabilities and unresolved limitations are in docs/rune-feasibility.md and docs/runtime.md.

The architecture, design goals, constraints, and implementation roadmap are documented in docs/architecture.md. Treat proposed capabilities as plans, not existing behavior.

Agent rules

• Remove placeholders that do not apply. For project details you cannot determine reliably, ask the user rather than guessing; if they are unavailable, leave the placeholders clearly marked.
• Never push changes unless explicitly told to.
• After changing files, run the project's formatter using its configured settings. Do not override project formatting configuration or invoke a formatter directly on individual files unless project guidance says to.
• Use conventional commits with the types used by this project. Use ! and a BREAKING CHANGE: footer for breaking API or behavior changes.
• End commit messages with a co-author trailer appropriate to the agent and product. For example: Co-Authored-By: <AGENT_NAME> <AGENT_EMAIL>.
• Inform the user about commits and other Git changes, including commit messages.
• Commit changes after each step unless the user says not to or a project no-commit marker such as .NOCOMMIT exists in the repository root.
  • Changes affecting compilation or tests may only be committed after the relevant build, lint, and test checks pass.
  • Documentation, CI, editor, and deployment configuration changes may not require code checks; follow the project's validation requirements.
  • Check the current branch before every commit.
• Commit formatting-only changes separately when formatting reformats code unrelated to the functional changes.
• Add user-visible changes to the project's Unreleased changelog section using its established format, creating that section if needed.

Architecture and constraints

• Keep actor identity, mailbox, private state, behavior implementation, and incarnation distinct as runtime work begins.
• Use message passing for normal actor interaction; do not introduce shared mutable actor state.
• Keep behavior implementations immutable and install updates at safe boundaries. Do not mutate active execution frames in place.
• Start with the Rune feasibility work in Phase 0. Verify APIs and capabilities against the actual Rune version before relying on them; do not claim interruption, preemption, durability, or delivery guarantees without tests.
• Build only the smallest workspace structure needed for the current milestone; the crate layout in the spec is proposed, not a requirement to create empty crates.

Repository structure

• Cargo.toml: Rust workspace definition.
• crates/runa/: current executable crate and entry point.
• crates/runa-rune/: Phase 0 Rune compilation and execution experiments.
• crates/runa-actor/: actor value and lifecycle contracts.
• crates/runa-runtime/: single-worker scheduling and in-memory transitions.
• runa-std/actors/: default Rune actor scripts loaded by the local CLI.
• docs/architecture.md: architecture, roadmap, risks, and acceptance scenario.
• docs/decisions/: architectural decisions.
• runa-std/: default Rune scripts for an image.
• scripts/: general-purpose development automation.
• tests/: system and end-to-end tests; require an explicit runner rather than assuming Cargo discovers tests at a virtual workspace root.
• examples/ and vscode/: reserved for examples and the VS Code extension.
• README.md: project overview and current getting-started instructions.

Commands

Run these from the repository root:

mise run format
mise run lint
mise run test
mise run pre-commit

mise run pre-commit runs format, lint, and test sequentially, stopping on failure. Formatting uses the repository's Tombi and rustfmt configurations. Clippy checks all workspace targets and treats warnings as errors.

The workspace tests cover execution probes, actor runtime invariants, and the interactive CLI. cargo run -p runa opens the local CLI.

Conventions

• Keep changes focused and follow existing Rust formatting and workspace conventions.
• Prefer verified Rune APIs and explicit runtime guarantees over assumptions.
• Keep the README and architecture spec aligned with implemented behavior; label planned capabilities as planned.
• Do not push changes unless explicitly asked.
• Check the current branch before committing. Use conventional commit messages and include the repository's configured Copilot co-author trailer.
• Add user-visible changes to the project's Unreleased changelog section using its established format before you commit something, creating that section if needed.
• Before every commit, including documentation-only commits, run mise run pre-commit and require a successful exit. Fix all reported formatting, lint, and test problems, then rerun the task until it passes. Do not bypass checks or suppress diagnostics merely to make a commit pass.
• Review and stage formatter changes before committing. If further changes are made after validation, rerun mise run pre-commit before committing.