From d7b805acda8e17c2a42dc27f14d3b721c7d0f6a0 Mon Sep 17 00:00:00 2001 From: Steve Biedermann Date: Sun, 1 Nov 2026 19:39:44 +0100 Subject: [PATCH] docs: add project agent guidelines Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..12f8737 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,61 @@ +# 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 is a minimal Rust executable; Rune integration and the +actor runtime are not implemented yet. + +The architecture, design goals, constraints, and implementation roadmap are +documented in [runa-spec-architecture.md](runa-spec-architecture.md). Treat +proposed capabilities as plans, not existing behavior. + +## 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. +- `runa-spec-architecture.md`: architecture, roadmap, risks, and acceptance + scenario. +- `README.md`: project overview and current getting-started instructions. + +## Commands + +Run these from the repository root: + +```sh +cargo fmt --all -- --check +cargo check --workspace +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace +``` + +The current project is a minimal executable and may not yet have tests. + +## 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. +- Run relevant formatting, build, lint, and test checks before committing code + changes. Documentation-only changes do not require code checks.