devcouncil 0.1.1 → 0.2.0

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

@@ -8,18 +8,27 @@ import yaml
 from rich.console import Console
 from rich.panel import Panel
 
-from devcouncil.app.config import load_config, load_local_secrets, provider_api_key_env_var
+from devcouncil.app.config import (
+    _normalized_provider_name,
+    get_gcloud_access_token,
+    load_config,
+    load_local_secrets,
+    provider_api_key_env_var,
+)
 from devcouncil.cli.commands.doctor import render_doctor_check
-from devcouncil.cli.commands.init import initialize_project
+from devcouncil.cli.commands.init import initialize_project, parse_role_model_overrides
 from devcouncil.cli.commands.integrate import (
     _claude_command,
     _codex_command,
+    _configure_antigravity,
+    _configure_cursor,
     _configure_native_hooks,
+    _configure_opencode,
+    _configure_warp,
     _configure,
-    _cursor_command,
     _gemini_command,
 )
-from devcouncil.llm.provider import validate_model_provider
+from devcouncil.llm.provider import apply_provider_default_role_models, build_role_model_config, validate_model_provider
 
 app = typer.Typer()
 console = Console()
@@ -32,9 +41,36 @@ def _set_model_provider(project_root: Path, provider: str) -> None:
     raw_config.setdefault("models", {})
     previous = raw_config["models"].get("provider", "openrouter")
     raw_config["models"]["provider"] = normalized
+    updated_role_defaults = apply_provider_default_role_models(raw_config, previous, normalized)
     config_path.write_text(yaml.dump(raw_config, default_flow_style=False), encoding="utf-8")
     if previous != normalized:
         console.print(f"[green]Updated model provider from {previous} to {normalized}.[/green]")
+    if updated_role_defaults:
+        console.print(f"[green]Updated default role models for {normalized}.[/green]")
+
+
+def _set_model_roles(
+    project_root: Path,
+    model: str | None = None,
+    role_models: dict[str, str] | None = None,
+) -> None:
+    if not model and not role_models:
+        return
+
+    config_path = project_root / ".devcouncil" / "config.yaml"
+    raw_config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    raw_config.setdefault("models", {})
+    provider = validate_model_provider(raw_config["models"].get("provider", "openrouter"))
+    raw_config["models"]["roles"] = build_role_model_config(
+        provider,
+        model=model,
+        role_models=role_models,
+    )
+    config_path.write_text(yaml.dump(raw_config, default_flow_style=False), encoding="utf-8")
+    if model:
+        console.print(f"[green]Updated all model roles to use {model}.[/green]")
+    for role, selected_model in (role_models or {}).items():
+        console.print(f"[green]Updated {role} to use {selected_model}.[/green]")
 
 
 def _write_local_secret(project_root: Path, env_var: str, value: str) -> Path:
@@ -54,9 +90,43 @@ def _write_local_secret(project_root: Path, env_var: str, value: str) -> Path:
     return path
 
 
+def _configure_vertexai_settings(
+    project_root: Path,
+    provider: str,
+    vertex_project: str | None,
+    vertex_location: str | None,
+) -> None:
+    if provider != "vertexai":
+        return
+
+    local_secrets = load_local_secrets(project_root)
+    if vertex_project:
+        _write_local_secret(project_root, "VERTEXAI_PROJECT", vertex_project)
+        console.print("[green]Saved VERTEXAI_PROJECT to .devcouncil/secrets.env.[/green]")
+    elif not (
+        os.environ.get("VERTEXAI_PROJECT")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT")
+        or local_secrets.get("VERTEXAI_PROJECT")
+        or local_secrets.get("GOOGLE_CLOUD_PROJECT")
+    ):
+        console.print(
+            "[yellow]VERTEXAI_PROJECT is not set. "
+            "Set it in your shell or rerun setup with --vertex-project PROJECT_ID.[/yellow]"
+        )
+
+    if vertex_location:
+        _write_local_secret(project_root, "VERTEXAI_LOCATION", vertex_location)
+        console.print("[green]Saved VERTEXAI_LOCATION to .devcouncil/secrets.env.[/green]")
+
+
 def _configure_api_key(project_root: Path, api_key: str | None, skip_api_key: bool) -> None:
     config = load_config(project_root)
     provider = config.models.provider
