feat: Phase 3 — self-improvement workflow + change reports

- agents/workflows/improve.py: run_improvement() executes full
  Plan→Build→Verify pipeline, produces ChangeReport with structured
  results (verdict, files changed, test counts, follow-up tasks)
- agents/reports.py: ChangeReport dataclass, save/list at
  .specsmith/agent-reports/<task_id>.json
- agents/cli.py: 'specsmith agent improve <task>' and
  'specsmith agent reports' commands

The improve workflow enforces: no silent edits, no skipping tests,
no accepting unclear failures, all changes produce artifacts.

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

Author: tbitcs

src/specsmith/agents/cli.py

@@ -175,3 +175,59 @@ def verify(project_dir: str, max_turns: int) -> None:
         max_turns=max_turns,
     )
     result.process()
+
+
+@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 improve(task: str, project_dir: str, max_turns: int) -> None:
+    """Run the self-improvement workflow (Plan → Build → Verify → Report)."""
+    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.workflows.improve import run_improvement
+
+    project_dir = str(Path(project_dir).resolve())
+    console.print("\n[bold cyan]specsmith agent improve[/bold cyan]")
+    console.print(f"Task: [bold]{task}[/bold]\n")
+
+    report = run_improvement(task, project_dir, max_turns=max_turns)
+
+    console.print(f"\n[bold]Report:[/bold] {report.summary}")
+    if report.verdict == "ACCEPT":
+        console.print("[bold green]✓ ACCEPTED[/bold green]")
+    elif report.verdict == "REJECT":
+        console.print("[bold red]✗ REJECTED[/bold red]")
+    else:
+        console.print(f"[yellow]Verdict: {report.verdict}[/yellow]")
+
+    if report.follow_up_tasks:
+        console.print("\n[bold]Follow-up tasks:[/bold]")
+        for ft in report.follow_up_tasks:
+            console.print(f"  - {ft}")
+
+    console.print(f"\n[dim]Report saved to .specsmith/agent-reports/{report.task_id}.json[/dim]")
+
+
+@agent.command()
+@click.option("--project-dir", default=".", help="Project root directory.")
+def reports(project_dir: str) -> None:
+    """List recent improvement reports."""
+    from specsmith.agents.reports import list_reports
+
+    all_reports = list_reports(project_dir)
+    if not all_reports:
+        console.print("[yellow]No improvement reports found.[/yellow]")
+        return
+
+    for r in all_reports[:10]:
+        icon = {
+            "accepted": "[green]✓[/green]",
+            "rejected": "[red]✗[/red]",
+            "failed": "[red]![/red]",
+        }.get(r.status, "[yellow]?[/yellow]")
+        console.print(f"  {icon} {r.task_id} — {r.summary}")

