tws: Instructions file for Claude Code

AGENTS.md

This file provides guidance to agents working in this repository.

Build & Test

cargo build                    # compile
cargo test                     # run the full test suite
cargo test state::tests        # run tests in a specific module
cargo test resolve_selection   # run tests matching a name pattern

CI

.github/workflows/ci.yml runs on every PR and every push to main. Five jobs, all required to pass:

cargo test   --all-targets --locked                   # Test
cargo fmt    --all --check                            # Rustfmt — formatting
cargo clippy --all-targets --locked -- -D warnings    # Clippy — lints as errors
cargo audit                                           # Security audit — RustSec advisories
bash scripts/verify-agent-hooks.sh                    # Agent hook protocol — see below

Run cargo fmt --all and cargo clippy --all-targets -- -D warnings before pushing. CI pins the toolchain to Rust 1.96.1 (see RUST_VERSION in ci.yml); rustfmt reflows and clippy lints shift between releases, so format/lint with a matching toolchain to avoid CI turning red on formatting alone.

Workflow

Every change — even a tiny one — happens in a fresh git worktree on a new branch, then goes out as a PR. Never edit and commit directly on main in the primary checkout.

git worktree add ../tws-<slug> -b <branch> origin/main
cd ../tws-<slug>
# ...edit, commit, push, gh pr create

This keeps in-flight work isolated from main, and ensures every change is reviewable on GitHub before it lands.

Release

Patch/minor/major bumps follow semver.

1. Land fix/feature commits on main (merge any feature worktrees in first — do not bump versions inside a feature branch/worktree, it causes Cargo.lock conflicts on merge).
2. In the primary main checkout, bump version in both Cargo.toml and Cargo.lock (the [[package]] name = "tws" entry) in a separate commit titled version bump to vX.Y.Z.
3. Lightweight tag at the bump commit: git tag vX.Y.Z. Push both: git push origin main && git push origin vX.Y.Z.