# git-paw — Master TODO
Repository: `bearicorn/git-paw`
**Commands:** `start`, `stop`, `purge`, `status`, `list-clis`, `add-cli`, `remove-cli`
---
## Complete File Tree (87 files)
```
git-paw/
├── .editorconfig
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.yml
│ │ ├── config.yml
│ │ └── feature_request.yml
│ ├── dependabot.yml
│ ├── pull_request_template.md
│ └── workflows/
│ ├── ci.yml
│ ├── commitlint.yml
│ ├── docs.yml
│ └── release.yml
├── .gitignore
├── CHANGELOG.md
├── CLAUDE.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── Cargo.lock
├── Cargo.toml
├── LICENSE-APACHE
├── LICENSE-MIT
├── README.md
├── SECURITY.md
├── cliff.toml
├── deny.toml
├── justfile
├── rust-toolchain.toml
├── rustfmt.toml
├── docs/
│ ├── book.toml
│ └── src/
│ ├── SUMMARY.md
│ ├── architecture.md
│ ├── changelog.md
│ ├── cli-reference.md
│ ├── configuration/
│ │ ├── custom-clis.md
│ │ ├── global-config.md
│ │ ├── merging.md
│ │ ├── presets.md
│ │ └── repo-config.md
│ ├── contributing.md
│ ├── faq.md
│ ├── installation.md
│ ├── introduction.md
│ ├── quick-start-per-branch.md
│ ├── quick-start-same-cli.md
│ ├── specifications.md
│ ├── specifications/
│ │ ├── cli-detection.md
│ │ ├── configuration.md
│ │ ├── error-handling.md
│ │ ├── git-operations.md
│ │ ├── interactive-selection.md
│ │ ├── session-state.md
│ │ └── tmux-orchestration.md
│ ├── supported-clis.md
│ └── user-guide/
│ ├── cli-modes.md
│ ├── dry-run.md
│ ├── non-interactive.md
│ ├── presets.md
│ ├── session-management.md
│ └── starting-sessions.md
├── openspec/
│ ├── README.md
│ ├── changes/
│ │ └── .gitkeep
│ └── specs/
│ ├── cli-detection/
│ │ └── spec.md
│ ├── configuration/
│ │ └── spec.md
│ ├── error-handling/
│ │ └── spec.md
│ ├── git-operations/
│ │ └── spec.md
│ ├── interactive-selection/
│ │ └── spec.md
│ ├── session-state/
│ │ └── spec.md
│ └── tmux-orchestration/
│ └── spec.md
├── src/
│ ├── cli.rs
│ ├── config.rs
│ ├── detect.rs
│ ├── error.rs
│ ├── git.rs
│ ├── interactive.rs
│ ├── main.rs
│ ├── session.rs
│ └── tmux.rs
└── tests/
├── cli_tests.rs
├── config_integration.rs
├── e2e_tests.rs
├── git_integration.rs
├── helpers/
│ └── mod.rs
└── session_integration.rs
```
---
## Sequential Steps
### Phase 0: GitHub Setup (~15 minutes)
- [x] **0.1** Verify `bearicorn` org exists on GitHub
- [x] **0.2** Create repo `bearicorn/git-paw` (empty, default README)
- [x] **0.3** Set description: "Parallel AI Worktrees — orchestrate multiple AI coding CLI sessions across git worktrees"
- [x] **0.4** Set topics: `rust`, `cli`, `tmux`, `git-worktree`, `ai-coding`, `developer-tools`, `terminal`
- [x] **0.5** Set website URL: `https://bearicorn.github.io/git-paw/`
- [x] **0.6** Enable GitHub Pages (source: GitHub Actions)
- [x] **0.7** Enable GitHub Discussions
- [x] **0.8** Branch protection on `main`: require PR, require status checks, linear history
- [x] **0.9** Clone locally: `git clone git@github.com:bearicorn/git-paw.git && cd git-paw`
- [ ] **0.10** Reserve crate name on crates.io (placeholder 0.0.1)
- [ ] **0.11** Create `bearicorn/homebrew-tap` repo (empty — cargo-dist pushes formulas here)
### Phase 1: Scaffold (Issue #1, on `main`, ~30 minutes)
- [ ] **1.1** Add `LICENSE-MIT` and `LICENSE-APACHE`
- [ ] **1.2** Add `.gitignore` (Rust template)
- [ ] **1.3** Copy `CLAUDE.md` into repo root
- [ ] **1.4** `cargo init --name git-paw`
- [ ] **1.5** Set up `Cargo.toml`:
- `[package]`: name, version (0.1.0), edition (2021), description, license, repository, homepage, keywords, categories
- `[dependencies]`: clap (derive), dialoguer, console, which, thiserror, anyhow, serde (derive), serde_json, toml, dirs
- `[dev-dependencies]`: assert_cmd, predicates, tempfile, serial_test
- `[lints.clippy]`: pedantic = "warn" + specific allows/denies
- [ ] **1.6** `cargo dist init` — targets: macOS ARM/x86, Linux x86_64/ARM64; installers: shell, homebrew; tap: `bearicorn/homebrew-tap`
- [ ] **1.7** Add `rust-toolchain.toml` (stable)
- [ ] **1.8** Add `rustfmt.toml`
- [ ] **1.9** Add `.editorconfig`
- [ ] **1.10** Add `justfile` with all recipes
- [ ] **1.11** Create module stubs with `//!` docs: `error.rs`, `detect.rs`, `git.rs`, `tmux.rs`, `session.rs`, `config.rs`, `interactive.rs`
- [ ] **1.12** Create `src/cli.rs` — clap subcommands: start (default), stop, purge, status, list-clis, add-cli, remove-cli
- [ ] **1.13** Create `src/main.rs` — wire cli.rs
- [ ] **1.14** Verify: `cargo build`, `cargo clippy -- -D warnings`, `cargo fmt --check`
- [ ] **1.15** Verify: `git-paw --help`, `git-paw --version`
- [ ] **1.16** Commit: `feat(cli): scaffold project with subcommands and module stubs`
- [ ] **1.17** Push to `main`
### Phase 2: Create Branches + Issues (~10 minutes)
- [ ] **2.1** Create Wave 1 branches:
```bash
for b in feat/detect feat/git-ops feat/tmux feat/session-state feat/config feat/interactive feat/errors; do
git branch "$b"; done
git push origin --all
```
- [ ] **2.2** Create all 15 GitHub issues from the issues document
- [ ] **2.3** Assign labels and link branches
### Phase 3: Wave 1 — Core Implementation (7 parallel sessions, ~1 hour)
```bash
./parallel-ai.sh
# Select CLI: claude
# Select branches: feat/detect, feat/git-ops, feat/tmux, feat/session-state, feat/config, feat/interactive, feat/errors
```
- [ ] **3.1** Pane 1 — `feat/errors`: PawError enum (Issue #8)
- [ ] **3.2** Pane 2 — `feat/detect`: CLI detection + custom CLI loading (Issue #2)
- [ ] **3.3** Pane 3 — `feat/git-ops`: Branch listing + worktree management (Issue #3)
- [ ] **3.4** Pane 4 — `feat/tmux`: Session/pane orchestration + builder (Issue #4)
- [ ] **3.5** Pane 5 — `feat/session-state`: Persistence + recovery data (Issue #5)
- [ ] **3.6** Pane 6 — `feat/config`: TOML parsing + add/remove CLI + presets (Issue #6)
- [ ] **3.7** Pane 7 — `feat/interactive`: Dialoguer prompts + selection flows (Issue #7)
### Phase 4: Wave 1 Merge (~30 minutes)
- [ ] **4.1** Merge `feat/errors` first (shared dependency)
- [ ] **4.2** Merge remaining 6 in any order
- [ ] **4.3** Verify `main` builds: `cargo build && cargo clippy -- -D warnings`
- [ ] **4.4** Fix any merge conflicts
### Phase 5: Create Wave 2 Branches (~5 minutes)
- [ ] **5.1** Pull latest `main`
- [ ] **5.2** Create branches:
```bash
for b in feat/wire-up feat/unit-tests feat/integration-tests feat/ci feat/openspec feat/docs-site feat/readme; do
git branch "$b"; done
git push origin --all
```
### Phase 6: Wave 2 — Tests, CI, Docs (7 parallel sessions, ~1-2 hours)
```bash
./parallel-ai.sh
# Select CLI: claude
# Select branches: feat/wire-up, feat/unit-tests, feat/integration-tests, feat/ci, feat/openspec, feat/docs-site, feat/readme
```
- [ ] **6.1** Pane 1 — `feat/wire-up`: Connect all modules, smart start/stop/purge/status/add-cli/remove-cli (Issue #15)
- [ ] **6.2** Pane 2 — `feat/unit-tests`: Unit tests + coverage config (Issue #10)
- [ ] **6.3** Pane 3 — `feat/integration-tests`: Integration + E2E tests (Issue #11)
- [ ] **6.4** Pane 4 — `feat/ci`: GitHub Actions + deny.toml (Issue #12)
- [ ] **6.5** Pane 5 — `feat/openspec`: Spec files (Issue #9)
- [ ] **6.6** Pane 6 — `feat/docs-site`: mdBook (Issue #13)
- [ ] **6.7** Pane 7 — `feat/readme`: README + community files (Issue #14)
### Phase 7: Wave 2 Merge (~45 minutes)
- [ ] **7.1** Merge `feat/wire-up` first
- [ ] **7.2** Verify `cargo run -- --help` works end-to-end
- [ ] **7.3** Merge `feat/unit-tests` + `feat/integration-tests`
- [ ] **7.4** Verify `cargo test` passes
- [ ] **7.5** Merge `feat/openspec` + `feat/docs-site` + `feat/readme`
- [ ] **7.6** Verify `mdbook build docs/` succeeds
- [ ] **7.7** Merge `feat/ci` last
- [ ] **7.8** Verify CI passes on `main`
### Phase 8: Smoke Test (~20 minutes)
- [ ] **8.1** `just check` — passes
- [ ] **8.2** `just coverage` — >= 80%
- [ ] **8.3** `just deny` — passes
- [ ] **8.4** `just docs` — builds and opens
- [ ] **8.5** `just api-docs` — Rustdoc clean
- [ ] **8.6** `cargo run -- --help` — professional help text
- [ ] **8.7** `git paw start` in a real repo with Claude Code
- [ ] **8.8** Detach (`Ctrl+b d`), then `git paw start` — reattaches
- [ ] **8.9** `git paw stop`, then `git paw start` — recovers from stopped
- [ ] **8.10** Kill tmux manually, then `git paw start` — auto-recovers from crash
- [ ] **8.11** `git paw status` — shows correct state
- [ ] **8.12** `git paw add-cli test-agent /usr/bin/echo` — adds to config
- [ ] **8.13** `git paw list-clis` — shows detected + custom
- [ ] **8.14** `git paw remove-cli test-agent` — removes from config
- [ ] **8.15** `git paw purge --force` — everything removed
- [ ] **8.16** `git paw start --dry-run` — prints plan
- [ ] **8.17** GitHub Pages docs site is live
### Phase 9: Release v0.1.0 (~15 minutes)
- [ ] **9.1** `git cliff -o CHANGELOG.md`
- [ ] **9.2** Review CHANGELOG.md
- [ ] **9.3** Commit: `chore: prepare v0.1.0 release`
- [ ] **9.4** `git tag v0.1.0`
- [ ] **9.5** `git push origin main --tags`
- [ ] **9.6** Verify cargo-dist release:
- Binaries for macOS ARM/x86, Linux x86_64/ARM64
- GitHub Release with binaries, checksums, shell installer
- Homebrew formula pushed to `bearicorn/homebrew-tap`
- [ ] **9.7** `cargo publish`
- [ ] **9.8** Verify all install methods:
- `cargo install git-paw`
- `curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bearicorn/git-paw/releases/latest/download/git-paw-installer.sh | sh`
- `brew install bearicorn/tap/git-paw`
### Phase 10: Launch (~1 hour)
- [ ] **10.1** Verify badges in README are live
- [ ] **10.2** Verify docs site at `https://bearicorn.github.io/git-paw/`
- [ ] **10.3** Record demo GIF (`vhs` or `asciinema`)
- [ ] **10.4** Update README with demo GIF
- [ ] **10.5** Write launch post (dev.to or blog)
- [ ] **10.6** Post to: r/rust, r/commandline, Hacker News, X
- [ ] **10.7** Monitor feedback
- [ ] **10.8** Celebrate 🎉
---
## Summary
| 0 | GitHub setup | 15 min | No |
| 1 | Scaffold | 30 min | No |
| 2 | Branches + issues | 10 min | No |
| 3 | Wave 1: 7 modules | ~1 hour | 7 sessions |
| 4 | Wave 1 merge | 30 min | No |
| 5 | Wave 2 branches | 5 min | No |
| 6 | Wave 2: tests/CI/docs | ~1-2 hours | 7 sessions |
| 7 | Wave 2 merge | 45 min | No |
| 8 | Smoke test | 20 min | No |
| 9 | Release | 15 min | No |
| 10 | Launch | 1 hour | No |
**~5-6 hours** from zero to published crate, docs site, and launch post.
---
## Scripts
- **`parallel-ai.sh`** — launch parallel sessions
- **`cleanup-ai.sh`** — teardown sessions
These prototype what git-paw itself will become.
---
## Dependencies
| `clap` v4 | CLI parsing, subcommands, completions |
| `dialoguer` | Interactive prompts |
| `console` | Terminal colors/styling |
| `which` | PATH binary detection |
| `thiserror` | Typed errors |
| `anyhow` | Application error handling |
| `serde` + `serde_json` | Session serialization |
| `toml` + `serde` | Config parsing |
| `dirs` | Platform XDG directories |
Dev: `assert_cmd`, `predicates`, `tempfile`, `serial_test`
**Runtime:** `git`, `tmux`
**Platform:** macOS, Linux, Windows (WSL only)
**Dev tools:** `cargo-dist`, `cargo-llvm-cov`, `cargo-deny`, `git-cliff`, `just`
---
## Milestones
| **v0.1.0** | Core: start/stop/purge/status/add-cli/remove-cli, docs, CI, tests |
| **v0.2.0** | Presets, session resume improvements, `.deb` packaging |
| **v0.3.0** | Pane labels, prompt pre-loading |
| **v1.0.0** | Stable CLI contract, broad distribution |