aster: Instructions file for Codex

Aster

Rust workspace, edition 2024, stable toolchain. Crates live in crates/ and are prefixed aster- (the exception is symbol-extractor). The crates/aster-cli crate is the binary; everything else is a library.

Human-facing setup and PR etiquette live in CONTRIBUTING.md. This file is the working agreement for agents editing this repo.

Global rules

• No useless comments in code.
• Match the project's existing style and patterns before writing anything new.
• No em dashes (—) in any writing.
• Never add Co-Authored-By: Claude/Cursor trailers to commits or PRs, and strip them if found.
• Use Conventional Commits for every message.

User-facing copy

Every string a user sees (TUI cells, panel cards, error boxes, status lines) is written in plain, relatable language, never harness vocabulary. "Turns", "verdict", "judge", "budget exhausted", "rate limited", "context window" are internal words; users get "tries", "check", "too many requests", "stopped after 20 tries". Errors always say what happened and what to do next in one plain sentence, with the raw provider detail demoted below. Protocol field names, config keys, env vars, and docs stay technical; only rendered copy is covered by this rule.

Rust conventions

• Read the crate you are touching and follow its existing patterns before introducing a new one.
• The rust-best-practices, rust-review, and rust-port skills live locally in .aster/skills/ (gitignored, never shipped) and cover general Rust idiom. Where they disagree with this file, this file wins.
• Inline variables into format! braces: format!("{name}"), not format!("{}", name).
• Collapse nested if statements.
• Prefer method references over closures: .map(str::trim), not .map(|s| s.trim()).
• Avoid bare bool and ambiguous Option parameters that force callers to write foo(false) or bar(None). Prefer enums, newtypes, or named methods so the callsite reads on its own. aster_policy::Mode and PermissionModeArg are the shape to copy.
• Make match statements exhaustive. Avoid wildcard arms over enums we own, so adding a variant produces a compile error instead of silent fallthrough.
• New traits get a doc comment explaining their role and what implementors are expected to do. McpInvoker in crates/aster-mcp/src/lib.rs is the example.
• Prefer private modules with an explicit pub crate API. Keep the exported surface as small as the callers need.
• Do not create helper functions that are called exactly once.
• Keep the core dependency-light. No vector DB, no external services in the review path. A new heavy dependency needs a written justification in the PR.