Change Recipes

Use these recipes to route changes through the correct modules without crossing layer boundaries.

Add or Modify a Session Workflow🔗

  1. Update orchestration in crates/agentty/src/app/session/ (lifecycle.rs, worker.rs, task.rs, etc.).
  2. Keep persistence in crates/agentty/src/infra/db/ domain modules and keep crates/agentty/src/infra/db.rs limited to pool wiring plus repository composition.
  3. Keep git operations behind GitClient in crates/agentty/src/infra/git/client.rs (re-exported from crates/agentty/src/infra/git.rs).
  4. Preserve the session-branch invariant: one evolving commit per session branch, with the first file-changing turn creating it and later file-changing turns updating it by amending HEAD.
  5. Update docs when lifecycle/status behavior changes: docs/site/content/docs/usage/workflow.md.

Add a New Agent Backend or Model🔗

  1. Update domain model declarations in crates/agentty/src/domain/agent.rs.
  2. Add backend behavior in crates/agentty/src/infra/agent/ and register it in provider.rs.
  3. If app-server-based, implement app_server_client() in the concrete backend so the provider owns its runtime wiring.
  4. Register any shared parsing, prompt-transport, streaming, or thought-policy changes in crates/agentty/src/infra/agent/provider.rs.
  5. The channel layer (infra/channel.rs) routes automatically based on the backend-owned transport mode - no change needed there unless the runtime contract itself changes.
  6. Update docs/site/content/docs/agents/backends.md with backend/model documentation.

Add a Keybinding or Mode Interaction🔗

  1. Update the handler in crates/agentty/src/runtime/mode/, or in crates/agentty/src/runtime/key_handler.rs when the interaction is a cross-mode overlay dispatch.
  2. If a new mode/state is needed, extend crates/agentty/src/ui/state/app_mode.rs.
  3. If help content changes, update crates/agentty/src/ui/state/help_action.rs as needed.
  4. Update docs/site/content/docs/usage/keybindings.md.

Add or Change Database Schema🔗

  1. Add a new migration file in crates/agentty/migrations/ (NNN_description.sql).
  2. Never modify existing migration files.
  3. Keep query changes in the matching crates/agentty/src/infra/db/*.rs domain module instead of expanding crates/agentty/src/infra/db.rs.
  4. Ensure any status/model behavior changes are reflected in docs pages affected by user-facing behavior.

Add a New UI Page or Component🔗

  1. Add the page in crates/agentty/src/ui/page/ or component in crates/agentty/src/ui/component/.
  2. Wire the page into crates/agentty/src/ui/router.rs.
  3. If a new AppMode is needed, extend crates/agentty/src/ui/state/app_mode.rs and add a key handler in crates/agentty/src/runtime/mode/.

Contributor Checklist for Architecture-Safe Changes🔗

  1. Keep workflow/state transitions in app/, not in UI rendering modules.
  2. Keep external integrations in infra/ behind traits.
  3. Keep business entities and enums in domain/.
  4. In app/ and runtime/ orchestration, avoid direct Command::new, Instant::now, SystemTime::now, and direct filesystem/process calls unless they run behind trait boundaries.
  5. For helpers that need timestamps in app/ or runtime/, reuse the shared app/session/core.rs Clock boundary instead of adding direct Instant::now() or SystemTime::now() calls.
  6. New external boundaries should get a trait with #[cfg_attr(test, mockall::automock)].
  7. Update docs in docs/site/content/docs/ whenever user-facing behavior changes.
  8. Update docs/site/content/docs/architecture/module-map.md, docs/site/content/docs/architecture/runtime-flow.md, and docs/site/content/docs/architecture/testability-boundaries.md when architecture responsibilities change.
  9. Keep the nearest semantic AGENTS.md guides aligned when a major module's purpose, invariants, or change-routing guidance changes.
  10. Treat render-time helpers as hot paths: avoid per-frame cloning of large render inputs, and make line-count/layout helpers reuse the same cached derived data as the final paint path.
  11. When adding/removing files in runtime/mode/, update the runtime-mode file list in docs/site/content/docs/architecture/module-map.md.
  12. When changing TurnRequest/TurnEvent/TurnResult shapes in crates/agentty/src/infra/channel/contract.rs (re-exported by crates/agentty/src/infra/channel.rs), update the key-types table in docs/site/content/docs/architecture/runtime-flow.md.
  13. When adding/removing #[cfg_attr(test, mockall::automock)] external-boundary traits, update docs/site/content/docs/architecture/testability-boundaries.md.
  14. Run quality gates from AGENTS.md before opening a PR.