tagteam 0.3.0__py3-none-any.whl

tagteam/__init__.py

@@ -0,0 +1,13 @@
+"""
+Tagteam
+
+A collaboration framework for structured AI-to-AI handoffs with human oversight.
+Configure your lead and reviewer agents via tagteam.yaml.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("tagteam")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

tagteam/__main__.py

@@ -0,0 +1,6 @@
+"""CLI entrypoint for python -m tagteam"""
+import sys
+from tagteam.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tagteam/cli.py

@@ -0,0 +1,418 @@
+"""
+CLI for Tagteam.
+
+Usage:
+    python -m tagteam init        - Initialize agent configuration
+    python -m tagteam setup [dir] - Copy framework files to a project
+    python -m tagteam migrate     - Migrate legacy projects to use config
+    python -m tagteam watch       - Start the watcher daemon
+    python -m tagteam state       - View/update orchestration state
+    python -m tagteam session     - Manage orchestration sessions
+    python -m tagteam serve       - Start the web dashboard server
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from tagteam.config import read_config
+
+
+CONFIG_TEMPLATE = """# Tagteam Configuration
+# Defines the two AI agents and their roles in the collaboration workflow.
+
+agents:
+  lead:
+    name: {lead_name}
+  reviewer:
+    name: {reviewer_name}
+"""
+
+HANDOFF_EXPLAINER = """
+How the handoff works:
+
+  Lead (one AI agent) plans each phase and implements the approved plan.
+  Reviewer (a second AI agent) reviews both the plan and the implementation.
+  Arbiter (you, the human) breaks ties and approves phases.
+
+Work progresses phase-by-phase. Each phase is listed in docs/roadmap.md and
+goes through two review cycles: plan, then implementation. If the two agents
+can't make progress in 10 rounds, control escalates to the human arbiter.
+
+State is tracked in handoff-state.json (current turn) and
+docs/handoffs/<phase>_<type>_rounds.jsonl plus <phase>_<type>_status.json
+(per-cycle rounds). Either agent can pick up where the other left off at
+any time.
+"""
+
+GETTING_STARTED = """
+Getting Started
+===============
+Start a session with agents and watcher (run from project root):
+
+  tagteam session start
+
+If you are on Windows or another unsupported platform, use the manual backend:
+
+  tagteam session start --backend manual
+  tagteam watch --mode notify
+
+Or use quickstart (runs setup + init + session with backend auto-detection):
+
+  tagteam quickstart
+"""
+
+
+def prompt_input(
+    prompt: str,
+    valid_options: list[str] | None = None,
+    lowercase: bool = True,
+) -> str:
+    """Get user input with optional validation."""
+    while True:
+        raw_value = input(prompt).strip()
+        if not raw_value:
+            print("  Please enter a value.")
+            continue
+
+        check_value = raw_value.lower()
+        if valid_options and check_value not in valid_options:
+            print(f"  Please enter one of: {', '.join(valid_options)}")
+            continue
+
+        return check_value if lowercase else raw_value
+
+
+def write_config(target_dir: str, lead_name: str, reviewer_name: str) -> Path:
+    """Write tagteam.yaml to target_dir. Non-interactive."""
+    config_path = Path(target_dir) / "tagteam.yaml"
+    config_content = CONFIG_TEMPLATE.format(
+        lead_name=lead_name,
+        reviewer_name=reviewer_name,
+    )
+    config_path.write_text(config_content, encoding="utf-8")
+    return config_path
+
+
+def needs_init(project_dir: str = ".") -> bool:
+    """Check if agent configuration is needed."""
+    return not (Path(project_dir) / "tagteam.yaml").exists()
+
+
+def run_init(project_dir: str = ".", show_explainer: bool = False) -> bool:
+    """Run interactive init if config is missing. Requires TTY.
+
+    show_explainer=False by default so callers like quickstart can print the
+    explainer themselves exactly once. Standalone CLI dispatch passes True.
+    """
+    if not needs_init(project_dir):
+        print("Agent configuration already exists; skipping init.")
+        return True
+
+    if not sys.stdin.isatty():
+        print("Error: No tagteam.yaml found and stdin is not interactive.")
+        print("  Run 'tagteam init' interactively first.")
+        return False
+
+    import os
+
+    original_dir = os.getcwd()
+    try:
+        os.chdir(project_dir)
+        init_command(show_explainer=show_explainer)
+    finally:
+        os.chdir(original_dir)
+    return True
+
+
+def init_command(show_explainer: bool = True) -> int:
+    """Interactive init command to create tagteam.yaml.
+
+    Prompts for two agent names: lead first, reviewer second. No role prompt —
+    order defines role.
+    """
+    config_path = Path("tagteam.yaml")
+
+    print()
+    print("Tagteam Setup")
+    print("================")
+    print("This framework coordinates work between two AI agents.")
+    print()
+
+    if config_path.exists():
+        existing = read_config(config_path)
+        if existing:
+            agents = existing.get("agents", {})
+            lead = agents.get("lead", {}).get("name", "unknown")
+            reviewer = agents.get("reviewer", {}).get("name", "unknown")
+
+            print("tagteam.yaml already exists with:")
+            print(f"  Lead: {lead}")
+            print(f"  Reviewer: {reviewer}")
+        else:
+            print("tagteam.yaml already exists but could not be parsed.")
+            print("(File may be empty or malformed)")
+
+        print()
+        overwrite = prompt_input("Overwrite? (y/n): ", ["y", "n", "yes", "no"])
+        if overwrite not in ["y", "yes"]:
+            print("Aborted.")
+            return 0
+        print()
+
+    print("Enter the names of your two AI agents (first is Lead, second is Reviewer).")
+    print()
+
+    lead_name = prompt_input("Lead agent name: ", lowercase=False)
+    reviewer_name = prompt_input("Reviewer agent name: ", lowercase=False)
+    print()
+
+    write_config(".", lead_name, reviewer_name)
+
+    print("Created tagteam.yaml")
+    print(f"  Lead: {lead_name}")
+    print(f"  Reviewer: {reviewer_name}")
+
+    if show_explainer:
+        print(HANDOFF_EXPLAINER)
+    print(GETTING_STARTED)
+    return 0
+
+
+def setup_command(target_dir: str = ".") -> int:
+    """Copy framework files to target directory."""
+    from tagteam.setup import main as setup_main
+
+    setup_main(target_dir)
+    return 0
+
+
+_BACKEND_SURFACE = {
+    "iterm2": "tab",
+    "tmux": "pane",
+    "manual": "terminal",
+}
+
+
+def _print_priming_box(lead_name: str, reviewer_name: str, surface: str) -> None:
+    """Print a boxed 'SESSION READY' message with backend-appropriate terminology."""
+    prime_body = (
+        "Read tagteam.yaml and .claude/skills/handoff/"
+        "SKILL.md, then type /handoff"
+    )
+    lines = [
+        "SESSION READY",
+        "",
+        f"In the Lead {surface}, tell {lead_name}:",
+        f'  "{prime_body}"',
+        "",
+        f"In the Reviewer {surface}, tell {reviewer_name} the same.",
+    ]
+    width = max(len(line) for line in lines) + 4
+    print("╔" + "═" * (width - 2) + "╗")
+    for line in lines:
+        print("║ " + line.ljust(width - 4) + " ║")
+    print("╚" + "═" * (width - 2) + "╝")
+
+
+def quickstart_command(args: list[str]) -> int:
+    """Run setup + init + session start in one command."""
+    from tagteam.session import SUPPORTED_BACKENDS, default_backend, ensure_session
+    from tagteam.setup import run_setup
+
+    project_dir = "."
+    backend = None
+    i = 0
+    while i < len(args):
+        if args[i] == "--dir" and i + 1 < len(args):
+            project_dir = args[i + 1]
+            i += 2
+        elif args[i] == "--backend" and i + 1 < len(args):
+            backend = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    if backend is not None and backend not in SUPPORTED_BACKENDS:
+        print(f"Invalid backend: {backend}. Use 'iterm2', 'tmux', or 'manual'.")
+        return 1
+
+    project_dir = str(Path(project_dir).resolve())
+
+    print("Tagteam - Quick Start")
+    print("========================")
+    print(f"Project: {project_dir}")
+    print()
+
+    print("[1/3] Framework setup...")
+    run_setup(project_dir)
+    print()
+
+    print("[2/3] Agent configuration...")
+    if not run_init(project_dir, show_explainer=False):
+        return 1
+    print()
+
+    print("[3/3] Starting session...")
+    outcome = ensure_session(project_dir, backend, launch=True)
+    if outcome == "error":
+        return 1
+
+    effective_backend = backend or default_backend()
+    surface = _BACKEND_SURFACE.get(effective_backend, "terminal")
+
+    config = read_config(Path(project_dir) / "tagteam.yaml") or {}
+    agents = config.get("agents", {})
+    lead_name = agents.get("lead", {}).get("name", "Lead")
+    reviewer_name = agents.get("reviewer", {}).get("name", "Reviewer")
+
+    print(HANDOFF_EXPLAINER)
+
+    if outcome == "exists":
+        print("Session already running. Switch to it to continue.")
+        return 0
+
+    _print_priming_box(lead_name, reviewer_name, surface)
+    return 0
+
+
+def upgrade_command() -> int:
+    """Re-run setup on all registered projects."""
+    from tagteam.registry import get_registered_projects
+    from tagteam.setup import main as setup_main
+
+    projects = get_registered_projects()
+
+    if not projects:
+        print("No registered projects found.")
+        print()
+        print("Projects are registered automatically when you run 'tagteam setup'.")
+        print("Run 'tagteam setup <dir>' in each project directory first.")
+        return 0
+
+    print(f"Upgrading {len(projects)} registered project(s)...")
+    print()
+
+    failed = []
+    for project_dir in projects:
+        print("=" * 60)
+        print(f"Project: {project_dir}")
+        print("=" * 60)
+        try:
+            setup_main(project_dir)
+        except Exception as exc:
+            print(f"  ERROR: {exc}")
+            failed.append(project_dir)
+        print()
+
+    if failed:
+        print(f"Completed with {len(failed)} error(s):")
+        for project_dir in failed:
+            print(f"  - {project_dir}")
+        return 1
+
+    print(f"All {len(projects)} project(s) upgraded successfully.")
+    return 0
+
+
+HELP_TEXT = """\
+Tagteam
+
+Usage: tagteam <command>
+
+Quick start (from project root):
+  tagteam quickstart
+
+  This runs setup, agent configuration, and session start in one command.
+  The session backend is auto-detected unless you pass --backend.
+
+Commands:
+  quickstart    Setup + init + session start in one command
+  init          Create tagteam.yaml configuration interactively
+  setup [dir]   Copy framework files to a project directory
+  session       Manage orchestration session (start/kill/attach)
+  watch         Start the watcher daemon for automated orchestration
+  state         View or update the orchestration state file
+  roadmap       Query roadmap phases and build execution queue
+  cycle         Manage cycle documents (init, add, status, rounds, render)
+  serve         Start the web dashboard server
+  tui           Launch the Handoff Saloon terminal UI
+  migrate       Migrate legacy projects to use tagteam.yaml
+  upgrade       Re-run setup on all registered projects (after pip upgrade)
+
+Advanced setup (individual steps, from project root):
+  tagteam setup
+  tagteam init
+  tagteam session start
+
+Manual workflow fallback:
+  tagteam session start --backend manual
+  tagteam watch --mode notify
+"""
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    if len(sys.argv) < 2:
+        print(HELP_TEXT)
+        return 1
+
+    command = sys.argv[1].lower()
+
+    if command == "quickstart":
+        return quickstart_command(sys.argv[2:])
+    if command == "init":
+        return init_command()
+    if command == "setup":
+        target = sys.argv[2] if len(sys.argv) > 2 else "."
+        return setup_command(target)
+    if command == "migrate":
+        from tagteam.migrate import migrate_command
+
+        return migrate_command(sys.argv[2:])
+    if command == "watch":
+        from tagteam.watcher import watch_command
+
+        return watch_command(sys.argv[2:])
+    if command == "roadmap":
+        from tagteam.roadmap import roadmap_command
+
+        return roadmap_command(sys.argv[2:])
+    if command == "cycle":
+        from tagteam.cycle import cycle_command
+
+        return cycle_command(sys.argv[2:])
+    if command == "state":
+        from tagteam.state import state_command
+
+        return state_command(sys.argv[2:])
+    if command == "session":
+        from tagteam.session import session_command
+
+        return session_command(sys.argv[2:])
+    if command == "serve":
+        from tagteam.server import serve_command
+
+        return serve_command(sys.argv[2:])
+    if command == "tui":
+        try:
+            from tagteam.tui import tui_command
+        except ImportError:
+            print("The TUI requires the 'textual' package.")
+            print("Install it with: pip install tagteam[tui]")
+            return 1
+        return tui_command(sys.argv[2:])
+    if command == "upgrade":
+        return upgrade_command()
+    if command in ["-h", "--help", "help"]:
+        print(HELP_TEXT)
+        return 0
+
+    print(f"Unknown command: {command}")
+    print("Run 'tagteam --help' for usage.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tagteam/config.py

@@ -0,0 +1,185 @@
+"""
+Centralized configuration handling for Tagteam.
+
+This module provides a single source of truth for reading and validating
+tagteam.yaml configuration files.
+"""
+
+from pathlib import Path
+
+# PyYAML is optional
+try:
+    import yaml
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+
+def read_config(config_path: Path | str) -> dict | None:
+    """Read and parse tagteam.yaml.
+
+    Args:
+        config_path: Path to config file
+
+    Returns:
+        Parsed config dict, or None if file doesn't exist or is invalid
+    """
+    path = Path(config_path)
+    if not path.exists():
+        return None
+
+    try:
+        content = path.read_text(encoding="utf-8")
+        if HAS_YAML:
+            result = yaml.safe_load(content)
+            # Only return if it's a dict (not [], "foo", or other valid YAML)
+            return result if isinstance(result, dict) else None
+
+        # Fallback parsing without PyYAML
+        lead_name = None
+        reviewer_name = None
+        lead_command = None
+        reviewer_command = None
+        lines = content.split('\n')
+        for i, line in enumerate(lines):
+            if 'lead:' in line:
+                for j in range(i + 1, min(i + 4, len(lines))):
+                    sub = lines[j]
+                    if 'name:' in sub:
+                        lead_name = sub.split('name:')[1].strip()
+                    elif 'command:' in sub:
+                        lead_command = sub.split('command:')[1].strip()
+                    elif not sub.startswith(' ') and not sub.startswith('\t'):
+                        break
+            elif 'reviewer:' in line:
+                for j in range(i + 1, min(i + 4, len(lines))):
+                    sub = lines[j]
+                    if 'name:' in sub:
+                        reviewer_name = sub.split('name:')[1].strip()
+                    elif 'command:' in sub:
+                        reviewer_command = sub.split('command:')[1].strip()
+                    elif not sub.startswith(' ') and not sub.startswith('\t'):
+                        break
+        if lead_name and reviewer_name:
+            result = {'agents': {
+                'lead': {'name': lead_name},
+                'reviewer': {'name': reviewer_name},
+            }}
+            if lead_command:
+                result['agents']['lead']['command'] = lead_command
+            if reviewer_command:
+                result['agents']['reviewer']['command'] = reviewer_command
+            return result
+    except Exception:
+        pass
+    return None
+
+
+def validate_config(config: dict) -> list[str]:
+    """Validate tagteam.yaml structure.
+
+    Args:
+        config: Parsed config dict
+
+    Returns:
+        List of error messages (empty if valid)
+    """
+    errors = []
+
+    if not isinstance(config, dict):
+        return ["Config must be a YAML mapping"]
+
+    agents = config.get("agents")
+    if not isinstance(agents, dict):
+        errors.append("Missing 'agents' section")
+        return errors
+
+    # Validate lead
+    lead = agents.get("lead")
+    if not isinstance(lead, dict) or not lead.get("name"):
+        errors.append("Missing or invalid 'agents.lead.name'")
+
+    # Validate reviewer
+    reviewer = agents.get("reviewer")
+    if not isinstance(reviewer, dict) or not reviewer.get("name"):
+        errors.append("Missing or invalid 'agents.reviewer.name'")
+
+    # Validate command if present
+    for role in ["lead", "reviewer"]:
+        agent = agents.get(role, {})
+        if isinstance(agent, dict):
+            command = agent.get("command")
+            if command is not None and not isinstance(command, str):
+                errors.append(f"'agents.{role}.command' must be a string")
+            elif isinstance(command, str) and not command.strip():
+                errors.append(f"'agents.{role}.command' is empty")
+
+    # Validate model_patterns if present
+    all_patterns: list[tuple[str, list[str]]] = []
+    for role in ["lead", "reviewer"]:
+        agent = agents.get(role, {})
+        if not isinstance(agent, dict):
+            continue
+        patterns = agent.get("model_patterns")
+        if patterns is not None:
+            if not isinstance(patterns, list):
+                errors.append(f"'agents.{role}.model_patterns' must be a list")
+            elif not all(isinstance(p, str) and p for p in patterns):
+                errors.append(f"'agents.{role}.model_patterns' must contain non-empty strings")
+            else:
+                all_patterns.append((role, [p.lower() for p in patterns]))
+
+    # Check for pattern overlap (error, not warning)
+    if len(all_patterns) == 2:
+        role1, patterns1 = all_patterns[0]
+        role2, patterns2 = all_patterns[1]
+        for p1 in patterns1:
+            for p2 in patterns2:
+                if p1 in p2 or p2 in p1:
+                    errors.append(
+                        f"Pattern overlap: '{p1}' ({role1}) and '{p2}' ({role2}) "
+                        f"could match the same model identifier"
+                    )
+
+    return errors
+
+
+def get_launch_commands(config: dict) -> tuple[str, str]:
+    """Extract launch commands for lead and reviewer agents.
+
+    Uses the optional 'command' field from each agent config,
+    falling back to the lowercase agent name.
+
+    Args:
+        config: Parsed config dict
+
+    Returns:
+        (lead_command, reviewer_command) tuple
+    """
+    agents = config.get("agents", {})
+    lead = agents.get("lead", {}) if isinstance(agents.get("lead"), dict) else {}
+    reviewer = agents.get("reviewer", {}) if isinstance(agents.get("reviewer"), dict) else {}
+
+    lead_cmd = lead.get("command") or (lead.get("name") or "claude").lower()
+    reviewer_cmd = reviewer.get("command") or (reviewer.get("name") or "codex").lower()
+
+    return lead_cmd, reviewer_cmd
+
+
+def get_agent_names(config: dict) -> tuple[str | None, str | None]:
+    """Extract lead and reviewer names from config.
+
+    Args:
+        config: Parsed config dict
+
+    Returns:
+        (lead_name, reviewer_name) tuple, with None for missing values
+    """
+    agents = config.get("agents", {})
+    lead = agents.get("lead", {})
+    reviewer = agents.get("reviewer", {})
+
+    lead_name = lead.get("name") if isinstance(lead, dict) else None
+    reviewer_name = reviewer.get("name") if isinstance(reviewer, dict) else None
+
+    return lead_name, reviewer_name