feat: Phase 2 — AG2 agent shell (Planner/Builder/Verifier over Ollama)

New package: src/specsmith/agents/
- agents/config.py: AgentConfig loaded from scaffold.yml agents: key
- agents/tools/filesystem.py: read, write, patch, list_tree, search (pathlib)
- agents/tools/shell.py: run_project_command with structured output
- agents/tools/git.py: status, diff, changed_files, branch_info
- agents/tools/tests.py: run_unit_tests, summarize_failures
- agents/roles.py: Planner/Builder/Verifier with AG2 ConversableAgent
- agents/cli.py: specsmith agent run/plan/status/verify commands
- cli.py: wire agent command group into main CLI

Dependencies: ag2[ollama] added as optional extra in pyproject.toml
AG2 uses native Ollama tool calling, hide_tools=if_any_run

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

pyproject.toml

@@ -65,6 +65,8 @@ openai = ["openai>=1.0"]
 gemini = ["google-genai>=1.0"]
 mistral = ["openai>=1.0"]  # Mistral uses the openai SDK pointed at api.mistral.ai
 gui = ["PySide6>=6.6"]
+# AG2 agent shell (Planner/Builder/Verifier over Ollama)
+ag2 = ["ag2[ollama]"]
 # Install all optional LLM providers
 agent = ["anthropic>=0.56", "openai>=1.0"]
 # Convenience bundle: everything

