arbor: Instructions file for Claude Code

CLAUDE.md

This file provides instructions for Claude Code when working in this repository.

Priorities

1. Keep code simple, explicit, and maintainable.
2. Fix root causes, avoid temporary band-aids.
3. Preserve user changes, never revert unrelated edits.

Toolchain

This project uses a pinned Rust nightly toolchain: nightly-2025-11-30. All commands go through just recipes which apply the correct toolchain automatically.

Commands

• Format: just format
• Format check: just format-check
• Lint (clippy): just lint
• Test: just test
• Full CI suite: just ci
• Run app: just run
• Run HTTP daemon: just run-httpd

Before Committing / Pushing

Always run these checks before committing and fix any issues:

1. just format — auto-fix formatting
2. just lint — must pass with zero warnings (-D warnings)
3. just test — all tests must pass

If any check fails, fix the issue, then commit the fix. Never skip just format or just lint before a commit, even for small changes.

Git Workflow

Conventional commits: feat|fix|docs|style|refactor|test|chore(scope): description No Co-Authored-By trailers. Update README.md features list with feat commits.

Rust Rules

• Do not use unwrap() or expect() in non-test code. In test modules, use #[allow(clippy::unwrap_used, clippy::expect_used)] on the module.
• Use clear error handling with typed errors (thiserror/anyhow where appropriate).
• Use arbor_core::ResultExt and arbor_core::OptionExt for .context() on Result<T, E> and Option<T> — prefer these over ad-hoc .map_err() with format strings.
• Use SessionId and WorkspaceId newtypes from arbor_core::id instead of raw String for session/workspace identifiers. These are #[serde(transparent)] for wire compatibility.
• Keep modules focused and delete dead code instead of leaving it around.
• Collapse nested if / if let statements when possible (clippy collapsible_if).
• Never shell out to external CLIs (gh, git via Command::new, etc.) for GitHub API calls or operations that can be done with Rust crates. Use octocrab, reqwest, or other Rust HTTP/API crates instead. The only acceptable use of std::process::Command is where no Rust crate equivalent exists.