feat(flowctl): add compress filters for show/guard/cat and strip more compact fields

Wire show, guard, and cat commands through the TOML compress pipeline
(pretty_output) so they benefit from automatic token optimization in
non-TTY mode (Claude Code). Add three new TOML filter definitions with
inline tests. Expand COMPACT_STRIP to remove 8 additional JSON fields
that LLM consumers rarely need (branch_name, review statuses, defaults).

- show: strips slug prefixes, spec paths, shortens status labels
- guard: short-circuits to "✓ guard passed" on all-pass, limits failures to 30 lines
- cat: truncates long specs to head 30 + tail 5 lines
- compact JSON: strips branch_name, plan/completion review status/timestamps, defaults

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

flowctl/crates/flowctl-cli/src/commands/admin/guard.rs

@@ -11,7 +11,7 @@ use std::sync::OnceLock;
 use regex::Regex;
 use serde_json::json;
 
-use crate::output::{error_exit, json_output};
+use crate::output::{error_exit, json_output, pretty_output};
 
 use flowctl_core::types::CONFIG_FILE;
 
@@ -409,6 +409,7 @@ pub fn cmd_guard(json_mode: bool, layer: String) {
     let mut results: Vec<serde_json::Value> = Vec::new();
     let mut all_passed = true;
     let mut pass_count: usize = 0;
+    let mut pretty_buf = String::new();
 
     for (layer_name, cmd_type, cmd) in &commands {
         let output = Command::new("sh")
@@ -447,14 +448,14 @@ pub fn cmd_guard(json_mode: bool, layer: String) {
 
         if !json_mode {
             let icon = if passed { "\u{2713}" } else { "\u{2717}" };
-            println!(
-                "{} [{}] {}: {}",
+            pretty_buf.push_str(&format!(
+                "{} [{}] {}: {}\n",
                 icon, layer_name, cmd_type, filtered.summary
-            );
+            ));
             // Show errors inline for failed guards
             for err in &filtered.errors {
                 for err_line in err.lines().take(3) {
-                    println!("    {}", err_line);
+                    pretty_buf.push_str(&format!("    {}\n", err_line));
                 }
             }
         }
@@ -465,7 +466,8 @@ pub fn cmd_guard(json_mode: bool, layer: String) {
     } else {
         let total = commands.len();
         let suffix = if all_passed { "" } else { " \u{2014} FAILED" };
-        println!("\n{}/{} guards passed{}", pass_count, total, suffix);
+        pretty_buf.push_str(&format!("\n{}/{} guards passed{}", pass_count, total, suffix));
+        pretty_output("guard", &pretty_buf);
     }
 
     if !all_passed {

flowctl/crates/flowctl-cli/src/commands/query.rs

@@ -198,19 +198,21 @@ pub fn cmd_show(json: bool, id: String) {
             result["tasks"] = json!(task_summaries);
             json_output(result);
         } else {
-            println!("Epic: {}", epic.id);
-            println!("Title: {}", epic.title);
-            println!("Status: {}", epic.status);
-            println!("Spec: .flow/specs/{}.md", epic.id);
-            println!("\nTasks ({}):", tasks.len());
+            let mut buf = String::new();
+            buf.push_str(&format!("Epic: {}\n", epic.id));
+            buf.push_str(&format!("Title: {}\n", epic.title));
+            buf.push_str(&format!("Status: {}\n", epic.status));
+            buf.push_str(&format!("Spec: .flow/specs/{}.md\n", epic.id));
+            buf.push_str(&format!("\nTasks ({}):\n", tasks.len()));
             for t in &tasks {
                 let deps = if t.depends_on.is_empty() {
                     String::new()
                 } else {
                     format!(" (deps: {})", t.depends_on.join(", "))
                 };
-                println!("  [{}] {}: {}{}", t.status, t.id, t.title, deps);
+                buf.push_str(&format!("  [{}] {}: {}{}\n", t.status, t.id, t.title, deps));
             }
+            pretty_output("show", &buf);
         }
     } else if is_task_id(&id) {
         let task = match get_task(&flow_dir, &id) {
@@ -223,20 +225,22 @@ pub fn cmd_show(json: bool, id: String) {
         if json {
             json_output(task_to_json(&task));
         } else {
-            println!("Task: {}", task.id);
-            println!("Epic: {}", task.epic);
-            println!("Title: {}", task.title);
-            println!("Status: {}", task.status);
+            let mut buf = String::new();
+            buf.push_str(&format!("Task: {}\n", task.id));
+            buf.push_str(&format!("Epic: {}\n", task.epic));
+            buf.push_str(&format!("Title: {}\n", task.title));
+            buf.push_str(&format!("Status: {}\n", task.status));
             if task.domain != flowctl_core::types::Domain::General {
-                println!("Domain: {}", task.domain);
+                buf.push_str(&format!("Domain: {}\n", task.domain));
             }
             let deps_str = if task.depends_on.is_empty() {
                 "none".to_string()
             } else {
                 task.depends_on.join(", ")
             };
-            println!("Depends on: {}", deps_str);
-            println!("Spec: .flow/tasks/{}.md", task.id);
+            buf.push_str(&format!("Depends on: {}\n", deps_str));
+            buf.push_str(&format!("Spec: .flow/tasks/{}.md\n", task.id));
+            pretty_output("show", &buf);
         }
     } else {
         error_exit(&format!(
@@ -483,7 +487,7 @@ pub fn cmd_cat(id: String) {
         // Epic spec: still read from specs/ directory
         let spec_path = flow_dir.join(SPECS_DIR).join(format!("{}.md", id));
         match fs::read_to_string(&spec_path) {
-            Ok(content) => print!("{}", content),
+            Ok(content) => pretty_output("cat", &content),
             Err(_) => {
                 error_exit(&format!("Spec not found: {}", spec_path.display()));
             }
@@ -495,7 +499,7 @@ pub fn cmd_cat(id: String) {
                 if body.is_empty() {
                     error_exit(&format!("Task spec not found: {}", id));
                 }
-                print!("{}", body);
+                pretty_output("cat", &body);
             }
             Err(_) => {
                 error_exit(&format!("Task not found: {}", id));

flowctl/crates/flowctl-cli/src/output.rs

@@ -17,6 +17,14 @@ const COMPACT_STRIP: &[&str] = &[
     "spec_path",
     "file_path",
     "schema_version",
+    "branch_name",
+    "plan_review_status",
+    "plan_reviewed_at",
+    "completion_review_status",
+    "completion_reviewed_at",
+    "default_impl",
+    "default_review",
+    "default_sync",
 ];
 
 /// Shared output options (flattened into every subcommand via clap).

flowctl/crates/flowctl-core/src/compress.rs

@@ -38,6 +38,9 @@ const FILES_TOML: &str = include_str!("filters/files.toml");
 const READY_TOML: &str = include_str!("filters/ready.toml");
 const HOOK_PRECOMPACT_TOML: &str = include_str!("filters/hook_precompact.toml");
 const HOOK_SUBAGENT_TOML: &str = include_str!("filters/hook_subagent.toml");
+const SHOW_TOML: &str = include_str!("filters/show.toml");
+const GUARD_TOML: &str = include_str!("filters/guard.toml");
+const CAT_TOML: &str = include_str!("filters/cat.toml");
 
 // ---------------------------------------------------------------------------
 // Deserialization types (TOML schema)
@@ -269,6 +272,9 @@ const BUILTIN_SOURCES: &[(&str, &str)] = &[
     ("ready", READY_TOML),
     ("hook_precompact", HOOK_PRECOMPACT_TOML),
     ("hook_subagent", HOOK_SUBAGENT_TOML),
+    ("show", SHOW_TOML),
+    ("guard", GUARD_TOML),
+    ("cat", CAT_TOML),
 ];
 
 fn load_registry() -> Vec<CompiledFilter> {
@@ -698,6 +704,9 @@ on_empty = "all clean"
             "ready",
             "hook_precompact",
             "hook_subagent",
+            "show",
+            "guard",
+            "cat",
         ] {
             assert!(
                 reg.iter().any(|f| f.name == *expected),

flowctl/crates/flowctl-core/src/filters/cat.toml

@@ -0,0 +1,117 @@
+schema_version = 1
+
+[filters.cat]
+description = "Compact flowctl cat output — truncate long specs to head+tail"
+match_command = "^flowctl\\s+cat"
+head_lines = 30
+tail_lines = 5
+max_lines = 50
+truncate_lines_at = 120
+
+[[tests.cat]]
+name = "short spec passes through"
+input = """
+# Epic: Token Optimization
+
+## Goal
+Reduce token waste in flowctl output.
+
+## Tasks
+1. Add show filter
+2. Add guard filter
+3. Add cat filter
+"""
+expected = """
+# Epic: Token Optimization
+
+## Goal
+Reduce token waste in flowctl output.
+
+## Tasks
+1. Add show filter
+2. Add guard filter
+3. Add cat filter
+"""
+
+[[tests.cat]]
+name = "long spec truncated"
+input = """
+line 1
+line 2
+line 3
+line 4
+line 5
+line 6
+line 7
+line 8
+line 9
+line 10
+line 11
+line 12
+line 13
+line 14
+line 15
+line 16
+line 17
+line 18
+line 19
+line 20
+line 21
+line 22
+line 23
+line 24
+line 25
+line 26
+line 27
+line 28
+line 29
+line 30
+line 31
+line 32
+line 33
+line 34
+line 35
+line 36
+line 37
+line 38
+line 39
+line 40
+"""
+expected = """
+line 1
+line 2
+line 3
+line 4
+line 5
+line 6
+line 7
+line 8
+line 9
+line 10
+line 11
+line 12
+line 13
+line 14
+line 15
+line 16
+line 17
+line 18
+line 19
+line 20
+line 21
+line 22
+line 23
+line 24
+line 25
+line 26
+line 27
+line 28
+line 29
+line 30
+... (5 lines omitted)
+line 36
+line 37
+line 38
+line 39
+line 40
+"""

flowctl/crates/flowctl-core/src/filters/guard.toml

@@ -0,0 +1,44 @@
+schema_version = 1
+
+[filters.guard]
+description = "Compact flowctl guard output — short-circuit on all-pass, truncate failures"
+match_command = "^flowctl\\s+guard"
+strip_ansi = true
+match_output = [
+  # All guards passed — collapse to one-liner (skip if any ✗ failure present)
+  { pattern = "guards passed$", message = "✓ guard passed", unless = "✗" },
+]
+truncate_lines_at = 100
+max_lines = 30
+
+[[tests.guard]]
+name = "all passed short-circuits"
+input = """
+✓ [backend] test: 255 passed, 2 ignored (11 suites, 4.28s)
+✓ [backend] lint: no issues
+✓ [backend] typecheck: no issues
+
+3/3 guards passed
+"""
+expected = "✓ guard passed"
+
+[[tests.guard]]
+name = "failure preserved"
+input = """
+✓ [backend] test: 255 passed, 2 ignored (11 suites, 4.28s)
+✗ [backend] lint: 3 issues
+    error: unused variable `x`
+    error: missing docs
+    error: dead code
+
+2/3 guards passed — FAILED
+"""
+expected = """
+✓ [backend] test: 255 passed, 2 ignored (11 suites, 4.28s)
+✗ [backend] lint: 3 issues
+    error: unused variable `x`
+    error: missing docs
+    error: dead code
+
+2/3 guards passed — FAILED
+"""

flowctl/crates/flowctl-core/src/filters/show.toml

@@ -0,0 +1,67 @@
+schema_version = 1
+
+[filters.show]
+description = "Compact flowctl show output — strip slug noise, shorten status, truncate"
+match_command = "^flowctl\\s+show"
+strip_lines_matching = [
+  "^\\s*$",
+]
+replace = [
+  # Strip epic slug prefix from dep lists and task IDs
+  { pattern = "\\bfn-\\d+(?:-[a-zA-Z0-9-]+)?(\\.\\d+)", replacement = "$1" },
+  # Compact status labels
+  { pattern = "Status: in_progress", replacement = "Status: wip" },
+  { pattern = "Status: blocked", replacement = "Status: blk" },
+  { pattern = "Status: skipped", replacement = "Status: skip" },
+  # Compact task lines inside epic show
+  { pattern = "^(\\s*)\\[in_progress\\]", replacement = "${1}[wip]" },
+  { pattern = "^(\\s*)\\[skipped\\]", replacement = "${1}[skip]" },
+  { pattern = "^(\\s*)\\[blocked\\]", replacement = "${1}[blk]" },
+  # Strip "Spec: .flow/..." lines (LLM already knows spec paths)
+  { pattern = "^Spec: .flow/.*$", replacement = "" },
+]
+truncate_lines_at = 80
+max_lines = 40
+
+[[tests.show]]
+name = "epic show compaction"
+input = """
+Epic: fn-21-improve-flowctl-code-quality
+Title: Improve flowctl code quality
+Status: open
+Spec: .flow/specs/fn-21-improve-flowctl-code-quality.md
+
+Tasks (3):
+  [done] fn-21-improve-flowctl-code-quality.1: Remove dead code [backend]
+  [in_progress] fn-21-improve-flowctl-code-quality.2: Add clippy config [backend]
+  [todo] fn-21-improve-flowctl-code-quality.3: Add pre-commit hook [backend]
+"""
+expected = """
+Epic: fn-21-improve-flowctl-code-quality
+Title: Improve flowctl code quality
+Status: open
+Tasks (3):
+  [done] .1: Remove dead code [backend]
+  [wip] .2: Add clippy config [backend]
+  [todo] .3: Add pre-commit hook [backend]
+"""
+
+[[tests.show]]
+name = "task show compaction"
+input = """
+Task: fn-21-improve-flowctl-code-quality.1
+Epic: fn-21-improve-flowctl-code-quality
+Title: Remove dead code in diagnostics.rs
+Status: done
+Domain: backend
+Depends on: none
+Spec: .flow/tasks/fn-21-improve-flowctl-code-quality.1.md
+"""
+expected = """
+Task: .1
+Epic: fn-21-improve-flowctl-code-quality
+Title: Remove dead code in diagnostics.rs
+Status: done
+Domain: backend
+Depends on: none
+"""