Engineering guide
Rust conventions for Castellan contributors. Guardrail enforcement lives in governance policies.
Toolchain
- Pin via
rust-toolchain.toml - Format:
cargo fmt --all - Lint:
cargo clippy --workspace --all-targets -- -D warnings
Verification
| Tier | Command |
|---|---|
| Iterate | ./scripts/verify.sh --fast |
| Before PR / CI | ./scripts/verify.sh (full) |
./scripts/verify.sh --fast
./scripts/verify.sh
castellan drift-check
Details: Verify before PR. Operators who only run Castellan day-to-day should follow Daily driver instead — that path uses castellan drift-check, not ./scripts/verify.sh.
Shared Cargo target (worktrees)
Optional helper for multiple worktrees:
source scripts/dev-env.sh # exports CARGO_TARGET_DIR to a shared directory
verify.sh defaults to $ROOT/target for isolation unless CARGO_TARGET_DIR is already set.
Crate boundaries
| Crate | Responsibility |
|---|---|
castellan-core | Types: Goal, EpisodeLog, topology |
castellan-runtime | Scheduler, engine, thin MCP host glue |
castellan-events | Unified observability schema |
castellan-cli | Operator surface |
castellan-multiplexer | PTY + socket API |
Docs
- Published book (
book/src/) is canonical for operators — castellan-docs.pages.dev docs/holds engineering specs; see docs/INDEX.md- Do not link raw GitHub
docs/blobs from book pages — use relative book links
Agent workflows
| Path | When |
|---|---|
| Frontier sprint | Backlog-driven BL delivery; Full vs Fast path + verify_tier |
| Prewalk | Multi-file work: frontier explores, capped todos, first edit, then cheap executor |