src/specsmith/agents/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""specsmith AG2 agent shell — Planner/Builder/Verifier over Ollama."""
+
+from specsmith.agents.config import AgentConfig, load_agent_config
+
+__all__ = ["AgentConfig", "load_agent_config"]

src/specsmith/agents/cli.py

@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""CLI commands for the AG2 agent shell.
+
+Wired into the main specsmith CLI as the ``agent`` command group.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.group()
+def agent() -> None:
+    """AG2 agent shell — Planner/Builder/Verifier over Ollama."""
+
+
+@agent.command()
+@click.argument("task")
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=6, help="Maximum conversation turns per agent.")
+def run(task: str, project_dir: str, max_turns: int) -> None:
+    """Execute a task through the full Planner → Builder → Verifier pipeline."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401 — verify AG2 is installed
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.config import load_agent_config
+    from specsmith.agents.roles import create_builder, create_planner, create_verifier
+
+    project_dir = str(Path(project_dir).resolve())
+    config = load_agent_config(project_dir)
+
+    console.print(
+        f"\n[bold cyan]specsmith agent shell[/bold cyan] — {config.primary_model} via Ollama"
+    )
+    console.print(f"Task: [bold]{task}[/bold]\n")
+
+    # Phase 1: Plan
+    console.print("[dim]─── Phase 1: Planning ───[/dim]")
+    planner = create_planner(config, project_dir)
+    plan_result = planner.run(message=f"Plan this task:\n{task}", max_turns=max_turns)
+    plan_result.process()
+
+    plan_text = ""
+    for msg in plan_result.messages:
+        if msg.get("role") == "assistant" and msg.get("content"):
+            plan_text = msg["content"]
+
+    if not plan_text:
+        console.print("[yellow]Planner produced no output.[/yellow]")
+        return
+
+    # Phase 2: Build
+    console.print("\n[dim]─── Phase 2: Building ───[/dim]")
+    builder = create_builder(config, project_dir)
+    build_result = builder.run(
+        message=f"Execute this plan:\n\n{plan_text}",
+        max_turns=max_turns,
+    )
+    build_result.process()
+
+    build_text = ""
+    for msg in build_result.messages:
+        if msg.get("role") == "assistant" and msg.get("content"):
+            build_text = msg["content"]
+
+    # Phase 3: Verify
+    console.print("\n[dim]─── Phase 3: Verifying ───[/dim]")
+    verifier = create_verifier(config, project_dir)
+    verify_result = verifier.run(
+        message=(
+            f"Verify the following changes:\n\n{build_text}"
+            "\n\nRun the relevant tests and report ACCEPT or REJECT."
+        ),
+        max_turns=max_turns,
+    )
+    verify_result.process()
+
+    # Summary
+    console.print("\n[bold cyan]─── Done ───[/bold cyan]")
+    for msg in verify_result.messages:
+        if msg.get("role") == "assistant" and msg.get("content"):
+            content = msg["content"]
+            if "ACCEPT" in content.upper():
+                console.print("[bold green]✓ ACCEPTED[/bold green]")
+            elif "REJECT" in content.upper():
+                console.print("[bold red]✗ REJECTED[/bold red]")
+            break
+
+
+@agent.command()
+@click.argument("task")
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=6, help="Maximum conversation turns.")
+def plan(task: str, project_dir: str, max_turns: int) -> None:
+    """Generate a plan without executing it."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.config import load_agent_config
+    from specsmith.agents.roles import create_planner
+
+    project_dir = str(Path(project_dir).resolve())
+    config = load_agent_config(project_dir)
+
+    console.print(f"\n[bold cyan]specsmith agent plan[/bold cyan] — {config.primary_model}")
+    planner = create_planner(config, project_dir)
+    result = planner.run(message=f"Plan this task:\n{task}", max_turns=max_turns)
+    result.process()
+
+
+@agent.command()
+@click.option("--project-dir", default=".", help="Project root directory.")
+def status(project_dir: str) -> None:
+    """Show agent configuration and Ollama status."""
+    from specsmith.agents.config import load_agent_config
+
+    config = load_agent_config(project_dir)
+    console.print("[bold]Agent Configuration[/bold]")
+    console.print(f"  Primary model:  {config.primary_model}")
+    console.print(f"  Utility model:  {config.utility_model}")
+    console.print(f"  Ollama URL:     {config.ollama_base_url}")
+    console.print(f"  Max iterations: {config.max_iterations}")
+    console.print(f"  Context length: {config.num_ctx}")
+    console.print(f"  Tools enabled:  {', '.join(config.tools_enabled)}")
+
+    # Check Ollama
+    try:
+        from specsmith.agent.providers.ollama import OllamaProvider
+
+        p = OllamaProvider(base_url=config.ollama_base_url)
+        if p.is_available():
+            console.print("  Ollama:         [green]running[/green]")
+        else:
+            console.print("  Ollama:         [red]not available[/red]")
+    except Exception:  # noqa: BLE001
+        console.print("  Ollama:         [yellow]unknown[/yellow]")
+
+
+@agent.command()
+@click.option("--project-dir", default=".", help="Project root directory.")
+@click.option("--max-turns", default=4, help="Maximum conversation turns.")
+def verify(project_dir: str, max_turns: int) -> None:
+    """Run the Verifier agent on the current project state."""
+    try:
+        from autogen import ConversableAgent  # noqa: F401
+    except ImportError:
+        console.print("[red]AG2 is not installed.[/red] Run: pip install ag2[ollama]")
+        raise SystemExit(1)  # noqa: B904
+
+    from specsmith.agents.config import load_agent_config
+    from specsmith.agents.roles import create_verifier
+
+    project_dir = str(Path(project_dir).resolve())
+    config = load_agent_config(project_dir)
+
+    console.print(f"\n[bold cyan]specsmith agent verify[/bold cyan] — {config.utility_model}")
+    verifier = create_verifier(config, project_dir)
+    result = verifier.run(
+        message=(
+            "Run the full test suite and report the current project health."
+            " Report ACCEPT or REJECT."
+        ),
+        max_turns=max_turns,
+    )
+    result.process()

src/specsmith/agents/config.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Agent configuration — loaded from scaffold.yml ``agents:`` key."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for the AG2 agent shell."""
+
+    primary_model: str = "qwen2.5:14b"
+    utility_model: str = "qwen2.5:7b"
+    ollama_base_url: str = "http://localhost:11434"
+    max_iterations: int = 10
+    stream: bool = False
+    num_ctx: int = 4096
+    tools_enabled: list[str] = field(
+        default_factory=lambda: ["filesystem", "shell", "git", "tests", "docs"]
+    )
+
+    def llm_config_dict(self, model: str | None = None) -> dict[str, Any]:
+        """Return an AG2-compatible LLM config dict for Ollama."""
+        return {
+            "model": model or self.primary_model,
+            "api_type": "ollama",
+            "client_host": self.ollama_base_url,
+            "stream": self.stream,
+            "num_ctx": self.num_ctx,
+            "native_tool_calls": True,
+            "hide_tools": "if_any_run",
+        }
+
+
+def load_agent_config(project_dir: str | Path) -> AgentConfig:
+    """Load agent config from scaffold.yml ``agents:`` section.
+
+    Falls back to defaults if scaffold.yml doesn't exist or has no agents key.
+    """
+    scaffold_path = Path(project_dir) / "scaffold.yml"
+    if not scaffold_path.exists():
+        return AgentConfig()
+
+    try:
+        import yaml
+
+        with open(scaffold_path, encoding="utf-8") as f:
+            raw = yaml.safe_load(f) or {}
+        agents_raw = raw.get("agents", {}) or {}
+        return AgentConfig(
+            primary_model=agents_raw.get("primary_model", AgentConfig.primary_model),
+            utility_model=agents_raw.get("utility_model", AgentConfig.utility_model),
+            ollama_base_url=agents_raw.get("ollama_base_url", AgentConfig.ollama_base_url),
+            max_iterations=agents_raw.get("max_iterations", AgentConfig.max_iterations),
+            stream=agents_raw.get("stream", AgentConfig.stream),
+            num_ctx=agents_raw.get("num_ctx", AgentConfig.num_ctx),
+            tools_enabled=agents_raw.get("tools_enabled", AgentConfig().tools_enabled),
+        )
+    except Exception:  # noqa: BLE001
+        return AgentConfig()