+    if _normalized_provider_name(provider) == "ollama":
+        console.print(
+            "[green]Ollama uses a local server (default http://localhost:11434); no API key required.[/green]"
+        )
+        return
     env_var = provider_api_key_env_var(provider)
     local_secrets = load_local_secrets(project_root)
 
@@ -70,6 +140,9 @@ def _configure_api_key(project_root: Path, api_key: str | None, skip_api_key: bo
         _write_local_secret(project_root, env_var, api_key)
         console.print(f"[green]Saved {env_var} to .devcouncil/secrets.env.[/green]")
         return
+    if provider == "vertexai" and get_gcloud_access_token():
+        console.print("[green]Vertex AI access token is available from gcloud auth print-access-token.[/green]")
+        return
     if skip_api_key:
         console.print(f"[yellow]Skipped {env_var} setup. Model-backed commands will ask again if it is missing.[/yellow]")
         return
@@ -109,7 +182,6 @@ def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_s
         ("Codex CLI", _codex_command(project_root)),
         ("Gemini CLI", _gemini_command(project_root, gemini_scope)),
         ("Claude Code", _claude_command(project_root, "local")),
-        ("Cursor", _cursor_command(project_root)),
     ]
     results = []
     for tool, command in commands:
@@ -117,6 +189,10 @@ def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_s
             console.print(f"[yellow]{tool} CLI not found on PATH. Skipping optional integration.[/yellow]")
             continue
         results.append(_configure(tool, command, apply))
+    results.append(_configure_cursor(project_root, apply))
+    results.append(_configure_opencode(project_root, apply))
+    results.append(_configure_antigravity(project_root, apply))
+    results.append(_configure_warp(project_root, apply))
     _configure_native_hooks(project_root, "all", apply)
     if apply and any(not ok for ok in results):
         raise typer.Exit(code=1)