src/specsmith/agents/reports.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Change reports — structured artifacts from improvement runs.
+
+Every improvement run produces a ChangeReport stored as JSON at
+``.specsmith/agent-reports/<task_id>.json``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+@dataclass
+class ChangeReport:
+    """Structured output from an improvement run."""
+
+    task_id: str = ""
+    task_description: str = ""
+    project_dir: str = "."
+    status: str = "pending"  # pending, accepted, rejected, failed, unclear
+    verdict: str = ""  # ACCEPT, REJECT, UNCLEAR
+    plan: str = ""
+    build_output: str = ""
+    verify_output: str = ""
+    files_changed: list[str] = field(default_factory=list)
+    tests_run: int = 0
+    tests_passed: int = 0
+    tests_failed: int = 0
+    summary: str = ""
+    follow_up_tasks: list[str] = field(default_factory=list)
+    created: str = field(
+        default_factory=lambda: datetime.now(tz=timezone.utc).isoformat()
+    )
+
+    def to_dict(self) -> dict:
+        """Convert to a JSON-serializable dict (excludes verbose fields)."""
+        d = asdict(self)
+        # Truncate verbose fields for the summary view
+        for key in ("plan", "build_output", "verify_output"):
+            if len(d.get(key, "")) > 500:
+                d[key] = d[key][:500] + "...(truncated)"
+        return d
+
+
+def save_report(report: ChangeReport) -> Path:
+    """Save a change report to ``.specsmith/agent-reports/``."""
+    root = Path(report.project_dir).resolve()
+    reports_dir = root / ".specsmith" / "agent-reports"
+    reports_dir.mkdir(parents=True, exist_ok=True)
+    path = reports_dir / f"{report.task_id}.json"
+    path.write_text(
+        json.dumps(report.to_dict(), indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return path
+
+
+def list_reports(project_dir: str = ".") -> list[ChangeReport]:
+    """List all change reports, newest first."""
+    reports_dir = Path(project_dir).resolve() / ".specsmith" / "agent-reports"
+    if not reports_dir.exists():
+        return []
+    reports: list[ChangeReport] = []
+    for path in sorted(reports_dir.glob("*.json"), reverse=True):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            reports.append(ChangeReport(**{
+                k: v for k, v in data.items()
+                if k in ChangeReport.__dataclass_fields__
+            }))
+        except Exception:  # noqa: BLE001
+            pass
+    return reports

src/specsmith/agents/workflows/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""AG2 agent workflows — reusable task execution patterns."""

src/specsmith/agents/workflows/improve.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""improve_specsmith workflow — self-improvement loop.
+
+Executes: inspect repo → plan changes → edit code/docs → run tests →
+summarize → produce follow-up tasks.
+
+Constraints:
+- No silent edits (all changes produce artifacts)
+- No skipping tests
+- No accepting unclear failures
+- Verifier must approve before changes are accepted
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from specsmith.agents.config import AgentConfig, load_agent_config
+from specsmith.agents.reports import ChangeReport, save_report
+
+
+def run_improvement(
+    task: str,
+    project_dir: str,
+    max_turns: int = 6,
+    config: AgentConfig | None = None,
+) -> ChangeReport:
+    """Run the full improvement workflow on the specsmith codebase.
+
+    Returns a ChangeReport with results and follow-up tasks.
+    """
+    from specsmith.agents.roles import (
+        create_builder,
+        create_planner,
+        create_verifier,
+    )
+
+    if config is None:
+        config = load_agent_config(project_dir)
+
+    report = ChangeReport(
+        task_id=datetime.now(tz=timezone.utc).strftime("%Y%m%d_%H%M%S"),
+        task_description=task,
+        project_dir=project_dir,
+    )
+
+    # ── Phase 1: Plan ──────────────────────────────────────────────
+    planner = create_planner(config, project_dir)
+    plan_result = planner.run(
+        message=f"Plan this improvement task for the specsmith codebase:\n{task}",
+        max_turns=max_turns,
+    )
+    plan_result.process()
+
+    plan_text = _extract_last_assistant_message(plan_result.messages)
+    report.plan = plan_text
+
+    if not plan_text:
+        report.status = "failed"
+        report.summary = "Planner produced no output."
+        save_report(report)
+        return report
+
+    # ── Phase 2: Build ─────────────────────────────────────────────
+    builder = create_builder(config, project_dir)
+    build_result = builder.run(
+        message=f"Execute this plan on the specsmith codebase:\n\n{plan_text}",
+        max_turns=max_turns,
+    )
+    build_result.process()
+
+    build_text = _extract_last_assistant_message(build_result.messages)
+    report.build_output = build_text
+
+    # Extract files changed from build output
+    report.files_changed = _extract_files_from_output(build_text)
+
+    # ── Phase 3: Verify ────────────────────────────────────────────
+    verifier = create_verifier(config, project_dir)
+    verify_result = verifier.run(
+        message=(
+            f"Verify these changes to the specsmith codebase:\n\n"
+            f"{build_text}\n\n"
+            "Run the relevant tests. Report ACCEPT or REJECT with reasoning."
+        ),
+        max_turns=max_turns,
+    )
+    verify_result.process()
+
+    verify_text = _extract_last_assistant_message(verify_result.messages)
+    report.verify_output = verify_text
+
+    # Parse verdict
+    if "ACCEPT" in verify_text.upper():
+        report.status = "accepted"
+        report.verdict = "ACCEPT"
+    elif "REJECT" in verify_text.upper():
+        report.status = "rejected"
+        report.verdict = "REJECT"
+    else:
+        report.status = "unclear"
+        report.verdict = "UNCLEAR"
+
+    # Extract test results
+    report.tests_run, report.tests_passed, report.tests_failed = (
+        _extract_test_counts(verify_text)
+    )
+
+    # Generate follow-up tasks
+    report.follow_up_tasks = _extract_follow_ups(verify_text, build_text)
+    report.summary = _generate_summary(report)
+
+    save_report(report)
+    return report
+
+
+def _extract_last_assistant_message(messages: list[dict[str, Any]]) -> str:
+    """Get the last assistant message content from a conversation."""
+    for msg in reversed(messages):
+        if msg.get("role") == "assistant" and msg.get("content"):
+            return msg["content"]
+    return ""
+
+
+def _extract_files_from_output(text: str) -> list[str]:
+    """Heuristically extract file paths from builder output."""
+    import re
+
+    files: list[str] = []
+    # Match patterns like "Wrote X chars to path" or "Patched path"
+    pattern = r"(?:Wrote|Patched|Created|Modified)\s+.*?\s+(?:to\s+)?(\S+\.\w+)"
+    for match in re.finditer(pattern, text):
+        files.append(match.group(1))
+    # Match patterns like "- path/to/file.py" in lists
+    for match in re.finditer(r"^-\s+`?([a-zA-Z0-9_/\\.]+\.\w+)`?", text, re.MULTILINE):
+        if match.group(1) not in files:
+            files.append(match.group(1))
+    return files
+
+
+def _extract_test_counts(text: str) -> tuple[int, int, int]:
+    """Extract test run/pass/fail counts from verifier output."""
+    import re
+
+    # Match "N passed" pattern
+    passed_match = re.search(r"(\d+)\s+passed", text)
+    failed_match = re.search(r"(\d+)\s+failed", text)
+    passed = int(passed_match.group(1)) if passed_match else 0
+    failed = int(failed_match.group(1)) if failed_match else 0
+    return passed + failed, passed, failed
+
+
+def _extract_follow_ups(verify_text: str, build_text: str) -> list[str]:
+    """Extract follow-up tasks from agent output."""
+    follow_ups: list[str] = []
+    for text in [verify_text, build_text]:
+        for line in text.splitlines():
+            lower = line.lower().strip()
+            if lower.startswith(("- todo:", "- follow-up:", "- next:")):
+                follow_ups.append(line.strip().lstrip("- "))
+            elif "TODO" in line and ":" in line:
+                follow_ups.append(line.strip())
+    return follow_ups
+
+
+def _generate_summary(report: ChangeReport) -> str:
+    """Generate a human-readable summary of the improvement run."""
+    parts = [f"Task: {report.task_description}"]
+    parts.append(f"Verdict: {report.verdict}")
+    if report.files_changed:
+        parts.append(f"Files changed: {', '.join(report.files_changed)}")
+    if report.tests_run > 0:
+        parts.append(
+            f"Tests: {report.tests_passed}/{report.tests_run} passed"
+            + (f", {report.tests_failed} failed" if report.tests_failed else "")
+        )
+    if report.follow_up_tasks:
+        parts.append(f"Follow-ups: {len(report.follow_up_tasks)}")
+    return " | ".join(parts)