Allow --head/--tail to customize count with --after/--before cursors

Previously all four direction/cursor flags were mutually exclusive,
which locked cursor-based pagination to the hardcoded default of 25.
Relax the rule to allow the natural combinations:

  --after TS --head N    next N newer after TS
  --before TS --tail N   previous N older before TS

Still forbidden: --head + --tail (two counts), --after + --before (two
cursors), --head + --before, --tail + --after (direction conflicts).
Error messages name the offending pair. README and skill docs updated
with the new idioms and drop the "next/previous 25" phrasing in favor
of "default 25, override with --head/--tail".

Author: fprochazka

README.md

@@ -135,11 +135,13 @@ slack conversations list --refresh
 slack messages list '#general'
 slack messages list C0123456789
 
-# Direction flags (mutually exclusive)
-slack messages list '#general' --tail 5                    # last 5 messages
-slack messages list '#general' --head 5                    # first 5 in window
-slack messages list '#general' --after 1234567890.123456   # next 25 after cursor
-slack messages list '#general' --before 1234567890.123456  # previous 25 before cursor
+# Direction flags
+slack messages list '#general' --tail 5                             # last 5 messages
+slack messages list '#general' --head 5                             # first 5 in window
+slack messages list '#general' --after 1234567890.123456            # messages after cursor (default 25, override with --head N)
+slack messages list '#general' --before 1234567890.123456           # messages before cursor (default 25, override with --tail N)
+slack messages list '#general' --after 1234567890.123456 --head 5   # next 5 newer
+slack messages list '#general' --before 1234567890.123456 --tail 5  # previous 5 older
 
 # Compose with time windows
 slack messages list '#general' --today

coding-agent-plugins/claude-code/skills/slackcli/SKILL.md

@@ -72,26 +72,33 @@ slack conversations list --refresh    # Force cache refresh
 
 ### List Messages
 
-Four mutually-exclusive direction flags control which slice of history to fetch.
-When no direction flag is given, the default is `--tail 25`. Results are always
-displayed oldest → newest.
+Direction flags control which slice of history to fetch. When no direction flag
+is given, the default is `--tail 25`. Results are always displayed
+oldest → newest.
 
 | Flag | Meaning |
 |------|---------|
 | `--tail N` | Last N messages in the window (default direction; default N=25) |
 | `--head N` | First N messages in the window, oldest first |
