feat(plugin): council assembly animation with staggered specialist arrival (#1441)

- Add council_animator.py: staggered typing animation for council scene
  rendering to stderr, with per-agent delay for dramatic "assembling" effect
- Wire into user-prompt-submit.py: animate council on mode entry
  (PLAN/EVAL/AUTO) when council preset exists
- Graceful degradation: static output when stderr is not a TTY
- Configurable via CODINGBUDDY_COUNCIL_ANIMATION env (on/off/1/0)
- Total animation < 2 seconds for typical 4-agent council
- 18 tests covering build_lines, static render, animation toggle, env config

Closes #1441

Author: JeremyDev87

packages/claude-code-plugin/hooks/lib/council_animator.py

@@ -0,0 +1,113 @@
+"""Council Assembly Animation — staggered specialist arrival effect (#1441).
+
+Renders council specialists one-by-one with typing animation to stderr,
+creating a dramatic "assembling the team" moment. Degrades gracefully
+to static output when stderr is not a TTY or animation is disabled.
+"""
+import os
+import sys
+import time
+from typing import List, Optional
+
+# Per-agent delay in seconds (total < 2s for typical 4-agent council)
+DEFAULT_AGENT_DELAY = 0.15
+DEFAULT_CHAR_SPEED = 0.02
+
+# Environment variable to disable animation
+ANIMATION_ENV = "CODINGBUDDY_COUNCIL_ANIMATION"
+
+
+def animate_council_assembly(
+    primary: str,
+    specialists: List[str],
+    moderator_copy: str = "Council assembled.",
+    agent_delay: float = DEFAULT_AGENT_DELAY,
+    char_speed: float = DEFAULT_CHAR_SPEED,
+) -> str:
+    """Render council assembly with staggered animation to stderr.
+
+    When stderr is a TTY and animation is enabled, agents appear
+    one-by-one with a typing effect. Otherwise, falls back to
+    static rendering returned as a string.
+
+    Args:
+        primary: Primary agent name.
+        specialists: List of specialist agent names.
+        moderator_copy: Moderator greeting text.
+        agent_delay: Delay between agents in seconds.
+        char_speed: Delay between characters for typing effect.
+
+    Returns:
+        The full rendered council scene as a string (for logging/testing).
+    """
+    lines = _build_lines(primary, specialists, moderator_copy)
+    full_text = "\n".join(lines)
+
+    if _should_animate():
+        _animate_to_stderr(lines, agent_delay, char_speed)
+    else:
+        sys.stderr.write(full_text + "\n")
+        sys.stderr.flush()
+
+    return full_text
+
+
+def render_council_static(
+    primary: str,
+    specialists: List[str],
+    moderator_copy: str = "Council assembled.",
+) -> str:
+    """Render council scene as static text (no animation).
+
+    Args:
+        primary: Primary agent name.
+        specialists: List of specialist agent names.
+        moderator_copy: Moderator greeting text.
+
+    Returns:
+        Formatted council scene string.
+    """
+    return "\n".join(_build_lines(primary, specialists, moderator_copy))
+
+
+def _build_lines(
+    primary: str,
+    specialists: List[str],
+    moderator_copy: str,
+) -> List[str]:
+    """Build the council scene lines."""
+    lines = []
+    lines.append(f"  \u25d5\u203f\u25d5 {moderator_copy}")  # ◕‿◕ buddy face
+    lines.append(f"  \u25b6 {primary} [primary]")
+    for spec in specialists:
+        lines.append(f"  \u25cb {spec} [specialist]")
+    lines.append("  \u2501\u2501 Council assembled \u2501\u2501")
+    return lines
+
+
+def _should_animate() -> bool:
+    """Check if animation should be enabled."""
+    env_value = os.environ.get(ANIMATION_ENV, "").lower()
+    if env_value == "0" or env_value == "false" or env_value == "off":
+        return False
+    if env_value == "1" or env_value == "true" or env_value == "on":
+        return True
+    # Default: animate only if stderr is a TTY
+    return hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+
+
+def _animate_to_stderr(
+    lines: List[str],
+    agent_delay: float,
+    char_speed: float,
+) -> None:
+    """Write lines to stderr with staggered typing effect."""
+    for i, line in enumerate(lines):
+        for char in line:
+            sys.stderr.write(char)
+            sys.stderr.flush()
+            time.sleep(char_speed)
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+        if i < len(lines) - 1:
+            time.sleep(agent_delay)

packages/claude-code-plugin/hooks/tests/test_council_animator.py

@@ -0,0 +1,139 @@
+"""Tests for council_animator module (#1441)."""
+import os
+import sys
+
+import pytest
+
+# Add lib to path
+_hooks_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_lib_dir = os.path.join(_hooks_dir, "lib")
+if _lib_dir not in sys.path:
+    sys.path.insert(0, _lib_dir)
+
+from council_animator import (
+    animate_council_assembly,
+    render_council_static,
+    _build_lines,
+    _should_animate,
+    ANIMATION_ENV,
+)
+
+
+class TestBuildLines:
+    def test_includes_buddy_face(self):
+        lines = _build_lines("planner", ["security"], "Let's go.")
+        assert any("\u25d5\u203f\u25d5" in line for line in lines)
+
+    def test_includes_primary_agent(self):
+        lines = _build_lines("technical-planner", ["security"], "Go.")
+        assert any("technical-planner" in line and "[primary]" in line for line in lines)
+
+    def test_includes_specialists(self):
+        lines = _build_lines("planner", ["security-specialist", "performance-specialist"], "Go.")
+        specialist_lines = [l for l in lines if "[specialist]" in l]
+        assert len(specialist_lines) == 2
+        assert any("security-specialist" in l for l in specialist_lines)
+        assert any("performance-specialist" in l for l in specialist_lines)
+
+    def test_ends_with_assembled_line(self):
+        lines = _build_lines("planner", ["security"], "Go.")
+        assert "Council assembled" in lines[-1]
+
+    def test_moderator_copy_in_first_line(self):
+        lines = _build_lines("planner", [], "Time for a checkup.")
+        assert "Time for a checkup." in lines[0]
+
+    def test_empty_specialists(self):
+        lines = _build_lines("planner", [], "Go.")
+        assert len(lines) == 3  # buddy, primary, assembled
+
+
+class TestRenderCouncilStatic:
+    def test_returns_string(self):
+        result = render_council_static("planner", ["security"], "Go.")
+        assert isinstance(result, str)
+
+    def test_contains_all_agents(self):
+        result = render_council_static("planner", ["sec", "perf", "a11y"], "Go.")
+        assert "planner" in result
+        assert "sec" in result
+        assert "perf" in result
+        assert "a11y" in result
+
+    def test_multiline_output(self):
+        result = render_council_static("planner", ["security"], "Go.")
+        assert "\n" in result
+
+
+class TestShouldAnimate:
+    @pytest.fixture(autouse=True)
+    def cleanup_env(self):
+        original = os.environ.get(ANIMATION_ENV)
+        yield
+        if original is not None:
+            os.environ[ANIMATION_ENV] = original
+        elif ANIMATION_ENV in os.environ:
+            del os.environ[ANIMATION_ENV]
+
+    def test_disabled_with_env_0(self):
+        os.environ[ANIMATION_ENV] = "0"
+        assert _should_animate() is False
+
+    def test_disabled_with_env_false(self):
+        os.environ[ANIMATION_ENV] = "false"
+        assert _should_animate() is False
+
+    def test_disabled_with_env_off(self):
+        os.environ[ANIMATION_ENV] = "off"
+        assert _should_animate() is False
+
+    def test_enabled_with_env_1(self):
+        os.environ[ANIMATION_ENV] = "1"
+        assert _should_animate() is True
+
+    def test_enabled_with_env_true(self):
+        os.environ[ANIMATION_ENV] = "true"
+        assert _should_animate() is True
+
+    def test_default_depends_on_tty(self):
+        if ANIMATION_ENV in os.environ:
+            del os.environ[ANIMATION_ENV]
+        # In test environment, stderr is typically not a TTY
+        result = _should_animate()
+        expected = hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+        assert result == expected
+
+
+class TestAnimateCouncilAssembly:
+    def test_returns_full_text(self, capsys):
+        os.environ[ANIMATION_ENV] = "0"  # Disable animation for speed
+        result = animate_council_assembly(
+            "technical-planner",
+            ["security-specialist", "performance-specialist"],
+            "Let's map it out.",
+            agent_delay=0,
+            char_speed=0,
+        )
+        assert "technical-planner" in result
+        assert "security-specialist" in result
+        assert "performance-specialist" in result
+        assert "Let's map it out." in result
+        assert "Council assembled" in result
+        os.environ.pop(ANIMATION_ENV, None)
+
+    def test_static_mode_writes_to_stderr(self, capsys):
+        os.environ[ANIMATION_ENV] = "0"
+        animate_council_assembly(
+            "planner", ["security"], "Go.",
+            agent_delay=0, char_speed=0,
+        )
+        captured = capsys.readouterr()
+        assert captured.out == ""  # Nothing to stdout
+        os.environ.pop(ANIMATION_ENV, None)
+
+    def test_handles_empty_specialists(self):
+        os.environ[ANIMATION_ENV] = "0"
+        result = animate_council_assembly("planner", [], "Go.", agent_delay=0, char_speed=0)
+        assert "planner" in result
+        assert "Council assembled" in result
+        os.environ.pop(ANIMATION_ENV, None)

packages/claude-code-plugin/hooks/user-prompt-submit.py

@@ -165,6 +165,21 @@ def main():
             except Exception:
                 pass
 
+            # Council Assembly Animation: staggered specialist arrival (#1441)
+            try:
+                if council_preset and isinstance(council_preset, dict):
+                    from council_animator import animate_council_assembly
+
+                    animate_council_assembly(
+                        primary=council_preset.get("primary", ""),
+                        specialists=council_preset.get("specialists", []),
+                        moderator_copy=council_preset.get(
+                            "moderator_copy", "Council assembled."
+                        ),
+                    )
+            except Exception:
+                pass  # Never block prompt submission
+
             # Agent Council Memory: inject prior findings for specialists (#1435)
             try:
                 from agent_memory import AgentMemory