# AGENTS.md
## Mission
Build **`git-workty`** — a Git subcommand (`git workty …`) that turns Git worktrees into *daily-driver workspaces*.
The product goal is **instant, safe context switching** without stashing/WIP commits:
- Create a “task workspace” (worktree) in one command
- Jump between tasks in one command (with shell integration that actually `cd`s)
- See a clean **dashboard** of everything in flight (dirty/diverged/PR)
- Clean up merged work safely
> This tool is not a full Git TUI. It’s a focused “workspace switcher + dashboard” built on top of `git worktree`.
> Read `design.md` for the full spec.
---
## Non‑negotiables (do not compromise)
### Safety
1. **Never destroy work by default.**
- Do **not** remove a worktree with uncommitted changes unless `--force` is explicitly provided.
- Do **not** delete branches by default; branch deletion requires an explicit flag.
2. **Clear confirmations for destructive operations.**
- If running in an interactive terminal, prompt before deleting multiple worktrees unless `--yes`.
- In non-interactive contexts, require `--yes` for destructive multi-delete operations.
### Scriptability (stdout/stderr contract)
- If a command’s primary output is *a path* (e.g., `go`, `pick`, `new --print-path`), it must print **only that path to stdout** (plus a trailing newline).
- Human-readable logs, hints, progress, warnings should go to **stderr**.
- Provide `--json` for machine output where appropriate.
### Compatibility
- Must work on macOS, Linux, and Windows (PowerShell supported for `init`).
- Respect `NO_COLOR` and provide `--no-color`.
- Avoid shelling out through a shell (no `sh -c`). Use `std::process::Command` with args.
### Don’t reimplement Git
- This tool must use Git as the source of truth (`git worktree list --porcelain`, `git status`, etc.).
- Do not parse `.git` internal structures manually unless absolutely required.
---
## Deliverables (MVP)
### Binary + invocation
- Build a single binary named **`git-workty`**.
- Git will expose it as `git workty`.
### Commands
Implement the commands described in `design.md` (minimum set):
1. `git workty` (alias: `git workty list`)
2. `git workty new <name> [--from <base>] [--path <path>] [--print-path] [--open]`
3. `git workty go <name>` (prints path)
4. `git workty pick` (interactive fuzzy; prints chosen path)
5. `git workty rm <name> [--force] [--delete-branch] [--yes]`
6. `git workty clean [--merged] [--dry-run] [--yes]`
7. `git workty init <shell> [--wrap-git] [--no-cd]`
8. `git workty doctor`
9. `git workty completions <shell>`
10. (Optional but recommended) `git workty pr <number>` if `gh` is available
### Config
- Store per-repo config in the **common git dir**:
- path: `$(git rev-parse --git-common-dir)/workty.toml`
- Never write config into the working tree.
### UX polish checklist
- `--help` must contain **examples**.
- Errors must include “what happened” + “what to do next”.
- Default `list` output should be *one-screen scannable*.
---
## Rust implementation guidelines
### Tooling + style
- Rust stable (edition 2021).
- Run:
- `cargo fmt`
- `cargo clippy -- -D warnings`
- `cargo test`
- Prefer small modules over one giant file.
### Suggested crates
- CLI: `clap` (derive)
- Errors: `anyhow` + `thiserror`
- Serialization: `serde`, `serde_json`
- Config: `toml`
- TTY detection: `is-terminal` (or `atty`)
- Colors: `owo-colors` or `termcolor` + respect `NO_COLOR`
- Fuzzy picker: `dialoguer` (FuzzySelect)
- Temp dirs for tests: `tempfile`
### Module layout (suggested)
- `src/main.rs` – CLI entry + global flags + routing
- `src/git.rs` – all Git command execution + helpers
- `src/worktree.rs` – parse `git worktree list --porcelain`
- `src/status.rs` – dirty + ahead/behind computation
- `src/config.rs` – load/save config
- `src/ui.rs` – table rendering + color/icons + JSON output
- `src/shell.rs` – `init` scripts per shell
- `src/gh.rs` – optional GitHub CLI integration
---
## Testing requirements
### Unit tests
- Parse `git worktree list --porcelain` (cover: normal, detached, bare, locked).
- Slug/path building (branch name with `/`, spaces, Unicode).
- Config load/save and defaulting.
### Integration tests (minimum)
Using `tempfile`:
1. Create a repo, commit a file, set a base branch.
2. `workty new foo` creates a new worktree at expected path.
3. `workty list` shows both main + foo.
4. Dirty detection works (`echo >> file`).
5. `rm` refuses dirty without `--force`.
6. `clean --dry-run` lists candidates; `clean --yes` actually removes.
---
## Release notes (don’t skip)
When MVP passes tests:
- Add a `README.md` quickstart with a 30-second demo flow.
- Provide install instructions: `cargo install --path .` (at minimum) and ideally prebuilt releases later.
---
## “Incredible DX” bar
If you’re unsure what to optimize: optimize the 3 commands below until they feel *inevitable*:
1) `git workty`
2) `wcd` (from `init`)
3) `git workty new <name>`
If those are delightful, the product will spread.