ai-dev-workflow 0.1.0__py3-none-any.whl

ai_workflow_cli.py

@@ -0,0 +1,761 @@
+"""CLI bootstrap for ai-dev-workflow."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+from ado_provider import AzureDevOps, build_state_mapping, validate_mapping, validate_field_mapping
+from work_item_provider import REQUIRED_AGENT_ROLES, REQUIRED_CANONICAL_STATES
+from setup_wizard import build_setup_plan, discover_provider, interactive_mapping, interactive_ado_field_mapping, render_user_steps, apply_github_status_bootstrap
+from github_work_item_provider import validate_github_mapping
+from ai_provider import provider_template, validate_provider_registry
+from source_connection import resolve_github_token
+from work_item_registry import validate_work_item_provider
+from ado_mcp import build_ado_mcp
+from worker_registry import build_worker, validate_worker_registry
+from framework_update import DEFAULT_FRAMEWORK_SOURCE, ensure_framework_metadata, build_update_plan, apply_update
+
+
+DEFAULT_ROLE_PROVIDERS = {
+    "SetupAgent": "manual",
+    "ArchitectAgent": "manual",
+    "TesterAgent": "codex",
+    "ImplementerAgent": "codex",
+    "ReviewerAgent": "manual",
+    "RuntimeVerifierAgent": "project-defined",
+}
+
+PACKAGE_VERSION = "0.1.0"
+
+ROLE_KEYS = {
+    "SetupAgent": "setup",
+    "ArchitectAgent": "architect",
+    "TesterAgent": "tester",
+    "ImplementerAgent": "implementer",
+    "ReviewerAgent": "reviewer",
+    "RuntimeVerifierAgent": "runtime_verifier",
+}
+
+
+def _load_yaml(path: Path) -> dict:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required")
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return data or {}
+
+
+def _dump_yaml(data: dict) -> str:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required")
+    return yaml.safe_dump(data, sort_keys=False, allow_unicode=True)
+
+
+def build_agents(role_providers: dict | None = None) -> dict:
+    role_providers = role_providers or DEFAULT_ROLE_PROVIDERS
+    return {
+        ROLE_KEYS[role]: {"role": role, "provider": provider}
+        for role, provider in role_providers.items()
+    }
+
+
+def build_ado_config(discovery: dict, role_providers: dict | None = None) -> dict:
+    return {
+        "version": 1,
+        "work_items": {
+            "provider": "azure-devops",
+            "azure_devops": {
+                "organization": discovery["organization"],
+                "project": discovery["project"],
+                "project_id": discovery["project_id"],
+                "process_id": discovery["process_id"],
+                "state_mapping": build_state_mapping(discovery),
+            },
+        },
+        "agents": build_agents(role_providers),
+    }
+
+
+def build_github_config(role_providers: dict | None = None) -> dict:
+    return {
+        "version": 1,
+        "work_items": {"provider": "github-issues"},
+        "agents": build_agents(role_providers),
+    }
+
+
+def merge_owned(existing: dict, generated: dict) -> dict:
+    merged = dict(existing)
+    merged["version"] = existing.get("version", generated.get("version", 1))
+    for key in ("work_items", "agents", "execution_environment"):
+        if key in generated:
+            merged[key] = generated[key]
+    if "framework" in generated:
+        merged["framework"] = {
+            **generated["framework"],
+            **(existing.get("framework") or {}),
+            "source": generated["framework"]["source"],
+            "ref": generated["framework"]["ref"],
+            "schema_version": generated["framework"]["schema_version"],
+        }
+    return merged
+
+
+def ensure_file(path: Path, content: str, force: bool = False) -> bool:
+    if path.exists() and not force:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def generated_agents_md() -> str:
+    return """# AGENTS.md
+
+This repository uses ai-dev-workflow.
+
+Start from CURRENT.md when present, then load only context relevant to the assigned role and task.
+Treat the configured WorkItemProvider as the task source of truth.
+Do not change frozen acceptance criteria merely to make tests pass.
+Runtime verification must not be inferred from mocks.
+"""
+
+
+def generated_current_md() -> str:
+    return """# CURRENT
+
+## Task
+None
+
+## Status
+Idle
+
+## Required Context
+AGENTS.md
+
+## Relevant Code
+None
+
+## Allowed Scope
+Project-defined
+
+## Done When
+Project-defined
+
+## Completed
+None
+
+## Next Action
+Select or publish a work item.
+
+## Blocker
+None
+"""
+
+
+def generated_devcontainer() -> str:
+    return """{
+  "name": "AI Workflow Workspace",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "lts"
+    }
+  },
+  "postCreateCommand": "python -m pip install --user PyYAML",
+  "remoteUser": "vscode"
+}
+"""
+
+
+def parse_framework_ref(framework_ref: str) -> tuple[str, str]:
+    marker = "/.github/workflows/"
+    if marker not in framework_ref or "@" not in framework_ref:
+        return DEFAULT_FRAMEWORK_SOURCE, "main"
+    source = framework_ref.split(marker, 1)[0]
+    ref = framework_ref.rsplit("@", 1)[1]
+    return source, ref
+
+
+def generated_github_caller(framework_ref: str) -> str:
+    return f"""name: AI Workflow Queue
+
+on:
+  issues:
+    types: [labeled, closed, unassigned]
+  workflow_dispatch:
+  schedule:
+    - cron: '*/10 * * * *'
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  dispatch:
+    if: github.event_name != 'issues' || github.event.action != 'labeled' || github.event.label.name == 'status:ready'
+    uses: {framework_ref}
+    with:
+      codex_cloud_enabled: false
+      codespaces_enabled: false
+      codespaces_mode: on-demand
+"""
+
+
+def doctor(config: dict, discovery: dict | None = None) -> list[str]:
+    errors = []
+    work_items = config.get("work_items", {})
+    provider = work_items.get("provider")
+    if provider not in ("github-issues", "azure-devops", "composite"):
+        errors.append("work_items.provider must be github-issues, azure-devops or composite")
+    if provider == "github-issues" and "github_issues" in work_items:
+        github = work_items.get("github_issues", {})
+        mapping = github.get("state_mapping", {})
+        if discovery is not None and discovery.get("labels") is not None:
+            errors.extend(validate_github_mapping(discovery, mapping))
+        canonical = set(mapping.values())
+        for required in REQUIRED_CANONICAL_STATES:
+            if required not in canonical:
+                errors.append(f"canonical state is not mapped by any GitHub status: {required}")
+    if provider in ("azure-devops", "composite"):
+        ado = work_items.get("azure_devops", {})
+        for field in ("organization", "project", "state_mapping"):
+            if not ado.get(field):
+                errors.append(f"missing Azure DevOps config: {field}")
+        mapping = ado.get("state_mapping", {})
+        if discovery is not None:
+            errors.extend(validate_mapping(discovery, mapping))
+        canonical = {value for wit in mapping.values() for value in wit.values()}
+        if provider == "azure-devops":
+            for required in REQUIRED_CANONICAL_STATES:
+                if required not in canonical:
+                    errors.append(f"canonical state is not mapped by any ADO state: {required}")
+        if discovery is not None:
+            errors.extend(validate_field_mapping(discovery, ado.get("field_mapping", {})))
+
+    agents = config.get("agents", {})
+    by_role = {
+        item.get("role"): item.get("provider")
+        for item in agents.values()
+        if isinstance(item, dict)
+    }
+    for role in REQUIRED_AGENT_ROLES:
+        provider_name = by_role.get(role)
+        if not provider_name or provider_name == "none":
+            errors.append(f"required agent role has no provider: {role}")
+
+    providers = config.get("providers", {})
+    if providers:
+        errors.extend(validate_provider_registry(providers, agents))
+
+    workers = config.get("workers", [])
+    if workers:
+        errors.extend(validate_worker_registry(workers, providers))
+
+    env = config.get("execution_environment", {})
+    if env:
+        env_type = env.get("type")
+        if env_type not in ("none", "codespaces"):
+            errors.append("execution_environment.type must be none or codespaces")
+        if env_type == "codespaces":
+            mode = (env.get("codespaces") or {}).get("mode")
+            if mode not in ("off", "on-demand", "always-on"):
+                errors.append("codespaces mode must be off, on-demand or always-on")
+    return errors
+
+
+def parse_role_provider(values: list[str]) -> dict:
+    result = dict(DEFAULT_ROLE_PROVIDERS)
+    for item in values:
+        if "=" not in item:
+            raise ValueError("role provider must use Role=provider")
+        role, provider = item.split("=", 1)
+        role, provider = role.strip(), provider.strip()
+        if role not in DEFAULT_ROLE_PROVIDERS or not provider:
+            raise ValueError(f"invalid role provider assignment: {item}")
+        result[role] = provider
+    return result
+
+
+def parse_ai_provider(values: list[str]) -> dict:
+    providers = {
+        "manual": provider_template("interactive"),
+        "codex": provider_template("chatgpt-codex"),
+    }
+    for raw in values:
+        if "=" not in raw:
+            raise ValueError("ai provider must use id=type[,key=value...]")
+        provider_id, spec = raw.split("=", 1)
+        provider_id = provider_id.strip()
+        parts = [p.strip() for p in spec.split(",") if p.strip()]
+        if not provider_id or not parts:
+            raise ValueError(f"invalid ai provider: {raw}")
+        provider_type = parts[0]
+        options = {}
+        for item in parts[1:]:
+            if "=" not in item:
+                raise ValueError(f"invalid ai provider option: {item}")
+            key, value = item.split("=", 1)
+            options[key.strip()] = value.strip()
+        providers[provider_id] = provider_template(
+            provider_type,
+            model=options.get("model"),
+            base_url=options.get("base_url"),
+            auth_type=options.get("auth"),
+            env=options.get("env"),
+        )
+    return providers
+
+
+def parse_worker(values: list[str]) -> list[dict]:
+    workers = []
+    for raw in values:
+        if "=" not in raw:
+            raise ValueError("worker must use id=mode,provider=...,environment=...,roles=A|B")
+        worker_id, spec = raw.split("=", 1)
+        worker_id = worker_id.strip()
+        parts = [p.strip() for p in spec.split(",") if p.strip()]
+        if not worker_id or not parts:
+            raise ValueError(f"invalid worker: {raw}")
+        mode = parts[0]
+        options = {}
+        for item in parts[1:]:
+            if "=" not in item:
+                raise ValueError(f"invalid worker option: {item}")
+            key, value = item.split("=", 1)
+            options[key.strip()] = value.strip()
+        roles = [x for x in options.get("roles", "").split("|") if x]
+        capabilities = [x for x in options.get("capabilities", "").split("|") if x]
+        managed = options.get("managed")
+        managed_value = None if managed is None else managed.lower() in ("1","true","yes","on")
+        workers.append(build_worker(
+            worker_id,
+            mode=mode,
+            provider=options.get("provider", "manual"),
+            environment=options.get("environment", "local"),
+            roles=roles,
+            capabilities=capabilities,
+            capacity=int(options.get("capacity", "1")),
+            managed=managed_value,
+            assignee=options.get("assignee"),
+            planning_updates=options.get("planning_updates", "approval-required"),
+        ))
+    return workers
+
+
+def parse_ado_field_mapping(values: list[str]) -> dict:
+    """Parse WIT:key=Field.Ref[,default=value]. Values are user-defined; fields must already exist."""
+    result = {}
+    for raw in values:
+        if "=" not in raw or ":" not in raw.split("=",1)[0]:
+            raise ValueError("ado field must use WIT:key=Field.Ref[,default=value]")
+        left, spec = raw.split("=",1)
+        wit, key = left.split(":",1)
+        parts = [p.strip() for p in spec.split(",") if p.strip()]
+        field_ref = parts[0]
+        config = {"field": field_ref}
+        for item in parts[1:]:
+            if "=" not in item:
+                raise ValueError(f"invalid ado field option: {item}")
+            k, v = item.split("=",1)
+            if k.strip() != "default":
+                raise ValueError(f"unsupported ado field option: {k}")
+            config["default"] = v
+        result.setdefault(wit.strip(), {})[key.strip()] = config
+    return result
+
+
+def build_environment(environment: str, codespaces_mode: str) -> dict:
+    if environment == "none":
+        return {"type": "none"}
+    return {
+        "type": "codespaces",
+        "codespaces": {
+            "enabled": codespaces_mode != "off",
+            "mode": codespaces_mode,
+        },
+    }
+
+
+def perform_init(args, ado_api_factory=AzureDevOps) -> tuple[dict, dict | None]:
+    roles = parse_role_provider(args.role_provider)
+    discovery = None
+    if args.work_items == "azure-devops":
+        token = os.environ.get(args.ado_token_env)
+        if not token:
+            raise RuntimeError(f"{args.ado_token_env} is required")
+        api = ado_api_factory(args.ado_organization, token)
+        discovery = api.discover(args.ado_project)
+        generated = build_ado_config(discovery, roles)
+    else:
+        generated = build_github_config(roles)
+
+    generated["execution_environment"] = build_environment(
+        args.environment, args.codespaces_mode
+    )
+    framework_source, framework_version = parse_framework_ref(args.framework_ref)
+    generated = ensure_framework_metadata(
+        generated, source=framework_source, ref=framework_version
+    )
+
+    output = Path(args.output)
+    existing = _load_yaml(output) if output.exists() else {}
+    config = generated if args.force or not existing else merge_owned(existing, generated)
+    output.write_text(_dump_yaml(config), encoding="utf-8")
+
+    if discovery is not None:
+        discovery_path = output.with_suffix(output.suffix + ".ado-discovery.json")
+        discovery_path.write_text(
+            json.dumps(discovery, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    if not args.no_files:
+        ensure_file(Path("AGENTS.md"), generated_agents_md(), args.force)
+        ensure_file(Path("CURRENT.md"), generated_current_md(), args.force)
+        if args.environment == "codespaces":
+            ensure_file(
+                Path(".devcontainer/devcontainer.json"),
+                generated_devcontainer(),
+                args.force,
+            )
+        if args.work_items == "github-issues":
+            ensure_file(
+                Path(".github/workflows/ai-workflow.yml"),
+                generated_github_caller(args.framework_ref),
+                args.force,
+            )
+
+    return config, discovery
+
+
+def init_general(args) -> int:
+    config, discovery = perform_init(args)
+    errors = doctor(config, discovery)
+    print(f"Wrote {args.output}")
+    if errors:
+        print("Doctor findings:")
+        for error in errors:
+            print("- " + error)
+        return 2
+    print("Doctor: OK")
+    return 0
+
+
+def init_ado(args) -> int:
+    class Compat:
+        pass
+    compat = Compat()
+    compat.work_items = "azure-devops"
+    compat.ado_organization = args.organization
+    compat.ado_project = args.project
+    compat.ado_token_env = args.token_env
+    compat.role_provider = args.role_provider
+    compat.output = args.output
+    compat.force = args.force
+    compat.environment = "none"
+    compat.codespaces_mode = "off"
+    compat.no_files = True
+    compat.framework_ref = ""
+    config, discovery = perform_init(compat)
+    errors = doctor(config, discovery)
+    discovery_path = Path(args.output).with_suffix(Path(args.output).suffix + ".ado-discovery.json")
+    print(f"Wrote {args.output}")
+    print(f"Wrote {discovery_path}")
+    if errors:
+        print("Doctor findings:")
+        for error in errors:
+            print("- " + error)
+        return 2
+    print("Doctor: OK")
+    return 0
+
+
+def setup_cmd(args) -> int:
+    github_auth = None
+    if args.github_repository:
+        _, github_auth = resolve_github_token(args.github_auth, args.github_token_env)
+    provider_errors = validate_work_item_provider(args.work_items)
+    if provider_errors:
+        raise RuntimeError(provider_errors[0])
+
+    roles = parse_role_provider(args.role_provider)
+    agents = build_agents(roles)
+    providers = parse_ai_provider(args.ai_provider)
+    workers = parse_worker(args.worker)
+    environment = build_environment(args.environment, args.codespaces_mode)
+
+    discovery, suggestions = discover_provider(args)
+    ado_field_mapping = parse_ado_field_mapping(args.ado_field)
+    ado_mcp = None
+    if args.work_items in ("azure-devops", "composite") and args.ado_mcp_mode != "none":
+        ado_mcp = build_ado_mcp(
+            args.ado_organization,
+            mode=args.ado_mcp_mode,
+            auth=args.ado_mcp_auth,
+            project=args.ado_project,
+            team=args.ado_team,
+        )
+    mapping = suggestions
+    if not args.non_interactive:
+        print("Step 1/10: source host connected")
+        print("Step 2/10: repository context analyzed")
+        print("Step 3/10: work item provider selected:", args.work_items)
+        print("Step 4/10: work item provider connected")
+        print("Step 5/10: existing statuses discovered")
+        print("Step 6/10: confirm status mapping")
+        print("Step 8/10: workers registered:", len(workers))
+        mapping = interactive_mapping("azure-devops" if args.work_items == "composite" else args.work_items, discovery, suggestions)
+        if args.work_items in ("azure-devops", "composite") and not ado_field_mapping:
+            ado_field_mapping = interactive_ado_field_mapping(discovery)
+
+    workflow = {
+        "tdd": args.tdd,
+        "reviewer": {"mode": args.reviewer_mode},
+        "runtime_verification": {"mode": args.runtime_mode},
+    }
+    plan = build_setup_plan(
+        root=args.root,
+        work_items=args.work_items,
+        discovery=discovery,
+        mapping=mapping,
+        workflow=workflow,
+        agents=agents,
+        environment=environment,
+        providers=providers,
+        github_auth=github_auth,
+        ado_mcp=ado_mcp,
+        workers=workers,
+        ado_field_mapping=ado_field_mapping,
+    )
+    plan["work_items"]["mapping_confirmed"] = not args.plan_only
+    Path(args.plan_output).write_text(_dump_yaml(plan), encoding="utf-8")
+    print(render_user_steps(plan))
+    print(f"\nWrote setup plan: {args.plan_output}")
+
+    if args.plan_only:
+        return 0
+
+    if args.work_items == "github-issues":
+        discovery, mapping, created = apply_github_status_bootstrap(args, mapping)
+        if created:
+            print("Created managed GitHub status labels: " + ", ".join(created))
+
+    class InitArgs:
+        pass
+    init = InitArgs()
+    init.work_items = "azure-devops" if args.work_items == "composite" else args.work_items
+    init.ado_organization = args.ado_organization
+    init.ado_project = args.ado_project
+    init.ado_token_env = args.ado_token_env
+    init.role_provider = args.role_provider
+    init.output = args.output
+    init.force = args.force
+    init.environment = args.environment
+    init.codespaces_mode = args.codespaces_mode
+    init.no_files = args.no_files
+    init.framework_ref = args.framework_ref
+
+    config, _ = perform_init(init)
+    config["workflow"] = workflow
+    config["providers"] = providers
+    config["workers"] = workers
+    config["source_connection"] = {"github": github_auth or {}}
+    if ado_mcp:
+        config["mcp"] = {"azure_devops": ado_mcp}
+    if args.work_items == "github-issues":
+        config["work_items"]["github_issues"] = {
+            "repository": args.github_repository,
+            "state_mapping": mapping,
+        }
+    else:
+        config["work_items"]["azure_devops"]["state_mapping"] = mapping
+        config["work_items"]["azure_devops"]["field_mapping"] = ado_field_mapping
+        if args.work_items == "composite":
+            config["work_items"]["provider"] = "composite"
+            config["work_items"]["github_issues"] = {"repository": args.github_repository}
+            config["work_items"]["sync"] = {
+                "business_provider": "azure-devops",
+                "execution_provider": "github-issues",
+                "state_mode": "coarse",
+            }
+    framework_source, framework_version = parse_framework_ref(args.framework_ref)
+    config = ensure_framework_metadata(
+        config, source=framework_source, ref=framework_version
+    )
+    config["framework"]["source"] = framework_source
+    config["framework"]["ref"] = framework_version
+    Path(args.output).write_text(_dump_yaml(config), encoding="utf-8")
+    errors = doctor(config, discovery)
+    if errors:
+        print("Doctor findings:")
+        for error in errors:
+            print("- " + error)
+        return 2
+    print("Step 10/10: Doctor: OK")
+    return 0
+
+
+def update_cmd(args) -> int:
+    root = Path(args.root)
+    config_path = Path(args.config)
+    if not config_path.is_absolute():
+        config_path = root / config_path
+    if not config_path.exists():
+        raise RuntimeError(f"config not found: {config_path}")
+    config = _load_yaml(config_path)
+    meta = ensure_framework_metadata(config).get("framework", {})
+    target_ref = args.to or "main"
+    target_source = args.source or meta.get("source", DEFAULT_FRAMEWORK_SOURCE)
+    plan = build_update_plan(
+        config,
+        target_ref=target_ref,
+        target_source=target_source,
+    )
+
+    print(
+        f"Framework: {plan['current']['source']}@{plan['current']['ref']} "
+        f"-> {plan['target']['source']}@{plan['target']['ref']}"
+    )
+    print("Update available:", "yes" if plan["update_available"] else "no")
+    if args.check:
+        return 0
+
+    workflow_ref = (
+        f"{target_source}/.github/workflows/queue-dispatcher.yml@{target_ref}"
+    )
+    workflow = generated_github_caller(workflow_ref)
+    current_workflow_ref = (
+        f"{plan['current']['source']}/.github/workflows/queue-dispatcher.yml@"
+        f"{plan['current']['ref']}"
+    )
+    expected_current_workflow = generated_github_caller(current_workflow_ref)
+    updated, report = apply_update(
+        config,
+        target_ref=target_ref,
+        target_source=target_source,
+        generated_workflow=workflow,
+        expected_current_workflow=expected_current_workflow,
+        root=args.root,
+        force=args.force,
+    )
+    config_path.write_text(_dump_yaml(updated), encoding="utf-8")
+
+    print("Migrations:", ", ".join(report["migrations"]) or "none")
+    print("Changed files:", ", ".join(report["changed_files"]) or "none")
+    print("Preserved project files:", ", ".join(report["preserved_project_files"]))
+
+    errors = doctor(updated)
+    if errors:
+        print("Doctor findings:")
+        for error in errors:
+            print("- " + error)
+        return 2
+    print("Doctor: OK")
+    return 0
+
+
+def doctor_cmd(args) -> int:
+    config = _load_yaml(Path(args.config))
+    discovery = None
+    if args.discovery:
+        discovery = json.loads(Path(args.discovery).read_text(encoding="utf-8"))
+    errors = doctor(config, discovery)
+    if errors:
+        for error in errors:
+            print("ERROR: " + error)
+        return 2
+    print("Doctor: OK")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="ai-workflow")
+    parser.add_argument("--version", action="version", version=f"ai-workflow {PACKAGE_VERSION}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init")
+    init.add_argument("--work-items", choices=["github-issues", "azure-devops"], default="github-issues")
+    init.add_argument("--ado-organization")
+    init.add_argument("--ado-project")
+    init.add_argument("--ado-token-env", default="AZURE_DEVOPS_TOKEN")
+    init.add_argument("--environment", choices=["none", "codespaces"], default="none")
+    init.add_argument("--codespaces-mode", choices=["off", "on-demand", "always-on"], default="on-demand")
+    init.add_argument("--role-provider", action="append", default=[])
+    init.add_argument("--output", default=".ai-workflow.yml")
+    init.add_argument("--framework-ref", default="vuthethienlong/ai-dev-workflow/.github/workflows/queue-dispatcher.yml@main")
+    init.add_argument("--no-files", action="store_true")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(func=init_general)
+
+    init_ado_parser = sub.add_parser("init-ado")
+    init_ado_parser.add_argument("--organization", required=True)
+    init_ado_parser.add_argument("--project", required=True)
+    init_ado_parser.add_argument("--output", default=".ai-workflow.yml")
+    init_ado_parser.add_argument("--token-env", default="AZURE_DEVOPS_TOKEN")
+    init_ado_parser.add_argument("--role-provider", action="append", default=[])
+    init_ado_parser.add_argument("--force", action="store_true")
+    init_ado_parser.set_defaults(func=init_ado)
+
+    setup = sub.add_parser("setup")
+    setup.add_argument("--root", default=".")
+    setup.add_argument("--work-items", choices=["github-issues", "azure-devops", "composite"], default="github-issues")
+    setup.add_argument("--github-repository")
+    setup.add_argument("--github-token-env", default="GH_TOKEN")
+    setup.add_argument("--github-auth", choices=["gh-cli","token-env"], default="gh-cli")
+    setup.add_argument("--ado-organization")
+    setup.add_argument("--ado-project")
+    setup.add_argument("--ado-token-env", default="AZURE_DEVOPS_TOKEN")
+    setup.add_argument("--ado-mcp-mode", choices=["none","remote","local"], default="remote")
+    setup.add_argument("--ado-mcp-auth", choices=["interactive","azcli","env","envvar","pat"], default="interactive")
+    setup.add_argument("--ado-team")
+    setup.add_argument("--ado-field", action="append", default=[])
+    setup.add_argument("--environment", choices=["none", "codespaces"], default="none")
+    setup.add_argument("--codespaces-mode", choices=["off", "on-demand", "always-on"], default="on-demand")
+    setup.add_argument("--role-provider", action="append", default=[])
+    setup.add_argument("--ai-provider", action="append", default=[])
+    setup.add_argument("--worker", action="append", default=[])
+    setup.add_argument("--tdd", action=argparse.BooleanOptionalAction, default=True)
+    setup.add_argument("--reviewer-mode", choices=["manual", "automatic", "none"], default="manual")
+    setup.add_argument("--runtime-mode", choices=["project-defined", "batched", "none"], default="project-defined")
+    setup.add_argument("--output", default=".ai-workflow.yml")
+    setup.add_argument("--plan-output", default=".ai-setup-plan.yml")
+    setup.add_argument("--framework-ref", default="vuthethienlong/ai-dev-workflow/.github/workflows/queue-dispatcher.yml@main")
+    setup.add_argument("--plan-only", action="store_true")
+    setup.add_argument("--non-interactive", action="store_true")
+    setup.add_argument("--no-files", action="store_true")
+    setup.add_argument("--force", action="store_true")
+    setup.set_defaults(func=setup_cmd)
+
+    update = sub.add_parser("update")
+    update.add_argument("--config", default=".ai-workflow.yml")
+    update.add_argument("--root", default=".")
+    update.add_argument("--check", action="store_true")
+    update.add_argument("--to")
+    update.add_argument("--source")
+    update.add_argument("--force", action="store_true")
+    update.set_defaults(func=update_cmd)
+
+    doc = sub.add_parser("doctor")
+    doc.add_argument("--config", default=".ai-workflow.yml")
+    doc.add_argument("--discovery")
+    doc.set_defaults(func=doctor_cmd)
+
+    args = parser.parse_args()
+    if args.command in ("init", "setup") and args.work_items in ("azure-devops", "composite"):
+        if not args.ado_organization or not args.ado_project:
+            parser.error("--ado-organization and --ado-project are required for azure-devops")
+    if args.command == "setup" and args.work_items in ("github-issues", "composite") and not args.github_repository:
+        parser.error("--github-repository is required for GitHub status discovery")
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())