Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Reorganize CLAUDE.md: lead with pre-merge, move docs to subdirs (#224)

Maximilian Roosa9d24f6b99d4
diff --git a/CLAUDE.md b/CLAUDE.md
index caed82035..c3ca99dbf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,22 +45,29 @@ Avoid mixing: "main/default branch worktree" is confusing. Use "main worktree" f
### Running Tests
```bash
-# Unit tests (fast)
+# Run all tests + lints (recommended before committing)
+cargo run -- hook pre-merge --force
+```
+
+The pre-merge hook runs lints and the full test suite.
+
+**For faster iteration during development:**
+
+```bash
+# Lints only
+pre-commit run --all-files
+
+# Unit tests only
cargo test --lib --bins
-# Integration tests without shell tests (no external dependencies)
+# Integration tests (no shell tests)
cargo test --test integration
-# Integration tests WITH shell tests (requires bash/zsh/fish)
+# Integration tests with shell tests (requires bash/zsh/fish)
cargo test --test integration --features shell-integration-tests
-
-# Run all tests via pre-merge hook (recommended before committing)
-cargo run -- hook pre-merge --force
```
-The pre-merge hook runs the full test suite and is the recommended way to verify changes before committing.
-
-**Shell integration tests** require bash, zsh, and fish. On Linux, run `./dev/setup-claude-code-web.sh` to install them.
+**Shell integration tests** require bash, zsh, and fish.
### Claude Code Web Environment
@@ -70,7 +77,7 @@ When working in Claude Code web, run the setup script first:
./dev/setup-claude-code-web.sh
```
-This installs required shells (zsh, fish) and builds the project. The permission tests (`test_permission_error_prevents_save`, `test_approval_prompt_permission_error`) automatically skip when running as root, which is common in containerized environments.
+This installs required shells (zsh, fish) for shell integration tests and builds the project. The permission tests (`test_permission_error_prevents_save`, `test_approval_prompt_permission_error`) automatically skip when running as root, which is common in containerized environments.
### Shell/PTY Integration Tests
@@ -86,21 +93,6 @@ NEXTEST_NO_INPUT_HANDLER=1 cargo nextest run --features shell-integration-tests
The pre-merge hook already sets `NEXTEST_NO_INPUT_HANDLER=1`.
-### CLI Flag Descriptions
-
-Keep the first line of flag and argument descriptions brief—aim for 3-6 words. Use parenthetical defaults sparingly, only when the default isn't obvious from context.
-
-**Good examples:**
-- `/// Skip approval prompts`
-- `/// Show CI and \`main\` diffstat`
-- `/// Target branch (defaults to default branch)`
-
-**Bad examples (too verbose):**
-- `/// Auto-approve project commands without saving approvals.`
-- `/// Show CI status, conflict detection, and complete diff statistics`
-
-The help text should be scannable. Users reading `wt switch --help` need to quickly understand what each flag does without parsing long sentences.
-
## Command Execution Principles
### Real-time Output Streaming
@@ -140,59 +132,6 @@ Examples (where command names are from config):
Users can clean up old logs manually or use a git hook. No automatic cleanup is provided.
-## Testing Guidelines
-
-### Timing Tests: Long Timeouts with Fast Polling
-
-**Core principle:** Use long timeouts (5+ seconds) for reliability on slow CI, but poll frequently (10-50ms) so tests complete quickly when things work.
-
-This achieves both goals:
-- **No flaky failures** on slow machines - generous timeout accommodates worst-case
-- **Fast tests** on normal machines - frequent polling means no unnecessary waiting
-
-```rust
-// ✅ GOOD: Long timeout, fast polling
-let timeout = Duration::from_secs(5);
-let poll_interval = Duration::from_millis(10);
-let start = Instant::now();
-while start.elapsed() < timeout {
- if condition_met() { break; }
- thread::sleep(poll_interval);
-}
-
-// ❌ BAD: Fixed sleep (always slow, might still fail)
-thread::sleep(Duration::from_millis(500));
-assert!(condition_met());
-
-// ❌ BAD: Short timeout (flaky on slow CI)
-let timeout = Duration::from_millis(100);
-```
-
-Use the helpers in `tests/common/mod.rs`:
-
-```rust
-use crate::common::{wait_for_file, wait_for_file_count};
-
-// ✅ Poll for file existence with 5+ second timeout
-wait_for_file(&log_file, Duration::from_secs(5));
-
-// ✅ Poll for multiple files
-wait_for_file_count(&log_dir, "log", 3, Duration::from_secs(5));
-```
-
-These use exponential backoff (10ms → 500ms cap) for fast initial checks that back off on slow CI.
-
-**Exception - testing absence:** When verifying something did NOT happen, polling doesn't work. Use a fixed 500ms+ sleep:
-
-```rust
-thread::sleep(Duration::from_millis(500));
-assert!(!marker_file.exists(), "Command should NOT have run");
-```
-
-### Testing with --execute Commands
-
-Use `--force` to skip interactive prompts in tests. Don't pipe input to stdin.
-
## Coverage
- Install once: `cargo install cargo-llvm-cov`.
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index f7d146cd9..106150872 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -93,6 +93,21 @@ branch: Option<String>,
**Pattern:** All branch arguments should use `branch_value_completer()` for consistency with commands like `wt merge`, `wt switch --base`, `wt rebase`.
+## CLI Flag Descriptions
+
+Keep the first line of flag and argument descriptions brief—aim for 3-6 words. Use parenthetical defaults sparingly, only when the default isn't obvious from context.
+
+**Good examples:**
+- `/// Skip approval prompts`
+- `/// Show CI and \`main\` diffstat`
+- `/// Target branch (defaults to default branch)`
+
+**Bad examples (too verbose):**
+- `/// Auto-approve project commands without saving approvals.`
+- `/// Show CI status, conflict detection, and complete diff statistics`
+
+The help text should be scannable. Users reading `wt switch --help` need to quickly understand what each flag does without parsing long sentences.
+
## CLI Help Text Placement
Help text has three levels:
diff --git a/tests/CLAUDE.md b/tests/CLAUDE.md
index b3eb0cf39..81437c124 100644
--- a/tests/CLAUDE.md
+++ b/tests/CLAUDE.md
@@ -1,5 +1,56 @@
# Testing Guidelines
+## Timing Tests: Long Timeouts with Fast Polling
+
+**Core principle:** Use long timeouts (5+ seconds) for reliability on slow CI, but poll frequently (10-50ms) so tests complete quickly when things work.
+
+This achieves both goals:
+- **No flaky failures** on slow machines - generous timeout accommodates worst-case
+- **Fast tests** on normal machines - frequent polling means no unnecessary waiting
+
+```rust
+// ✅ GOOD: Long timeout, fast polling
+let timeout = Duration::from_secs(5);
+let poll_interval = Duration::from_millis(10);
+let start = Instant::now();
+while start.elapsed() < timeout {
+ if condition_met() { break; }
+ thread::sleep(poll_interval);
+}
+
+// ❌ BAD: Fixed sleep (always slow, might still fail)
+thread::sleep(Duration::from_millis(500));
+assert!(condition_met());
+
+// ❌ BAD: Short timeout (flaky on slow CI)
+let timeout = Duration::from_millis(100);
+```
+
+Use the helpers in `tests/common/mod.rs`:
+
+```rust
+use crate::common::{wait_for_file, wait_for_file_count};
+
+// ✅ Poll for file existence with 5+ second timeout
+wait_for_file(&log_file, Duration::from_secs(5));
+
+// ✅ Poll for multiple files
+wait_for_file_count(&log_dir, "log", 3, Duration::from_secs(5));
+```
+
+These use exponential backoff (10ms → 500ms cap) for fast initial checks that back off on slow CI.
+
+**Exception - testing absence:** When verifying something did NOT happen, polling doesn't work. Use a fixed 500ms+ sleep:
+
+```rust
+thread::sleep(Duration::from_millis(500));
+assert!(!marker_file.exists(), "Command should NOT have run");
+```
+
+## Testing with --execute Commands
+
+Use `--force` to skip interactive prompts in tests. Don't pipe input to stdin.
+
## README Examples and Snapshot Testing
### Problem: Separated stdout/stderr in Standard Snapshots