Development and testing

This page is for contributors making changes to caretta code or workflow assets.

Local development loop

Build quickly in debug mode.
Run targeted tests while iterating.
Run workspace-wide checks before opening a PR.

Build and run commands

# Build all crates
cargo build

# Run CLI help
cargo run -- --help

# Launch desktop app
cargo run -- gui

Test commands

# Full workspace tests
cargo test --workspace

# Targeted iteration example
cargo test agent::tracker::tests::

Quality gates

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Treat clippy warnings as errors.

Hook and smoke utilities

# Install local hooks that mirror CI checks
./scripts/setup-hooks.sh

# Run smoke coverage for install/CLI surfaces
./scripts/smoke-test.sh

Test placement and naming

Prefer inline unit tests near the logic under test (#[cfg(test)]).
Use descriptive snake_case test names.
Add coverage for parser changes, workflow prompt generation, and command construction paths.

Commit and PR expectations

Keep commits focused and imperative.
In PR descriptions, summarize user-visible change and list verification commands run.
Include screenshots or short recordings when changing UI behavior.

Documentation update policy

When changing workflows, command behavior, or adapter semantics, update both:

Project README/docs where needed.
Writerside topics in this directory for structured product documentation.

Last modified: 02 July 2026