@@ -157,9 +233,20 @@ def setup(
     apply: bool = typer.Option(False, "--apply", help="Apply integration config instead of previewing commands."),
     gemini_scope: str = typer.Option("project", "--gemini-scope", help="Gemini MCP config scope: project or user."),
     provider: str | None = typer.Option(None, "--provider", help="Set models.provider before configuring the API key."),
+    model: str | None = typer.Option(None, "--model", "-m", help="Model id to use for every default role."),
+    role_model: list[str] | None = typer.Option(
+        None,
+        "--role-model",
+        help="Per-role model override in ROLE=MODEL form. Can be repeated.",
+    ),
     api_key: str | None = typer.Option(None, "--api-key", help="Store the configured provider API key in local .devcouncil/secrets.env."),
+    vertex_project: str | None = typer.Option(None, "--vertex-project", help="Store VERTEXAI_PROJECT for the vertexai provider."),
+    vertex_location: str | None = typer.Option(None, "--vertex-location", help="Store VERTEXAI_LOCATION for the vertexai provider. Defaults to global."),
     skip_api_key: bool = typer.Option(False, "--skip-api-key", help="Skip the first-run model API key prompt."),
     skip_integrations: bool = typer.Option(False, "--skip-integrations", help="Skip the first-run coding CLI integration prompt."),
+    skip_map: bool = typer.Option(False, "--skip-map", help="Skip generating repo_map.json and agent guides on init."),
+    skip_skills: bool = typer.Option(False, "--skip-skills", help="Skip scaffolding engineering skills into .claude/skills/ on init."),
+    scaffold_ci: bool = typer.Option(False, "--scaffold-ci", help="Write a starter .github/workflows/devcouncil.yml from the configured commands."),
 ):
     """
     Initialize DevCouncil from a normal terminal in the target repository root.
@@ -174,7 +261,44 @@ def setup(
         raise typer.Exit(code=2)
 
     root = project_root.expanduser().resolve()
-    created = initialize_project(root, project_name=name)
+    try:
+        role_models = parse_role_model_overrides(role_model)
+        initial_provider = validate_model_provider(provider) if provider else "openrouter"
+    except ValueError as e:
+        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]."
+        )
+
+    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]")
 
@@ -185,11 +309,24 @@ def setup(
             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:
@@ -213,6 +350,8 @@ def setup(
             "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.",

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

@@ -0,0 +1,73 @@
+import typer
+from pathlib import Path
+from rich.console import Console
+
+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
+
+console = Console()
+
+
+def shell(
+    task_id: str = typer.Argument(..., help="Task ID"),
+    command: str | None = typer.Option(None, "--command", help="Run one guarded command and exit."),
+    shell_name: str = typer.Option("auto", "--shell", help="Shell backend: auto, pwsh, bash, zsh."),
+    force: bool = typer.Option(False, "--force", help="Reclaim a stale lease from a previous (possibly crashed) session."),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+):
+    """
+    Run guarded shell commands for a task.
+    """
+    root = project_root.expanduser().resolve()
+    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)
+
+    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)
+
+        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()

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

@@ -0,0 +1,88 @@
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.skills.registry import get_skill, load_skills, scaffold_skills, select_skills
+
+app = typer.Typer(help="Inspect and scaffold DevCouncil engineering skills for coding agents.")
+console = Console()
+
+
+def _is_repo_skill(skill, project_root: Path) -> bool:
+    if skill.source_path is None:
+        return False
+    try:
+        skill.source_path.resolve().relative_to(project_root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+@app.callback(invoke_without_command=True)
+def skills(
+    ctx: typer.Context,
+    goal: str = typer.Option("", "--goal", help="Optional goal text; highlights the skills that would apply."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root used for file-based skill triggers."),
+):
+    """List available skills and show which apply to this repository/goal."""
+    if ctx.invoked_subcommand is not None:
+        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()
+
+    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)."
+    )
+
+
+@app.command("show")
+def show(
+    name: str = typer.Argument(..., help="Skill name, e.g. core-engineering or android."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root, so repo-local skills are found too."),
+):
+    """Print the full body of a single skill."""
+    skill = get_skill(name, project_root=project_root.expanduser().resolve())
+    if skill is None:
+        console.print(f"[red]No skill named '{name}'. Run 'dev skills' to list available skills.[/red]")
+        raise typer.Exit(code=1)
+    console.print(skill.to_skill_md())
+
+
+@app.command("scaffold")
+def scaffold(
+    goal: str = typer.Argument("", help="Optional goal text used to widen domain-skill selection."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root to scaffold skills into."),
+    all_skills: bool = typer.Option(False, "--all", help="Scaffold every skill, not just the ones that apply."),
+):
+    """Write the applicable skills into <repo>/.claude/skills/<name>/SKILL.md."""
+    root = project_root.expanduser().resolve()
+    chosen = load_skills(project_root=root) if all_skills else select_skills(goal, root)
+    written = scaffold_skills(root, chosen)
+    if not written:
+        console.print(
+            f"[green]Skills already up to date in {root / '.claude' / 'skills'} "
+            f"({len(chosen)} applicable).[/green]"
+        )
+        return
+    console.print(f"[green]Wrote {len(written)} skill file(s):[/green]")
+    for path in written:
+        console.print(f"  {path.relative_to(root).as_posix()}")

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

@@ -8,7 +8,7 @@ from devcouncil.cli.commands.init import initialize_project
 from devcouncil.app.project_status import compute_phase
 from devcouncil.storage.db import get_db
 from devcouncil.storage.repositories import ArtifactGraphRepository, StateRepository
-from devcouncil.telemetry.cost import CostEstimator
+from devcouncil.telemetry.cost import CostEstimator, cost_by_task
 from devcouncil.live.summary import live_review_summary
 
 console = Console()
@@ -51,6 +51,7 @@ def _status_payload(project_root: Path) -> dict:
             "phase": phase,
             "coverage_summary": summary,
             "total_cost": total_cost,
+            "cost_by_task": cost_by_task(project_root),
             "task_status_counts": status_counts,
             "blocking_gaps": [gap.model_dump() for gap in blocking_gaps],
             "live_review": live_review_summary(project_root),
@@ -59,6 +60,11 @@ def _status_payload(project_root: Path) -> dict:
 
 def status(
     json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    fail_on_blocking: bool = typer.Option(
+        False,
+        "--fail-on-blocking",
+        help="Exit non-zero when blocking gaps remain, so shell-driven agents can gate on $?.",
+    ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """
@@ -66,8 +72,14 @@ def status(
     """
     root = project_root.expanduser().resolve()
     payload = _status_payload(root)
+
+    def _maybe_fail() -> None:
+        if fail_on_blocking and payload.get("blocking_gaps"):
+            raise typer.Exit(code=1)
+
     if json_format:
         typer.echo(json.dumps(payload, indent=2))
+        _maybe_fail()
         return
 
     if not payload["initialized"]:
@@ -108,6 +120,16 @@ def status(
             table.add_row(state, str(count))
         console.print(table)
 
+    cost_groups = payload.get("cost_by_task") or {}
+    if cost_groups:
+        cost_table = Table(title="Cost by Task")
+        cost_table.add_column("Task", style="cyan")
+        cost_table.add_column("Cost ($)", justify="right")
+        cost_table.add_column("Calls", justify="right")
+        for name, stats in sorted(cost_groups.items(), key=lambda kv: kv[1]["cost"], reverse=True):
+            cost_table.add_row(name, f"{stats['cost']:.4f}", str(stats["calls"]))
+        console.print(cost_table)
+
     blocking_gaps = payload["blocking_gaps"]
     if blocking_gaps:
         console.print(f"\n[red bold]WARNING: {len(blocking_gaps)} blocking gap(s) must be resolved:[/red bold]")
@@ -115,3 +137,5 @@ def status(
             console.print(f"  - [red]{gap['id']}[/red]: {gap['description'][:80]}")
         if len(blocking_gaps) > 5:
             console.print(f"  ... and {len(blocking_gaps) - 5} more. Run [bold]dev report[/bold] for details.")
+
+    _maybe_fail()

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

@@ -1,11 +1,12 @@
 import json
 import time
 from pathlib import Path
+from typing import Optional
 
 import typer
 from rich.console import Console
 
-from devcouncil.telemetry.traces import read_trace_events
+from devcouncil.telemetry.traces import read_trace_events, read_trace_events_since
 
 app = typer.Typer(help="Inspect DevCouncil trace events.")
 console = Console()
@@ -13,13 +14,56 @@ console = Console()
 
 @app.command("tail")
 def tail(
-    follow: bool = typer.Option(False, "--follow", "-f", help="Continue polling for new events."),
+    follow: bool = typer.Option(
+        False, "--follow/--no-follow", "-f", help="Continue polling for new events (default is a single shot)."
+    ),
     limit: int = typer.Option(50, "--limit", "-n", help="Maximum events to print before following."),
     jsonl: bool = typer.Option(True, "--jsonl/--pretty", help="Print JSONL or compact text rows."),
+    since: Optional[int] = typer.Option(
+        None,
+        "--since",
+        help="Byte-offset cursor from a previous run; emit only events after it (stateless incremental polling).",
+    ),
+    json_summary: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit a single {events, next_cursor} JSON object (incremental mode). Implies --no-follow.",
+    ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
-    """Print the DevCouncil trace JSONL stream for replay or debugging."""
+    """Print the DevCouncil trace JSONL stream for replay or debugging.
+
+    With ``--since <cursor> --no-follow`` (or ``--json``) a single-shot supervising
+    agent gets only the events appended after the cursor plus a ``next_cursor`` to
+    pass back on the next poll, so each poll is O(new) rather than O(all).
+    """
     project_root = project_root.expanduser().resolve()
+
+    # Incremental cursor mode: any of --since / --json / explicit --no-follow.
+    incremental = since is not None or json_summary
+    if incremental:
+        events, next_cursor = read_trace_events_since(project_root, since)
+        if json_summary:
+            typer.echo(
+                json.dumps(
+                    {
+                        "events": [event.model_dump(by_alias=True) for event in events],
+                        "next_cursor": next_cursor,
+                    }
+                )
+            )
+            return
+        for event in events:
+            if jsonl:
+                typer.echo(event.model_dump_json())
+            else:
+                console.print(
+                    f"{event.timestamp} {event.type} "
+                    f"{event.task_id or '-'} {event.summary or json.dumps(event.details)}"
+                )
+        console.print(f"[dim]next_cursor: {next_cursor}[/dim]")
+        return
+
     printed = 0
 
     def emit_new(start_index: int) -> int: