Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Refactor output system documentation for clarity
Maximilian Roos963ad0995065
diff --git a/.claude/rules/cli-output-formatting.md b/.claude/rules/cli-output-formatting.mdindex 29d5aa6ac..19ccf607c 100644--- a/.claude/rules/cli-output-formatting.md+++ b/.claude/rules/cli-output-formatting.md@@ -226,15 +226,16 @@ Use `suggest_command()` from `worktrunk::styling` for proper shell escaping.- **One blank after prompts** — Separate user input from results- **Never double blanks** — One blank line maximum between elements-## stdout vs stderr+## Output System-See `output-system-architecture.md` for the stream separation. Key rule:+Use `output::` functions, never direct `println!`. See `output-system-architecture.md`+for stdout vs stderr decisions.```rust-// GOOD - use output system+// GOODoutput::print(success_message("Branch created"))?;-// BAD - direct writes bypass output system+// BAD - bypasses output systemprintln!("Branch created");```diff --git a/.claude/rules/output-system-architecture.md b/.claude/rules/output-system-architecture.mdindex 29d3e34c2..ecd3ff9a2 100644--- a/.claude/rules/output-system-architecture.md+++ b/.claude/rules/output-system-architecture.md@@ -59,21 +59,19 @@ output::change_directory(&path)?; // Writes to directive file if set, else no-o## stdout vs stderr-- **stdout**: Primary output (tables, JSON) — pipeable-- **stderr**: Status messages (progress, success, errors, hints)-- **directive file**: Shell commands (cd, exec)+**Decision principle:** If this command is piped, what should the receiving program get?-This separation makes `wt list | grep feature` work.+- **stdout** → Data for pipes, scripts, `eval` (tables, JSON, shell code)+- **stderr** → Status for the human watching (progress, success, errors, hints)+- **directive file** → Shell commands executed after wt exits (cd, exec)++Examples:+- `wt list` → table/JSON to stdout (for grep, jq, scripts)+- `wt config shell init` → shell code to stdout (for `eval`)+- `wt switch` → status messages only (nothing to pipe)## Security`WORKTRUNK_DIRECTIVE_FILE` is automatically removed from spawned subprocesses(via `shell_exec::run()`). This prevents hooks from writing to the directivefile.--## Adding New Output Functions--Add the function to `global.rs`. The pattern:-- **Primary output** (data the command produces) → stdout via `table()` or `data()`-- **Status messages** (progress, success, errors) → stderr via `print()`-- **Directives** (cd, exec) → directive file via `change_directory()`, `execute()`