devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/cli/commands/setup.py

@@ -22,16 +22,19 @@ from devcouncil.cli.commands.integrate import (
     _codex_command,
     _configure_antigravity,
     _configure_cursor,
+    _configure_grok,
     _configure_native_hooks,
     _configure_opencode,
     _configure_warp,
     _configure,
-    _gemini_command,
 )
 from devcouncil.llm.provider import apply_provider_default_role_models, build_role_model_config, validate_model_provider
+from devcouncil.telemetry.stages import log_stage, log_step
+import logging
 
 app = typer.Typer()
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _set_model_provider(project_root: Path, provider: str) -> None:
@@ -180,7 +183,6 @@ def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_s
     console.print("[bold]Coding CLI integration[/bold]")
     commands = [
         ("Codex CLI", _codex_command(project_root)),
-        ("Gemini CLI", _gemini_command(project_root, gemini_scope)),
         ("Claude Code", _claude_command(project_root, "local")),
     ]
     results = []
@@ -190,6 +192,7 @@ def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_s
             continue
         results.append(_configure(tool, command, apply))
     results.append(_configure_cursor(project_root, apply))
+    results.append(_configure_grok(project_root, apply))
     results.append(_configure_opencode(project_root, apply))
     results.append(_configure_antigravity(project_root, apply))
     results.append(_configure_warp(project_root, apply))
