7.0 KiB

Raw Blame History

herdr

Terminal workspace manager for AI coding agents. Rust + ratatui.

Principles

State is separated from runtime. AppState is pure data, testable without PTYs or async. PaneState is separate from PaneRuntime. Workspace logic doesn't need real terminals.
Render is pure. compute_view() handles geometry and mutations. render() takes &AppState and only draws. Never mutate state during render.
No god objects. If a module is doing too many things, split it. app/ is already split into state, actions, and input. Keep it that way.
Platform code is isolated. OS-specific behavior lives in src/platform/. Core modules don't have #[cfg(target_os)].
Detection is decoupled. The detector reads a screen snapshot, never touches the parser or viewport state.
UI patterns should be reused. Herdr is a mouse-first TUI. New dialogs, onboarding, settings, and post-update flows should follow the existing UI/UX language and interaction patterns instead of inventing one-off screens. Prefer reusing existing modal/screen structure, affordances, and close actions so the app feels consistent.

Multi-agent isolation

Read-only investigation can happen in the shared checkout.

Small changes or small tasks are fine in the default main worktree. If you find unrelated implementation changes already in progress in the main worktree, use a dedicated worktree instead. Use a dedicated worktree for bigger features too.

Use this layout:

shared integration checkout: ../herdr
task worktrees: ../herdr-worktrees/<task-slug>
task branches: issue/<id>-<slug> when an issue exists

Do all code edits, tests, and validation inside the task worktree.

Commit on the task branch in that worktree.

When the change is ready, fast-forward the shared checkout at ../herdr to the task branch commit, then push origin/master from ../herdr. Do not treat the task branch as the final landing branch.

If the current session is already inside an isolated task worktree, keep using it. Do not create nested worktrees.

Before committing, propose the commit message and get alignment.

After the change is integrated, remove the task worktree and delete the task branch locally and remotely.

Testing

Use just recipes by default for tests and checks instead of invoking cargo or scripts directly.

just test               # cargo nextest + maintenance script tests
just check              # formatting check + cargo nextest + maintenance script tests

Default flow: run just check before committing. Do not commit until just check passes locally unless Can explicitly accepts a narrower validation for that commit.

Unit tests live next to the code (#[cfg(test)] mod tests). If you add behavior to AppState or Workspace, it should be testable with AppState::test_new() and Workspace::test_new() — no PTYs.

Conventions

Conventional commits, lowercase, no emojis.
Do not edit root CHANGELOG.md during normal feature or fix work. Maintainers prepare docs/next/CHANGELOG.md during release review unless explicitly asked to update it earlier.
Treat the root public docs as the latest released docs. Do not document unreleased behavior in root README.md, CONFIGURATION.md, INTEGRATIONS.md, SOCKET_API.md, or CHANGELOG.md during normal feature or fix work.
Treat docs/next/README.md, docs/next/CONFIGURATION.md, docs/next/INTEGRATIONS.md, docs/next/SOCKET_API.md, and docs/next/CHANGELOG.md as the next-release versions of those public docs. When unreleased work needs public documentation, update the matching file under docs/next/ instead of the root file.
Before release, copy the approved docs/next/ versions into the root public docs. just release blocks until each root public doc and CHANGELOG.md are identical to their docs/next/ counterparts.
Keep website copy and config examples aligned with the latest published release unless the user explicitly asks for prerelease docs.
Put local PRDs, planning notes, and exploratory specs under .prd/; that directory is ignored and locally controlled.
When a normal feature or fix commit relates to a GitHub issue, add a commit body line refs #<issue-number> after the subject. Use this shape:
```
fix: handle pane focus

refs #82
```
Do not use GitHub closing keywords like fixes #<issue-number>, closes #<issue-number>, or resolves #<issue-number> in normal commits, because master contains unreleased work and those keywords close issues before release. Release CI scans refs #<issue-number> body lines between release tags and closes the referenced issues after the GitHub Release is created.
Rust: no unwrap() in production code. tracing for logging. #[allow] only with a comment explaining why.
Don't bypass checks. If tests fail, fix them before committing.
Don't add dependencies without a reason. Check if the existing deps cover it first.

Releases

Before cutting a release, run /pre-release-audit to compare commits since the last tag against docs/next/CHANGELOG.md and docs/next/, then copy the approved next-release docs and changelog into the root public docs. The release script promotes the root changelog's ## Unreleased section into the versioned entry and copies the prepared changelog back to docs/next/CHANGELOG.md so the next cycle starts clean.

Default release flow:

just check
just release 0.x.y

just release 0.x.y prepares the changelog entry, bumps Cargo.toml, runs tests, commits, tags, and pushes. GitHub Actions builds the binaries after the tag is pushed, creates the GitHub release, uploads all four binary assets, then updates website/latest.json on master automatically.

The release workflow must publish these four assets:

herdr-linux-x86_64
herdr-linux-aarch64
herdr-macos-x86_64
herdr-macos-aarch64

website/latest.json is the shipped updater source of truth. Keep its schema aligned with src/update.rs:

{
  "version": "0.x.y",
  "notes": "### ...",
  "assets": {
    "linux-x86_64": "...",
    "linux-aarch64": "...",
    "macos-x86_64": "...",
    "macos-aarch64": "..."
  }
}

The app update check and the in-app What's New flow both depend on that exact manifest shape.

Do not edit website/latest.json during normal feature, fix, or test work. It describes the latest published release binaries, not the current unreleased source tree. The release workflow updates it after release assets are published.

When changing the server/client wire protocol, compare src/server/protocol.rs::PROTOCOL_VERSION against the latest released tag. Bump it only if the current source protocol is not already greater than the latest released protocol. Multiple unreleased wire changes in the same release cycle must share the same single protocol bump; Herdr supports tagged releases, not arbitrary master client/server compatibility. When a bump is required, update all hardcoded protocol expectations and manual protocol fixtures in tests. Keep protocol test expectations intentionally explicit so compatibility changes are reviewed instead of silently following the constant.

7.0 KiB Raw Blame History