-| `--after TS` | Next 25 messages after cursor timestamp TS (forward walk) |
-| `--before TS` | Previous 25 messages before cursor timestamp TS (backward walk) |
+| `--after TS` | Messages after cursor timestamp TS (default 25, override with `--head N`) |
+| `--before TS` | Messages before cursor timestamp TS (default 25, override with `--tail N`) |
+
+Allowed combinations: `--head N` alone, `--tail N` alone, `--after TS` alone,
+`--before TS` alone, `--after TS --head N`, `--before TS --tail N`.
+`--head + --tail`, `--after + --before`, `--head + --before`, and
+`--tail + --after` are rejected.
 
 Direction flags compose with time-window flags (`--since`, `--until`, `--today`,
 `--last-7d`, `--last-30d`), which are orthogonal bounds on the window.
 
 ```bash
-slack messages list '#channel'                            # Last 25 messages
-slack messages list '#channel' --tail 5                   # Last 5 messages
-slack messages list '#channel' --head 5                   # First 5 in window
-slack messages list '#channel' --after 1234567890.123456  # Next 25 after cursor
-slack messages list '#channel' --before 1234567890.123456 # Previous 25 before cursor
+slack messages list '#channel'                                      # Last 25 messages
+slack messages list '#channel' --tail 5                             # Last 5 messages
+slack messages list '#channel' --head 5                             # First 5 in window
+slack messages list '#channel' --after 1234567890.123456            # After cursor (default 25)
+slack messages list '#channel' --before 1234567890.123456           # Before cursor (default 25)
+slack messages list '#channel' --after 1234567890.123456 --head 5   # Next 5 newer
+slack messages list '#channel' --before 1234567890.123456 --tail 5  # Previous 5 older
 
 slack messages list '#channel' --today                    # Today only
 slack messages list '#channel' --last-7d                  # Last 7 days

src/slackcli/commands/messages.py

@@ -276,14 +276,16 @@ def list_messages(
         str | None,
         typer.Option(
             "--after",
-            help="Return up to 25 messages strictly after this ts (forward cursor).",
+            help="Return messages strictly after this ts (forward cursor). "
+            "Defaults to 25; combine with --head N to override.",
         ),
     ] = None,
     before: Annotated[
         str | None,
         typer.Option(
             "--before",
-            help="Return up to 25 messages strictly before this ts (backward cursor).",
+            help="Return messages strictly before this ts (backward cursor). "
+            "Defaults to 25; combine with --tail N to override.",
         ),
     ] = None,
     reactions: Annotated[
@@ -310,15 +312,20 @@ def list_messages(
 ) -> None:
     """List messages in a channel or thread.
 
-    Exactly one of --head / --tail / --after / --before may be set. If none
-    are specified, --tail 25 is used. Display order is always ascending
-    (oldest on top, newest on bottom) regardless of the direction flag.
+    Direction flags compose as follows: --head N or --tail N alone, --after TS
+    or --before TS alone (defaults to 25), or --after TS --head N /
+    --before TS --tail N to override the count. Any other combination is
+    rejected. If none are specified, --tail 25 is used. Display order is
+    always ascending (oldest on top, newest on bottom) regardless of the
+    direction flag.
 
     Examples:
         slack messages list '#general'                        # last 25
         slack messages list '#general' --tail 5
         slack messages list '#general' --after 1234567890.123456
         slack messages list '#general' --before 1234567890.123456
+        slack messages list '#general' --after 1234567890.123456 --head 5
+        slack messages list '#general' --before 1234567890.123456 --tail 5
         slack messages list '#general' --head 100 --since 2024-01-01
         slack messages list '#general' 1234567890.123456      # thread replies
     """
@@ -327,17 +334,29 @@ def list_messages(
         error_console.print(f"[red]Invalid --reactions value: {reactions}. Use 'off', 'counts', or 'names'.[/red]")
         raise typer.Exit(1)
 
-    # Validate mutually exclusive direction flags.
-    direction_flags = {
-        "--head": head is not None,
-        "--tail": tail is not None,
-        "--after": after is not None,
-        "--before": before is not None,
-    }
-    set_flags = [name for name, is_set in direction_flags.items() if is_set]
-    if len(set_flags) > 1:
+    # Validate direction flag combinations. Allowed:
+    #   (none), --head N, --tail N, --after TS, --before TS,
+    #   --after TS --head N, --before TS --tail N.
+    # Everything else is a user error.
+    has_head = head is not None
+    has_tail = tail is not None
+    has_after = after is not None
+    has_before = before is not None
+
+    if has_head and has_tail:
+        error_console.print("[red]--head and --tail are mutually exclusive.[/red]")
+        raise typer.Exit(1)
+    if has_after and has_before:
+        error_console.print("[red]--after and --before are mutually exclusive.[/red]")
+        raise typer.Exit(1)
+    if has_head and has_before:
         error_console.print(
-            f"[red]--head / --tail / --after / --before are mutually exclusive. Got: {', '.join(set_flags)}[/red]"
+            "[red]--head cannot be combined with --before. Use --tail N with --before, or --head N with --after.[/red]"
+        )
+        raise typer.Exit(1)
+    if has_tail and has_after:
+        error_console.print(
+            "[red]--tail cannot be combined with --after. Use --head N with --after, or --tail N with --before.[/red]"
         )
         raise typer.Exit(1)
 
@@ -347,14 +366,20 @@ def list_messages(
     count: int
     after_ts: str | None = None
     before_ts: str | None = None
-    if head is not None:
-        direction, count = "head", head
-    elif tail is not None:
-        direction, count = "tail", tail
-    elif after is not None:
+    if has_after and has_head:
+        direction, count = "head", head  # type: ignore[assignment]
+        after_ts = after
+    elif has_before and has_tail:
+        direction, count = "tail", tail  # type: ignore[assignment]
+        before_ts = before
+    elif has_head:
+        direction, count = "head", head  # type: ignore[assignment]
+    elif has_tail:
+        direction, count = "tail", tail  # type: ignore[assignment]
+    elif has_after:
         direction, count = "head", DEFAULT_CURSOR_PAGE
         after_ts = after
-    elif before is not None:
+    elif has_before:
         direction, count = "tail", DEFAULT_CURSOR_PAGE
         before_ts = before
     else: