Skip to content

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.md
index 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
+// GOOD
output::print(success_message("Branch created"))?;
-// BAD - direct writes bypass output system
+// BAD - bypasses output system
println!("Branch created");
```
diff --git a/.claude/rules/output-system-architecture.md b/.claude/rules/output-system-architecture.md
index 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 directive
file.
-
-## 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()`