@@ -261,6 +264,9 @@ def setup(
         raise typer.Exit(code=2)
 
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev setup: integrate=%s apply=%s", integrate, apply)
     try:
         role_models = parse_role_model_overrides(role_model)
         initial_provider = validate_model_provider(provider) if provider else "openrouter"
@@ -268,95 +274,99 @@ def setup(
         console.print(f"[red]{e}[/red]")
         raise typer.Exit(code=2) from e
 
-    # Size the default local model to the host's memory ceiling (unified RAM on Apple
-    # Silicon, VRAM on a discrete GPU, system RAM otherwise) instead of the static 7b,
-    # so users on any OS get a capable council out of the box. Only when the user chose
-    # Ollama and did not pin a model.
-    if initial_provider == "ollama" and model is None:
-        from devcouncil import hardware
-
-        host = hardware.describe_host()
-        model = host.recommended_ollama_model
-        console.print(
-            f"[green]Detected {host.chip_label} ({host.memory_label}); "
-            f"defaulting Ollama model to {model}.[/green] "
-            "Override with --model, and pull it first: "
-            f"[bold]ollama pull {model}[/bold]."
-        )
-    elif initial_provider == "ollama" and model is not None:
-        # Model pinned explicitly — still remind the user it must be pulled locally.
-        console.print(
-            f"[green]Using Ollama model {model}.[/green] "
-            f"Pull it first if needed: [bold]ollama pull {model}[/bold]."
+    with log_stage("setup", project_root=root, integrate=integrate):
+        log_step("setup/1: initializing project", project_root=root, trace=True)
+
+        # Size the default local model to the host's memory ceiling (unified RAM on Apple
+        # Silicon, VRAM on a discrete GPU, system RAM otherwise) instead of the static 7b,
+        # so users on any OS get a capable council out of the box. Only when the user chose
+        # Ollama and did not pin a model.
+        if initial_provider == "ollama" and model is None:
+            from devcouncil import hardware
+
+            host = hardware.describe_host()
+            model = host.recommended_ollama_model
+            console.print(
+                f"[green]Detected {host.chip_label} ({host.memory_label}); "
+                f"defaulting Ollama model to {model}.[/green] "
+                "Override with --model, and pull it first: "
+                f"[bold]ollama pull {model}[/bold]."
+            )
+        elif initial_provider == "ollama" and model is not None:
+            # Model pinned explicitly — still remind the user it must be pulled locally.
+            console.print(
+                f"[green]Using Ollama model {model}.[/green] "
+                f"Pull it first if needed: [bold]ollama pull {model}[/bold]."
+            )
+
+        created = initialize_project(
+            root,
+            project_name=name,
+            model_provider=initial_provider,
+            model=model,
+            role_models=role_models,
+            with_map=not skip_map,
+            with_skills=not skip_skills,
         )
-
-    created = initialize_project(
-        root,
-        project_name=name,
-        model_provider=initial_provider,
-        model=model,
-        role_models=role_models,
-        with_map=not skip_map,
-        with_skills=not skip_skills,
-    )
-    if not created:
-        console.print(f"[yellow]DevCouncil is already initialized at {root / '.devcouncil'}.[/yellow]")
-
-    if provider:
-        try:
-            _set_model_provider(root, provider)
-        except ValueError as e:
-            console.print(f"[red]{e}[/red]")
-            raise typer.Exit(code=2) from e
-
-    _set_model_roles(root, model=model, role_models=role_models)
-
-    configured_provider = load_config(root).models.provider
-    _configure_vertexai_settings(root, configured_provider, vertex_project, vertex_location)
-    _configure_api_key(root, api_key, skip_api_key)
-
-    console.print()
-    render_doctor_check(root)
-
-    if scaffold_ci:
-        from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, scaffold_ci as scaffold_ci_workflow
-
-        written = scaffold_ci_workflow(root)
-        if written is None:
-            console.print(f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists; left unchanged.[/yellow]")
-        else:
-            console.print(f"[green]Wrote starter CI workflow {written.relative_to(root).as_posix()}.[/green]")
-
-    if integrate:
-        _configure_coding_cli_integrations(root, apply=apply, gemini_scope=gemini_scope)
-    elif created and not skip_integrations:
-        _prompt_for_first_run_integrations(root, apply=True, gemini_scope=gemini_scope)
-
-    console.print()
-    console.print(Panel.fit(
-        "\n".join([
-            "[bold]Next commands[/bold]",
-            f"Keep running DevCouncil commands in this terminal at: {root}",
-            "One-command agent path:",
-            "dev e2e \"Describe the implementation goal\"",
-            "",
-            "Manual sidecar path:",
-            "dev plan \"Describe the implementation goal\"",
-            "dev tasks",
-            "dev run TASK-001 --executor manual",
-            "dev prompt TASK-001",
-            "Paste only the dev prompt output into your coding CLI.",
-            "Paste only the dev prompt output into your coding CLI, or run directly:",
-            "dev run TASK-001 --executor codex",
-            "dev run TASK-001 --executor gemini",
-            "dev run TASK-001 --executor claude",
-            "dev run TASK-001 --executor opencode",
-            "dev run TASK-001 --executor antigravity",
-            "dev verify TASK-001",
-            "",
-            "Use [bold]dev setup --integrate[/bold] to preview coding CLI MCP and native hook setup.",
-            "Use [bold]dev setup --integrate --apply[/bold] to configure detected clients.",
-        ]),
-        title="DevCouncil is ready",
-        border_style="green",
-    ))
+        if not created:
+            console.print(f"[yellow]DevCouncil is already initialized at {root / '.devcouncil'}.[/yellow]")
+
+        if provider:
+            try:
+                _set_model_provider(root, provider)
+            except ValueError as e:
+                console.print(f"[red]{e}[/red]")
+                raise typer.Exit(code=2) from e
+
+        _set_model_roles(root, model=model, role_models=role_models)
+
+        configured_provider = load_config(root).models.provider
+        _configure_vertexai_settings(root, configured_provider, vertex_project, vertex_location)
+        _configure_api_key(root, api_key, skip_api_key)
+
+        console.print()
+        render_doctor_check(root)
+
+        if scaffold_ci:
+            from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, scaffold_ci as scaffold_ci_workflow
+
+            written = scaffold_ci_workflow(root)
+            if written is None:
+                console.print(f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists; left unchanged.[/yellow]")
+            else:
+                console.print(f"[green]Wrote starter CI workflow {written.relative_to(root).as_posix()}.[/green]")
+
+        if integrate:
+            _configure_coding_cli_integrations(root, apply=apply, gemini_scope=gemini_scope)
+        elif created and not skip_integrations:
+            _prompt_for_first_run_integrations(root, apply=True, gemini_scope=gemini_scope)
+
+        console.print()
+        console.print(Panel.fit(
+            "\n".join([
+                "[bold]Next commands[/bold]",
+                f"Keep running DevCouncil commands in this terminal at: {root}",
+                "One-command agent path:",
+                "dev e2e \"Describe the implementation goal\"",
+                "",
+                "Manual sidecar path:",
+                "dev plan \"Describe the implementation goal\"",
+                "dev tasks",
+                "dev run TASK-001 --executor manual",
+                "dev prompt TASK-001",
+                "Paste only the dev prompt output into your coding CLI.",
+                "Paste only the dev prompt output into your coding CLI, or run directly:",
+                "dev run TASK-001 --executor codex",
+                "dev run TASK-001 --executor gemini",
+                "dev run TASK-001 --executor claude",
+                "dev run TASK-001 --executor opencode",
+                "dev run TASK-001 --executor antigravity",
+                "dev verify TASK-001",
+                "",
+                "Use [bold]dev setup --integrate[/bold] to preview coding CLI MCP and native hook setup.",
+                "Use [bold]dev setup --integrate --apply[/bold] to configure detected clients.",
+            ]),
+            title="DevCouncil is ready",
+            border_style="green",
+        ))
+        log_step("setup/complete", project_root=root, trace=True)

package/src/devcouncil/cli/commands/shell.py

@@ -1,3 +1,4 @@
+import logging
 import typer
 from pathlib import Path
 from rich.console import Console
@@ -6,8 +7,10 @@ from devcouncil.cli.commands.init import initialize_project
 from devcouncil.execution.shell_session import GuardedShellSession
 from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import TaskRepository
+from devcouncil.telemetry.stages import log_stage, log_step
 
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def shell(
@@ -21,53 +24,59 @@ def shell(
     Run guarded shell commands for a task.
     """
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev shell: task=%s command=%s", task_id, "set" if command else "interactive")
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
         console.print("[red]DevCouncil not initialized.[/red]")
         raise typer.Exit(code=1)
 
-    with db.get_session() as session:
-        task = TaskRepository(session).get_by_id(task_id)
-        if not task:
-            console.print(f"[red]Task {task_id} not found.[/red]")
-            raise typer.Exit(code=1)
+    with log_stage("shell", project_root=root, task_id=task_id):
+        log_step("shell/1: loading task and starting session", project_root=root, task_id=task_id, trace=True)
+        with db.get_session() as session:
+            task = TaskRepository(session).get_by_id(task_id)
+            if not task:
+                console.print(f"[red]Task {task_id} not found.[/red]")
+                raise typer.Exit(code=1)
 
-    try:
-        session_runner = GuardedShellSession(root, task, shell=shell_name)
-    except ValueError as exc:
-        console.print(f"[red]{exc}[/red]")
-        raise typer.Exit(code=2)
-    try:
-        session_runner.start(force=force)
-    except ValueError as exc:
-        # A live or stale lease from a prior session blocks a new one. Don't dump
-        # a traceback — tell the user how to recover.
-        console.print(f"[red]{exc}[/red]")
-        console.print(
-            "[yellow]Another shell session may be active for this task. If it is "
-            "stale (a previous session crashed), re-run with [bold]--force[/bold] to "
-            "reclaim it.[/yellow]"
-        )
-        raise typer.Exit(code=2)
-    try:
-        if command:
-            code = session_runner.run_one(command)
-            raise typer.Exit(code=code)
+        try:
+            session_runner = GuardedShellSession(root, task, shell=shell_name)
+        except ValueError as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(code=2)
+        try:
+            session_runner.start(force=force)
+        except ValueError as exc:
+            console.print(f"[red]{exc}[/red]")
+            console.print(
+                "[yellow]Another shell session may be active for this task. If it is "
+                "stale (a previous session crashed), re-run with [bold]--force[/bold] to "
+                "reclaim it.[/yellow]"
+            )
+            raise typer.Exit(code=2)
+        try:
+            if command:
+                log_step("shell/2: running guarded command", project_root=root, task_id=task_id)
+                code = session_runner.run_one(command)
+                log_step("shell/complete", project_root=root, task_id=task_id, trace=True)
+                raise typer.Exit(code=code)
 
-        console.print(f"[cyan]Guarded shell for {task_id}. Type exit or quit to end.[/cyan]")
-        while True:
-            try:
-                line = input(f"devcouncil:{task_id}> ")
-            except (EOFError, KeyboardInterrupt):
-                break
-            normalized = line.strip()
-            if normalized.lower() in {"exit", "quit"}:
-                break
-            if not normalized:
-                continue
-            code = session_runner.run_one(normalized)
-            if code != 0:
-                console.print(f"[yellow]Command exited with {code}[/yellow]")
-    finally:
-        session_runner.finish()
+            console.print(f"[cyan]Guarded shell for {task_id}. Type exit or quit to end.[/cyan]")
+            while True:
+                try:
+                    line = input(f"devcouncil:{task_id}> ")
+                except (EOFError, KeyboardInterrupt):
+                    break
+                normalized = line.strip()
+                if normalized.lower() in {"exit", "quit"}:
+                    break
+                if not normalized:
+                    continue
+                code = session_runner.run_one(normalized)
+                if code != 0:
+                    console.print(f"[yellow]Command exited with {code}[/yellow]")
+        finally:
+            session_runner.finish()
+        log_step("shell/complete", project_root=root, task_id=task_id, trace=True)

package/src/devcouncil/cli/commands/show.py

@@ -1,4 +1,5 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 from pathlib import Path
 
 import typer
@@ -7,9 +8,11 @@ from rich.panel import Panel
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import TaskRepository, RequirementRepository
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer()
 console = Console()
+logger = logging.getLogger(__name__)
 
 @app.callback(invoke_without_command=True)
 def show(
@@ -25,52 +28,63 @@ def show(
         return
 
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev show: task=%s json=%s", task_id, json_format)
     initialize_project(root, quiet=True)
     db = get_db(root)
     if not db:
         raise typer.Exit(code=1)
 
-    with db.get_session() as session:
-        task_repo = TaskRepository(session)
-        req_repo = RequirementRepository(session)
-        
-        task = task_repo.get_by_id(task_id)
-        if not task:
-            console.print(f"[red]Task {task_id} not found.[/red]")
-            raise typer.Exit(code=1)
-        
-        reqs = req_repo.get_all()
-        req_map = {r.id: r for r in reqs}
+    with log_stage("show", project_root=root, task_id=task_id):
+        log_step("show/1: loading task details", project_root=root, task_id=task_id, trace=True)
+        with db.get_session() as session:
+            task_repo = TaskRepository(session)
+            req_repo = RequirementRepository(session)
 
-        if json_format:
-            linked_requirements = [
-                req_map[req_id].model_dump()
-                for req_id in task.requirement_ids
-                if req_id in req_map
-            ]
-            typer.echo(json.dumps({
-                "task": task.model_dump(),
-                "linked_requirements": linked_requirements,
-            }, indent=2))
-            return
+            task = task_repo.get_by_id(task_id)
+            if not task:
+                message = f"Task {task_id} not found."
+                if json_format:
+                    typer.echo(dump_json({"ok": False, "error": message, "task_id": task_id}, indent=2))
+                else:
+                    console.print(f"[red]{message}[/red]")
+                raise typer.Exit(code=1)
 
-        output = f"[bold]Status:[/bold] {task.status}\n\n"
-        output += f"[bold]Description:[/bold]\n{task.description}\n\n"
-        
-        output += "[bold]Linked Requirements:[/bold]\n"
-        for req_id in task.requirement_ids:
-            req = req_map.get(req_id)
-            if req:
-                output += f"  - [cyan]{req.id}[/cyan]: {req.title}\n"
-            else:
-                output += f"  - [cyan]{req_id}[/cyan]: (Requirement not found)\n"
-                
-        output += "\n[bold]Planned Files:[/bold]\n"
-        for pf in task.planned_files:
-            output += f"  - {pf.path} ({pf.allowed_change}): {pf.reason}\n"
-            
-        output += "\n[bold]Expected Tests:[/bold]\n"
-        for et in task.expected_tests:
-            output += f"  - {et}\n"
+            reqs = req_repo.get_all()
+            req_map = {r.id: r for r in reqs}
 
-        console.print(Panel(output, title=f"Task {task.id}: {task.title}", expand=False))
+            if json_format:
+                linked_requirements = [
+                    req_map[req_id].model_dump()
+                    for req_id in task.requirement_ids
+                    if req_id in req_map
+                ]
+                typer.echo(dump_json({
+                    "task": task.model_dump(),
+                    "linked_requirements": linked_requirements,
+                }, indent=2))
+                log_step("show/complete", project_root=root, task_id=task_id, trace=True)
+                return
+
+            output = f"[bold]Status:[/bold] {task.status}\n\n"
+            output += f"[bold]Description:[/bold]\n{task.description}\n\n"
+
+            output += "[bold]Linked Requirements:[/bold]\n"
+            for req_id in task.requirement_ids:
+                req = req_map.get(req_id)
+                if req:
+                    output += f"  - [cyan]{req.id}[/cyan]: {req.title}\n"
+                else:
+                    output += f"  - [cyan]{req_id}[/cyan]: (Requirement not found)\n"
+
+            output += "\n[bold]Planned Files:[/bold]\n"
+            for pf in task.planned_files:
+                output += f"  - {pf.path} ({pf.allowed_change}): {pf.reason}\n"
+
+            output += "\n[bold]Expected Tests:[/bold]\n"
+            for et in task.expected_tests:
+                output += f"  - {et}\n"
+
+            console.print(Panel(output, title=f"Task {task.id}: {task.title}", expand=False))
+        log_step("show/complete", project_root=root, task_id=task_id, trace=True)

package/src/devcouncil/cli/commands/skills.py

@@ -7,9 +7,12 @@ from rich.table import Table
 
 from devcouncil.knowledge.frontmatter import build_frontmatter_markdown
 from devcouncil.skills.registry import Skill, get_skill, load_skills, scaffold_skills, select_skills
+from devcouncil.telemetry.stages import log_stage, log_step
+import logging
 
 app = typer.Typer(help="Inspect and scaffold DevCouncil engineering skills for coding agents.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 def _is_repo_skill(skill, project_root: Path) -> bool:
@@ -33,27 +36,33 @@ def skills(
         return
 
     root = project_root.expanduser().resolve()
-    all_skills = load_skills(project_root=root)
-    if not all_skills:
-        console.print("[yellow]No skills found in the DevCouncil skills library.[/yellow]")
-        raise typer.Exit()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev skills list: goal=%r", goal)
+    with log_stage("skills", project_root=root):
+        log_step("skills/1: loading skill registry", project_root=root, trace=True)
+        all_skills = load_skills(project_root=root)
+        if not all_skills:
+            console.print("[yellow]No skills found in the DevCouncil skills library.[/yellow]")
+            raise typer.Exit()
 
-    selected = {skill.name for skill in select_skills(goal, root)}
-    table = Table(title="DevCouncil Skills")
-    table.add_column("Skill", style="cyan")
-    table.add_column("Source", justify="center")
-    table.add_column("Applies", justify="center")
-    table.add_column("Description")
-    for skill in all_skills:
-        applies = "always" if skill.always else ("yes" if skill.name in selected else "-")
-        style = "green" if skill.name in selected else "dim"
-        source = "repo" if _is_repo_skill(skill, root) else "library"
-        table.add_row(skill.name, source, f"[{style}]{applies}[/{style}]", skill.description)
-    console.print(table)
-    console.print(
-        "\nScaffold the applicable skills into this repo with: "
-        "[bold]dev skills scaffold[/bold] (add a goal to widen selection, or --all)."
-    )
+        selected = {skill.name for skill in select_skills(goal, root)}
+        table = Table(title="DevCouncil Skills")
+        table.add_column("Skill", style="cyan")
+        table.add_column("Source", justify="center")
+        table.add_column("Applies", justify="center")
+        table.add_column("Description")
+        for skill in all_skills:
+            applies = "always" if skill.always else ("yes" if skill.name in selected else "-")
+            style = "green" if skill.name in selected else "dim"
+            source = "repo" if _is_repo_skill(skill, root) else "library"
+            table.add_row(skill.name, source, f"[{style}]{applies}[/{style}]", skill.description)
+        console.print(table)
+        console.print(
+            "\nScaffold the applicable skills into this repo with: "
+            "[bold]dev skills scaffold[/bold] (add a goal to widen selection, or --all)."
+        )
+        log_step("skills/complete", project_root=root, count=len(all_skills), trace=True)
 
 
 @app.command("show")