specify-cli 0.0.22__py3-none-any.whl → 0.9.5.dev0__py3-none-any.whl

specify_cli/__init__.py

@@ -6,7 +6,9 @@
 #     "rich",
 #     "platformdirs",
 #     "readchar",
-#     "httpx",
+#     "json5",
+#     "pyyaml",
+#     "packaging",
 # ]
 # ///
 """
@@ -24,402 +26,73 @@ Or install globally:
     specify init --here
 """
 
+import contextlib
 import os
-import subprocess
 import sys
 import zipfile
-import tempfile
-import shutil
-import shlex
 import json
+import yaml
 from pathlib import Path
-from typing import Optional, Tuple
+
+from typing import Any, Optional
 
 import typer
-import httpx
-from rich.console import Console
 from rich.panel import Panel
-from rich.progress import Progress, SpinnerColumn, TextColumn
-from rich.text import Text
-from rich.live import Live
 from rich.align import Align
 from rich.table import Table
-from rich.tree import Tree
-from typer.core import TyperGroup
-
-# For cross-platform keyboard input
-import readchar
-import ssl
-import truststore
-from datetime import datetime, timezone
-
-ssl_context = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
-client = httpx.Client(verify=ssl_context)
-
-def _github_token(cli_token: str | None = None) -> str | None:
-    """Return sanitized GitHub token (cli arg takes precedence) or None."""
-    return ((cli_token or os.getenv("GH_TOKEN") or os.getenv("GITHUB_TOKEN") or "").strip()) or None
-
-def _github_auth_headers(cli_token: str | None = None) -> dict:
-    """Return Authorization header dict only when a non-empty token exists."""
-    token = _github_token(cli_token)
-    return {"Authorization": f"Bearer {token}"} if token else {}
-
-def _parse_rate_limit_headers(headers: httpx.Headers) -> dict:
-    """Extract and parse GitHub rate-limit headers."""
-    info = {}
-    
-    # Standard GitHub rate-limit headers
-    if "X-RateLimit-Limit" in headers:
-        info["limit"] = headers.get("X-RateLimit-Limit")
-    if "X-RateLimit-Remaining" in headers:
-        info["remaining"] = headers.get("X-RateLimit-Remaining")
-    if "X-RateLimit-Reset" in headers:
-        reset_epoch = int(headers.get("X-RateLimit-Reset", "0"))
-        if reset_epoch:
-            reset_time = datetime.fromtimestamp(reset_epoch, tz=timezone.utc)
-            info["reset_epoch"] = reset_epoch
-            info["reset_time"] = reset_time
-            info["reset_local"] = reset_time.astimezone()
-    
-    # Retry-After header (seconds or HTTP-date)
-    if "Retry-After" in headers:
-        retry_after = headers.get("Retry-After")
-        try:
-            info["retry_after_seconds"] = int(retry_after)
-        except ValueError:
-            # HTTP-date format - not implemented, just store as string
-            info["retry_after"] = retry_after
-    
-    return info
-
-def _format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str) -> str:
-    """Format a user-friendly error message with rate-limit information."""
-    rate_info = _parse_rate_limit_headers(headers)
-    
-    lines = [f"GitHub API returned status {status_code} for {url}"]
-    lines.append("")
-    
-    if rate_info:
-        lines.append("[bold]Rate Limit Information:[/bold]")
-        if "limit" in rate_info:
-            lines.append(f"  • Rate Limit: {rate_info['limit']} requests/hour")
-        if "remaining" in rate_info:
-            lines.append(f"  • Remaining: {rate_info['remaining']}")
-        if "reset_local" in rate_info:
-            reset_str = rate_info["reset_local"].strftime("%Y-%m-%d %H:%M:%S %Z")
-            lines.append(f"  • Resets at: {reset_str}")
-        if "retry_after_seconds" in rate_info:
-            lines.append(f"  • Retry after: {rate_info['retry_after_seconds']} seconds")
-        lines.append("")
-    
-    # Add troubleshooting guidance
-    lines.append("[bold]Troubleshooting Tips:[/bold]")
-    lines.append("  • If you're on a shared CI or corporate environment, you may be rate-limited.")
-    lines.append("  • Consider using a GitHub token via --github-token or the GH_TOKEN/GITHUB_TOKEN")
-    lines.append("    environment variable to increase rate limits.")
-    lines.append("  • Authenticated requests have a limit of 5,000/hour vs 60/hour for unauthenticated.")
-    
-    return "\n".join(lines)
-
-# Agent configuration with name, folder, install URL, and CLI tool requirement
-AGENT_CONFIG = {
-    "copilot": {
-        "name": "GitHub Copilot",
-        "folder": ".github/",
-        "install_url": None,  # IDE-based, no CLI check needed
-        "requires_cli": False,
-    },
-    "claude": {
-        "name": "Claude Code",
-        "folder": ".claude/",
-        "install_url": "https://docs.anthropic.com/en/docs/claude-code/setup",
-        "requires_cli": True,
-    },
-    "gemini": {
-        "name": "Gemini CLI",
-        "folder": ".gemini/",
-        "install_url": "https://github.com/google-gemini/gemini-cli",
-        "requires_cli": True,
-    },
-    "cursor-agent": {
-        "name": "Cursor",
-        "folder": ".cursor/",
-        "install_url": None,  # IDE-based
-        "requires_cli": False,
-    },
-    "qwen": {
-        "name": "Qwen Code",
-        "folder": ".qwen/",
-        "install_url": "https://github.com/QwenLM/qwen-code",
-        "requires_cli": True,
-    },
-    "opencode": {
-        "name": "opencode",
-        "folder": ".opencode/",
-        "install_url": "https://opencode.ai",
-        "requires_cli": True,
-    },
-    "codex": {
-        "name": "Codex CLI",
-        "folder": ".codex/",
-        "install_url": "https://github.com/openai/codex",
-        "requires_cli": True,
-    },
-    "windsurf": {
-        "name": "Windsurf",
-        "folder": ".windsurf/",
-        "install_url": None,  # IDE-based
-        "requires_cli": False,
-    },
-    "kilocode": {
-        "name": "Kilo Code",
-        "folder": ".kilocode/",
-        "install_url": None,  # IDE-based
-        "requires_cli": False,
-    },
-    "auggie": {
-        "name": "Auggie CLI",
-        "folder": ".augment/",
-        "install_url": "https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli",
-        "requires_cli": True,
-    },
-    "codebuddy": {
-        "name": "CodeBuddy",
-        "folder": ".codebuddy/",
-        "install_url": "https://www.codebuddy.ai/cli",
-        "requires_cli": True,
-    },
-    "roo": {
-        "name": "Roo Code",
-        "folder": ".roo/",
-        "install_url": None,  # IDE-based
-        "requires_cli": False,
-    },
-    "q": {
-        "name": "Amazon Q Developer CLI",
-        "folder": ".amazonq/",
-        "install_url": "https://aws.amazon.com/developer/learning/q-developer-cli/",
-        "requires_cli": True,
-    },
-    "amp": {
-        "name": "Amp",
-        "folder": ".agents/",
-        "install_url": "https://ampcode.com/manual#install",
-        "requires_cli": True,
-    },
-    "shai": {
-        "name": "SHAI",
-        "folder": ".shai/",
-        "install_url": "https://github.com/ovh/shai",
-        "requires_cli": True,
-    },
-}
-
-SCRIPT_TYPE_CHOICES = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}
-
-CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"
-
-BANNER = """
-███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
-██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
-███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝ 
-╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝  
-███████║██║     ███████╗╚██████╗██║██║        ██║   
-╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝   
-"""
-
-TAGLINE = "GitHub Spec Kit - Spec-Driven Development Toolkit"
-class StepTracker:
-    """Track and render hierarchical steps without emojis, similar to Claude Code tree output.
-    Supports live auto-refresh via an attached refresh callback.
-    """
-    def __init__(self, title: str):
-        self.title = title
-        self.steps = []  # list of dicts: {key, label, status, detail}
-        self.status_order = {"pending": 0, "running": 1, "done": 2, "error": 3, "skipped": 4}
-        self._refresh_cb = None  # callable to trigger UI refresh
-
-    def attach_refresh(self, cb):
-        self._refresh_cb = cb
-
-    def add(self, key: str, label: str):
-        if key not in [s["key"] for s in self.steps]:
-            self.steps.append({"key": key, "label": label, "status": "pending", "detail": ""})
-            self._maybe_refresh()
-
-    def start(self, key: str, detail: str = ""):
-        self._update(key, status="running", detail=detail)
-
-    def complete(self, key: str, detail: str = ""):
-        self._update(key, status="done", detail=detail)
-
-    def error(self, key: str, detail: str = ""):
-        self._update(key, status="error", detail=detail)
-
-    def skip(self, key: str, detail: str = ""):
-        self._update(key, status="skipped", detail=detail)
-
-    def _update(self, key: str, status: str, detail: str):
-        for s in self.steps:
-            if s["key"] == key:
-                s["status"] = status
-                if detail:
-                    s["detail"] = detail
-                self._maybe_refresh()
-                return
-
-        self.steps.append({"key": key, "label": key, "status": status, "detail": detail})
-        self._maybe_refresh()
-
-    def _maybe_refresh(self):
-        if self._refresh_cb:
-            try:
-                self._refresh_cb()
-            except Exception:
-                pass
-
-    def render(self):
-        tree = Tree(f"[cyan]{self.title}[/cyan]", guide_style="grey50")
-        for step in self.steps:
-            label = step["label"]
-            detail_text = step["detail"].strip() if step["detail"] else ""
-
-            status = step["status"]
-            if status == "done":
-                symbol = "[green]●[/green]"
-            elif status == "pending":
-                symbol = "[green dim]○[/green dim]"
-            elif status == "running":
-                symbol = "[cyan]○[/cyan]"
-            elif status == "error":
-                symbol = "[red]●[/red]"
-            elif status == "skipped":
-                symbol = "[yellow]○[/yellow]"
-            else:
-                symbol = " "
-
-            if status == "pending":
-                # Entire line light gray (pending)
-                if detail_text:
-                    line = f"{symbol} [bright_black]{label} ({detail_text})[/bright_black]"
-                else:
-                    line = f"{symbol} [bright_black]{label}[/bright_black]"
-            else:
-                # Label white, detail (if any) light gray in parentheses
-                if detail_text:
-                    line = f"{symbol} [white]{label}[/white] [bright_black]({detail_text})[/bright_black]"
-                else:
-                    line = f"{symbol} [white]{label}[/white]"
-
-            tree.add(line)
-        return tree
-
-def get_key():
-    """Get a single keypress in a cross-platform way using readchar."""
-    key = readchar.readkey()
-
-    if key == readchar.key.UP or key == readchar.key.CTRL_P:
-        return 'up'
-    if key == readchar.key.DOWN or key == readchar.key.CTRL_N:
-        return 'down'
-
-    if key == readchar.key.ENTER:
-        return 'enter'
-
-    if key == readchar.key.ESC:
-        return 'escape'
-
-    if key == readchar.key.CTRL_C:
-        raise KeyboardInterrupt
-
-    return key
-
-def select_with_arrows(options: dict, prompt_text: str = "Select an option", default_key: str = None) -> str:
-    """
-    Interactive selection using arrow keys with Rich Live display.
-    
-    Args:
-        options: Dict with keys as option keys and values as descriptions
-        prompt_text: Text to show above the options
-        default_key: Default option key to start with
-        
-    Returns:
-        Selected option key
-    """
-    option_keys = list(options.keys())
-    if default_key and default_key in option_keys:
-        selected_index = option_keys.index(default_key)
-    else:
-        selected_index = 0
-
-    selected_key = None
-
-    def create_selection_panel():
-        """Create the selection panel with current selection highlighted."""
-        table = Table.grid(padding=(0, 2))
-        table.add_column(style="cyan", justify="left", width=3)
-        table.add_column(style="white", justify="left")
-
-        for i, key in enumerate(option_keys):
-            if i == selected_index:
-                table.add_row("▶", f"[cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
-            else:
-                table.add_row(" ", f"[cyan]{key}[/cyan] [dim]({options[key]})[/dim]")
-
-        table.add_row("", "")
-        table.add_row("", "[dim]Use ↑/↓ to navigate, Enter to select, Esc to cancel[/dim]")
-
-        return Panel(
-            table,
-            title=f"[bold]{prompt_text}[/bold]",
-            border_style="cyan",
-            padding=(1, 2)
-        )
-
-    console.print()
-
-    def run_selection_loop():
-        nonlocal selected_key, selected_index
-        with Live(create_selection_panel(), console=console, transient=True, auto_refresh=False) as live:
-            while True:
-                try:
-                    key = get_key()
-                    if key == 'up':
-                        selected_index = (selected_index - 1) % len(option_keys)
-                    elif key == 'down':
-                        selected_index = (selected_index + 1) % len(option_keys)
-                    elif key == 'enter':
-                        selected_key = option_keys[selected_index]
-                        break
-                    elif key == 'escape':
-                        console.print("\n[yellow]Selection cancelled[/yellow]")
-                        raise typer.Exit(1)
-
-                    live.update(create_selection_panel(), refresh=True)
-
-                except KeyboardInterrupt:
-                    console.print("\n[yellow]Selection cancelled[/yellow]")
-                    raise typer.Exit(1)
-
-    run_selection_loop()
-
-    if selected_key is None:
-        console.print("\n[red]Selection failed.[/red]")
-        raise typer.Exit(1)
-
-    return selected_key
-
-console = Console()
-
-class BannerGroup(TyperGroup):
-    """Custom group that shows banner before help."""
-
-    def format_help(self, ctx, formatter):
-        # Show banner before help
-        show_banner()
-        super().format_help(ctx, formatter)
+from .shared_infra import (
+    install_shared_infra as _install_shared_infra_impl,
+    refresh_shared_templates as _refresh_shared_templates_impl,
+)
 
+from ._console import (
+    BANNER as BANNER,
+    TAGLINE as TAGLINE,
+    BannerGroup,
+    StepTracker,
+    console,
+    get_key as get_key,
+    select_with_arrows as select_with_arrows,
+    show_banner,
+)
+from ._assets import (
+    _locate_bundled_extension,
+    _locate_bundled_preset,
+    _locate_bundled_workflow as _locate_bundled_workflow,
+    _locate_core_pack,
+    _repo_root,
+    get_speckit_version as get_speckit_version,
+)
+from ._utils import (
+    CLAUDE_LOCAL_PATH as CLAUDE_LOCAL_PATH,
+    CLAUDE_NPM_LOCAL_PATH as CLAUDE_NPM_LOCAL_PATH,
+    _display_project_path,
+    check_tool as check_tool,
+    handle_vscode_settings as handle_vscode_settings,
+    init_git_repo as init_git_repo,
+    is_git_repo as is_git_repo,
+    merge_json_files as merge_json_files,
+    run_command as run_command,
+)
+from ._version import (
+    GITHUB_API_LATEST as GITHUB_API_LATEST,
+    self_app as _self_app,
+    self_check as self_check,
+    self_upgrade as self_upgrade,
+)
+from ._agent_config import (
+    AGENT_CONFIG as AGENT_CONFIG,
+    AI_ASSISTANT_ALIASES as AI_ASSISTANT_ALIASES,
+    AI_ASSISTANT_HELP as AI_ASSISTANT_HELP,
+    DEFAULT_INIT_INTEGRATION as DEFAULT_INIT_INTEGRATION,
+    SCRIPT_TYPE_CHOICES as SCRIPT_TYPE_CHOICES,
+)
+from ._init_options import (
+    INIT_OPTIONS_FILE as INIT_OPTIONS_FILE,
+    is_ai_skills_enabled as _is_ai_skills_enabled,
+    load_init_options as load_init_options,
+    save_init_options as save_init_options,
+)
 
 app = typer.Typer(
     name="specify",
@@ -429,495 +102,158 @@ app = typer.Typer(
     cls=BannerGroup,
 )
 
-def show_banner():
-    """Display the ASCII art banner."""
-    banner_lines = BANNER.strip().split('\n')
-    colors = ["bright_blue", "blue", "cyan", "bright_cyan", "white", "bright_white"]
-
-    styled_banner = Text()
-    for i, line in enumerate(banner_lines):
-        color = colors[i % len(colors)]
-        styled_banner.append(line + "\n", style=color)
-
-    console.print(Align.center(styled_banner))
-    console.print(Align.center(Text(TAGLINE, style="italic bright_yellow")))
-    console.print()
+def _version_callback(value: bool):
+    if value:
+        console.print(f"specify {get_speckit_version()}")
+        raise typer.Exit()
 
 @app.callback()
-def callback(ctx: typer.Context):
+def callback(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-V", callback=_version_callback, is_eager=True, help="Show version and exit."),
+):
     """Show banner when no subcommand is provided."""
     if ctx.invoked_subcommand is None and "--help" not in sys.argv and "-h" not in sys.argv:
         show_banner()
         console.print(Align.center("[dim]Run 'specify --help' for usage information[/dim]"))
         console.print()
 
-def run_command(cmd: list[str], check_return: bool = True, capture: bool = False, shell: bool = False) -> Optional[str]:
-    """Run a shell command and optionally capture output."""
-    try:
-        if capture:
-            result = subprocess.run(cmd, check=check_return, capture_output=True, text=True, shell=shell)
-            return result.stdout.strip()
-        else:
-            subprocess.run(cmd, check=check_return, shell=shell)
-            return None
-    except subprocess.CalledProcessError as e:
-        if check_return:
-            console.print(f"[red]Error running command:[/red] {' '.join(cmd)}")
-            console.print(f"[red]Exit code:[/red] {e.returncode}")
-            if hasattr(e, 'stderr') and e.stderr:
-                console.print(f"[red]Error output:[/red] {e.stderr}")
-            raise
-        return None
-
-def check_tool(tool: str, tracker: StepTracker = None) -> bool:
-    """Check if a tool is installed. Optionally update tracker.
-    
-    Args:
-        tool: Name of the tool to check
-        tracker: Optional StepTracker to update with results
-        
-    Returns:
-        True if tool is found, False otherwise
-    """
-    # Special handling for Claude CLI after `claude migrate-installer`
-    # See: https://github.com/github/spec-kit/issues/123
-    # The migrate-installer command REMOVES the original executable from PATH
-    # and creates an alias at ~/.claude/local/claude instead
-    # This path should be prioritized over other claude executables in PATH
-    if tool == "claude":
-        if CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():
-            if tracker:
-                tracker.complete(tool, "available")
-            return True
-    
-    found = shutil.which(tool) is not None
-    
-    if tracker:
-        if found:
-            tracker.complete(tool, "available")
-        else:
-            tracker.error(tool, "not found")
-    
-    return found
-
-def is_git_repo(path: Path = None) -> bool:
-    """Check if the specified path is inside a git repository."""
-    if path is None:
-        path = Path.cwd()
-    
-    if not path.is_dir():
-        return False
-
-    try:
-        # Use git command to check if inside a work tree
-        subprocess.run(
-            ["git", "rev-parse", "--is-inside-work-tree"],
-            check=True,
-            capture_output=True,
-            cwd=path,
-        )
-        return True
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        return False
-
-def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Optional[str]]:
-    """Initialize a git repository in the specified path.
-    
-    Args:
-        project_path: Path to initialize git repository in
-        quiet: if True suppress console output (tracker handles status)
-    
-    Returns:
-        Tuple of (success: bool, error_message: Optional[str])
-    """
-    try:
-        original_cwd = Path.cwd()
-        os.chdir(project_path)
-        if not quiet:
-            console.print("[cyan]Initializing git repository...[/cyan]")
-        subprocess.run(["git", "init"], check=True, capture_output=True, text=True)
-        subprocess.run(["git", "add", "."], check=True, capture_output=True, text=True)
-        subprocess.run(["git", "commit", "-m", "Initial commit from Specify template"], check=True, capture_output=True, text=True)
-        if not quiet:
-            console.print("[green]✓[/green] Git repository initialized")
-        return True, None
-
-    except subprocess.CalledProcessError as e:
-        error_msg = f"Command: {' '.join(e.cmd)}\nExit code: {e.returncode}"
-        if e.stderr:
-            error_msg += f"\nError: {e.stderr.strip()}"
-        elif e.stdout:
-            error_msg += f"\nOutput: {e.stdout.strip()}"
-        
-        if not quiet:
-            console.print(f"[red]Error initializing git repository:[/red] {e}")
-        return False, error_msg
-    finally:
-        os.chdir(original_cwd)
-
-def handle_vscode_settings(sub_item, dest_file, rel_path, verbose=False, tracker=None) -> None:
-    """Handle merging or copying of .vscode/settings.json files."""
-    def log(message, color="green"):
-        if verbose and not tracker:
-            console.print(f"[{color}]{message}[/] {rel_path}")
-
-    try:
-        with open(sub_item, 'r', encoding='utf-8') as f:
-            new_settings = json.load(f)
-
-        if dest_file.exists():
-            merged = merge_json_files(dest_file, new_settings, verbose=verbose and not tracker)
-            with open(dest_file, 'w', encoding='utf-8') as f:
-                json.dump(merged, f, indent=4)
-                f.write('\n')
-            log("Merged:", "green")
-        else:
-            shutil.copy2(sub_item, dest_file)
-            log("Copied (no existing settings.json):", "blue")
-
-    except Exception as e:
-        log(f"Warning: Could not merge, copying instead: {e}", "yellow")
-        shutil.copy2(sub_item, dest_file)
-
-def merge_json_files(existing_path: Path, new_content: dict, verbose: bool = False) -> dict:
-    """Merge new JSON content into existing JSON file.
-
-    Performs a deep merge where:
-    - New keys are added
-    - Existing keys are preserved unless overwritten by new content
-    - Nested dictionaries are merged recursively
-    - Lists and other values are replaced (not merged)
+def _refresh_shared_templates(
+    project_path: Path,
+    *,
+    invoke_separator: str,
+    force: bool = False,
+) -> None:
+    """Refresh default-sensitive shared templates without touching scripts."""
+    _refresh_shared_templates_impl(
+        project_path,
+        version=get_speckit_version(),
+        core_pack=_locate_core_pack(),
+        repo_root=_repo_root(),
+        console=console,
+        invoke_separator=invoke_separator,
+        force=force,
+    )
 
-    Args:
-        existing_path: Path to existing JSON file
-        new_content: New JSON content to merge in
-        verbose: Whether to print merge details
 
-    Returns:
-        Merged JSON content as dict
+def _install_shared_infra(
+    project_path: Path,
+    script_type: str,
+    tracker: StepTracker | None = None,
+    force: bool = False,
+    invoke_separator: str = ".",
+    refresh_managed: bool = False,
+    refresh_hint: str | None = None,
+) -> bool:
+    """Install shared infrastructure files into *project_path*.
+
+    Copies ``.specify/scripts/<variant>/`` and ``.specify/templates/`` from
+    the bundled core_pack or source checkout, where ``<variant>`` is
+    ``bash`` when *script_type* is ``"sh"`` and ``powershell`` when it is
+    ``"ps"``.  Tracks all installed files in ``speckit.manifest.json``.
+
+    Shared scripts and page templates are processed to resolve
+    ``__SPECKIT_COMMAND_<NAME>__`` placeholders using *invoke_separator*
+    (``"."`` for markdown agents, ``"-"`` for skills agents).
+
+    Overwrite policy:
+
+    * ``force=True``  — overwrite every existing file (still skips symlinks
+      to avoid following links outside the project root).
+    * ``refresh_managed=True`` — overwrite only files whose on-disk hash
+      still matches the previously recorded manifest hash (i.e. unmodified
+      files installed by spec-kit). Files with diverging hashes are
+      treated as user customizations and preserved with a warning.
+    * Default — only add missing files; existing ones are skipped.
+
+    *refresh_hint* — caller-supplied rich-text fragment shown after the
+    "Preserved customized files" warning to tell the user which flag/command
+    they should re-run with to overwrite their customizations. Each caller
+    passes the flag that's actually valid in its CLI surface (e.g.
+    ``--refresh-shared-infra`` for ``integration switch``,
+    ``--force`` for ``init``/``integration upgrade``). When ``None``, no
+    remediation hint is printed for customizations.
+
+    Returns ``True`` on success.
     """
-    try:
-        with open(existing_path, 'r', encoding='utf-8') as f:
-            existing_content = json.load(f)
-    except (FileNotFoundError, json.JSONDecodeError):
-        # If file doesn't exist or is invalid, just use new content
-        return new_content
-
-    def deep_merge(base: dict, update: dict) -> dict:
-        """Recursively merge update dict into base dict."""
-        result = base.copy()
-        for key, value in update.items():
-            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
-                # Recursively merge nested dictionaries
-                result[key] = deep_merge(result[key], value)
-            else:
-                # Add new key or replace existing value
-                result[key] = value
-        return result
-
-    merged = deep_merge(existing_content, new_content)
-
-    if verbose:
-        console.print(f"[cyan]Merged JSON file:[/cyan] {existing_path.name}")
-
-    return merged
-
-def download_template_from_github(ai_assistant: str, download_dir: Path, *, script_type: str = "sh", verbose: bool = True, show_progress: bool = True, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Tuple[Path, dict]:
-    repo_owner = "github"
-    repo_name = "spec-kit"
-    if client is None:
-        client = httpx.Client(verify=ssl_context)
-
-    if verbose:
-        console.print("[cyan]Fetching latest release information...[/cyan]")
-    api_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest"
-
-    try:
-        response = client.get(
-            api_url,
-            timeout=30,
-            follow_redirects=True,
-            headers=_github_auth_headers(github_token),
-        )
-        status = response.status_code
-        if status != 200:
-            # Format detailed error message with rate-limit info
-            error_msg = _format_rate_limit_error(status, response.headers, api_url)
-            if debug:
-                error_msg += f"\n\n[dim]Response body (truncated 500):[/dim]\n{response.text[:500]}"
-            raise RuntimeError(error_msg)
-        try:
-            release_data = response.json()
-        except ValueError as je:
-            raise RuntimeError(f"Failed to parse release JSON: {je}\nRaw (truncated 400): {response.text[:400]}")
-    except Exception as e:
-        console.print(f"[red]Error fetching release information[/red]")
-        console.print(Panel(str(e), title="Fetch Error", border_style="red"))
-        raise typer.Exit(1)
-
-    assets = release_data.get("assets", [])
-    pattern = f"spec-kit-template-{ai_assistant}-{script_type}"
-    matching_assets = [
-        asset for asset in assets
-        if pattern in asset["name"] and asset["name"].endswith(".zip")
-    ]
-
-    asset = matching_assets[0] if matching_assets else None
-
-    if asset is None:
-        console.print(f"[red]No matching release asset found[/red] for [bold]{ai_assistant}[/bold] (expected pattern: [bold]{pattern}[/bold])")
-        asset_names = [a.get('name', '?') for a in assets]
-        console.print(Panel("\n".join(asset_names) or "(no assets)", title="Available Assets", border_style="yellow"))
-        raise typer.Exit(1)
-
-    download_url = asset["browser_download_url"]
-    filename = asset["name"]
-    file_size = asset["size"]
-
-    if verbose:
-        console.print(f"[cyan]Found template:[/cyan] {filename}")
-        console.print(f"[cyan]Size:[/cyan] {file_size:,} bytes")
-        console.print(f"[cyan]Release:[/cyan] {release_data['tag_name']}")
-
-    zip_path = download_dir / filename
-    if verbose:
-        console.print(f"[cyan]Downloading template...[/cyan]")
-
-    try:
-        with client.stream(
-            "GET",
-            download_url,
-            timeout=60,
-            follow_redirects=True,
-            headers=_github_auth_headers(github_token),
-        ) as response:
-            if response.status_code != 200:
-                # Handle rate-limiting on download as well
-                error_msg = _format_rate_limit_error(response.status_code, response.headers, download_url)
-                if debug:
-                    error_msg += f"\n\n[dim]Response body (truncated 400):[/dim]\n{response.text[:400]}"
-                raise RuntimeError(error_msg)
-            total_size = int(response.headers.get('content-length', 0))
-            with open(zip_path, 'wb') as f:
-                if total_size == 0:
-                    for chunk in response.iter_bytes(chunk_size=8192):
-                        f.write(chunk)
-                else:
-                    if show_progress:
-                        with Progress(
-                            SpinnerColumn(),
-                            TextColumn("[progress.description]{task.description}"),
-                            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
-                            console=console,
-                        ) as progress:
-                            task = progress.add_task("Downloading...", total=total_size)
-                            downloaded = 0
-                            for chunk in response.iter_bytes(chunk_size=8192):
-                                f.write(chunk)
-                                downloaded += len(chunk)
-                                progress.update(task, completed=downloaded)
-                    else:
-                        for chunk in response.iter_bytes(chunk_size=8192):
-                            f.write(chunk)
-    except Exception as e:
-        console.print(f"[red]Error downloading template[/red]")
-        detail = str(e)
-        if zip_path.exists():
-            zip_path.unlink()
-        console.print(Panel(detail, title="Download Error", border_style="red"))
-        raise typer.Exit(1)
-    if verbose:
-        console.print(f"Downloaded: {filename}")
-    metadata = {
-        "filename": filename,
-        "size": file_size,
-        "release": release_data["tag_name"],
-        "asset_url": download_url
-    }
-    return zip_path, metadata
+    return _install_shared_infra_impl(
+        project_path,
+        script_type,
+        version=get_speckit_version(),
+        core_pack=_locate_core_pack(),
+        repo_root=_repo_root(),
+        console=console,
+        force=force,
+        invoke_separator=invoke_separator,
+        refresh_managed=refresh_managed,
+        refresh_hint=refresh_hint,
+    )
 
-def download_and_extract_template(project_path: Path, ai_assistant: str, script_type: str, is_current_dir: bool = False, *, verbose: bool = True, tracker: StepTracker | None = None, client: httpx.Client = None, debug: bool = False, github_token: str = None) -> Path:
-    """Download the latest release and extract it to create a new project.
-    Returns project_path. Uses tracker if provided (with keys: fetch, download, extract, cleanup)
-    """
-    current_dir = Path.cwd()
 
-    if tracker:
-        tracker.start("fetch", "contacting GitHub API")
+def _install_shared_infra_or_exit(
+    project_path: Path,
+    script_type: str,
+    tracker: StepTracker | None = None,
+    force: bool = False,
+    invoke_separator: str = ".",
+    refresh_managed: bool = False,
+    refresh_hint: str | None = None,
+) -> bool:
     try:
-        zip_path, meta = download_template_from_github(
-            ai_assistant,
-            current_dir,
-            script_type=script_type,
-            verbose=verbose and tracker is None,
-            show_progress=(tracker is None),
-            client=client,
-            debug=debug,
-            github_token=github_token
+        return _install_shared_infra(
+            project_path,
+            script_type,
+            tracker=tracker,
+            force=force,
+            invoke_separator=invoke_separator,
+            refresh_managed=refresh_managed,
+            refresh_hint=refresh_hint,
         )
-        if tracker:
-            tracker.complete("fetch", f"release {meta['release']} ({meta['size']:,} bytes)")
-            tracker.add("download", "Download template")
-            tracker.complete("download", meta['filename'])
-    except Exception as e:
-        if tracker:
-            tracker.error("fetch", str(e))
-        else:
-            if verbose:
-                console.print(f"[red]Error downloading template:[/red] {e}")
-        raise
-
-    if tracker:
-        tracker.add("extract", "Extract template")
-        tracker.start("extract")
-    elif verbose:
-        console.print("Extracting template...")
-
-    try:
-        if not is_current_dir:
-            project_path.mkdir(parents=True)
-
-        with zipfile.ZipFile(zip_path, 'r') as zip_ref:
-            zip_contents = zip_ref.namelist()
-            if tracker:
-                tracker.start("zip-list")
-                tracker.complete("zip-list", f"{len(zip_contents)} entries")
-            elif verbose:
-                console.print(f"[cyan]ZIP contains {len(zip_contents)} items[/cyan]")
-
-            if is_current_dir:
-                with tempfile.TemporaryDirectory() as temp_dir:
-                    temp_path = Path(temp_dir)
-                    zip_ref.extractall(temp_path)
-
-                    extracted_items = list(temp_path.iterdir())
-                    if tracker:
-                        tracker.start("extracted-summary")
-                        tracker.complete("extracted-summary", f"temp {len(extracted_items)} items")
-                    elif verbose:
-                        console.print(f"[cyan]Extracted {len(extracted_items)} items to temp location[/cyan]")
-
-                    source_dir = temp_path
-                    if len(extracted_items) == 1 and extracted_items[0].is_dir():
-                        source_dir = extracted_items[0]
-                        if tracker:
-                            tracker.add("flatten", "Flatten nested directory")
-                            tracker.complete("flatten")
-                        elif verbose:
-                            console.print(f"[cyan]Found nested directory structure[/cyan]")
-
-                    for item in source_dir.iterdir():
-                        dest_path = project_path / item.name
-                        if item.is_dir():
-                            if dest_path.exists():
-                                if verbose and not tracker:
-                                    console.print(f"[yellow]Merging directory:[/yellow] {item.name}")
-                                for sub_item in item.rglob('*'):
-                                    if sub_item.is_file():
-                                        rel_path = sub_item.relative_to(item)
-                                        dest_file = dest_path / rel_path
-                                        dest_file.parent.mkdir(parents=True, exist_ok=True)
-                                        # Special handling for .vscode/settings.json - merge instead of overwrite
-                                        if dest_file.name == "settings.json" and dest_file.parent.name == ".vscode":
-                                            handle_vscode_settings(sub_item, dest_file, rel_path, verbose, tracker)
-                                        else:
-                                            shutil.copy2(sub_item, dest_file)
-                            else:
-                                shutil.copytree(item, dest_path)
-                        else:
-                            if dest_path.exists() and verbose and not tracker:
-                                console.print(f"[yellow]Overwriting file:[/yellow] {item.name}")
-                            shutil.copy2(item, dest_path)
-                    if verbose and not tracker:
-                        console.print(f"[cyan]Template files merged into current directory[/cyan]")
-            else:
-                zip_ref.extractall(project_path)
-
-                extracted_items = list(project_path.iterdir())
-                if tracker:
-                    tracker.start("extracted-summary")
-                    tracker.complete("extracted-summary", f"{len(extracted_items)} top-level items")
-                elif verbose:
-                    console.print(f"[cyan]Extracted {len(extracted_items)} items to {project_path}:[/cyan]")
-                    for item in extracted_items:
-                        console.print(f"  - {item.name} ({'dir' if item.is_dir() else 'file'})")
-
-                if len(extracted_items) == 1 and extracted_items[0].is_dir():
-                    nested_dir = extracted_items[0]
-                    temp_move_dir = project_path.parent / f"{project_path.name}_temp"
-
-                    shutil.move(str(nested_dir), str(temp_move_dir))
-
-                    project_path.rmdir()
-
-                    shutil.move(str(temp_move_dir), str(project_path))
-                    if tracker:
-                        tracker.add("flatten", "Flatten nested directory")
-                        tracker.complete("flatten")
-                    elif verbose:
-                        console.print(f"[cyan]Flattened nested directory structure[/cyan]")
-
-    except Exception as e:
-        if tracker:
-            tracker.error("extract", str(e))
-        else:
-            if verbose:
-                console.print(f"[red]Error extracting template:[/red] {e}")
-                if debug:
-                    console.print(Panel(str(e), title="Extraction Error", border_style="red"))
-
-        if not is_current_dir and project_path.exists():
-            shutil.rmtree(project_path)
+    except (ValueError, OSError) as exc:
+        console.print(f"[red]Error:[/red] Failed to install shared infrastructure: {exc}")
         raise typer.Exit(1)
-    else:
-        if tracker:
-            tracker.complete("extract")
-    finally:
-        if tracker:
-            tracker.add("cleanup", "Remove temporary archive")
-
-        if zip_path.exists():
-            zip_path.unlink()
-            if tracker:
-                tracker.complete("cleanup")
-            elif verbose:
-                console.print(f"Cleaned up: {zip_path.name}")
-
-    return project_path
 
 
 def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None = None) -> None:
-    """Ensure POSIX .sh scripts under .specify/scripts (recursively) have execute bits (no-op on Windows)."""
+    """Ensure POSIX .sh scripts under .specify/scripts and .specify/extensions (recursively) have execute bits (no-op on Windows)."""
     if os.name == "nt":
         return  # Windows: skip silently
-    scripts_root = project_path / ".specify" / "scripts"
-    if not scripts_root.is_dir():
-        return
+    scan_roots = [
+        project_path / ".specify" / "scripts",
+        project_path / ".specify" / "extensions",
+    ]
     failures: list[str] = []
     updated = 0
-    for script in scripts_root.rglob("*.sh"):
-        try:
-            if script.is_symlink() or not script.is_file():
-                continue
+    for scripts_root in scan_roots:
+        if not scripts_root.is_dir():
+            continue
+        for script in scripts_root.rglob("*.sh"):
             try:
-                with script.open("rb") as f:
-                    if f.read(2) != b"#!":
-                        continue
-            except Exception:
-                continue
-            st = script.stat(); mode = st.st_mode
-            if mode & 0o111:
-                continue
-            new_mode = mode
-            if mode & 0o400: new_mode |= 0o100
-            if mode & 0o040: new_mode |= 0o010
-            if mode & 0o004: new_mode |= 0o001
-            if not (new_mode & 0o100):
-                new_mode |= 0o100
-            os.chmod(script, new_mode)
-            updated += 1
-        except Exception as e:
-            failures.append(f"{script.relative_to(scripts_root)}: {e}")
+                if script.is_symlink() or not script.is_file():
+                    continue
+                try:
+                    with script.open("rb") as f:
+                        if f.read(2) != b"#!":
+                            continue
+                except Exception:
+                    continue
+                st = script.stat()
+                mode = st.st_mode
+                if mode & 0o111:
+                    continue
+                new_mode = mode
+                if mode & 0o400:
+                    new_mode |= 0o100
+                if mode & 0o040:
+                    new_mode |= 0o010
+                if mode & 0o004:
+                    new_mode |= 0o001
+                if not (new_mode & 0o100):
+                    new_mode |= 0o100
+                os.chmod(script, new_mode)
+                updated += 1
+            except Exception as e:
+                failures.append(f"{_display_project_path(project_path, script)}: {e}")
     if tracker:
         detail = f"{updated} updated" + (f", {len(failures)} failed" if failures else "")
         tracker.add("chmod", "Set script permissions recursively")
@@ -930,303 +266,186 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None =
             for f in failures:
                 console.print(f"  - {f}")
 
-@app.command()
-def init(
-    project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"),
-    ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, shai, or q"),
-    script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"),
-    ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for AI agent tools like Claude Code"),
-    no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"),
-    here: bool = typer.Option(False, "--here", help="Initialize project in the current directory instead of creating a new one"),
-    force: bool = typer.Option(False, "--force", help="Force merge/overwrite when using --here (skip confirmation)"),
-    skip_tls: bool = typer.Option(False, "--skip-tls", help="Skip SSL/TLS verification (not recommended)"),
-    debug: bool = typer.Option(False, "--debug", help="Show verbose diagnostic output for network and extraction failures"),
-    github_token: str = typer.Option(None, "--github-token", help="GitHub token to use for API requests (or set GH_TOKEN or GITHUB_TOKEN environment variable)"),
-):
-    """
-    Initialize a new Specify project from the latest template.
-    
-    This command will:
-    1. Check that required tools are installed (git is optional)
-    2. Let you choose your AI assistant
-    3. Download the appropriate template from GitHub
-    4. Extract the template to a new project directory or current directory
-    5. Initialize a fresh git repository (if not --no-git and no existing repo)
-    6. Optionally set up AI assistant commands
-    
-    Examples:
-        specify init my-project
-        specify init my-project --ai claude
-        specify init my-project --ai copilot --no-git
-        specify init --ignore-agent-tools my-project
-        specify init . --ai claude         # Initialize in current directory
-        specify init .                     # Initialize in current directory (interactive AI selection)
-        specify init --here --ai claude    # Alternative syntax for current directory
-        specify init --here --ai codex
-        specify init --here --ai codebuddy
-        specify init --here
-        specify init --here --force  # Skip confirmation when current directory not empty
-    """
+# ---------------------------------------------------------------------------
+# Agent-context extension config helpers
+# ---------------------------------------------------------------------------
 
-    show_banner()
+_AGENT_CTX_EXT_CONFIG = (
+    Path(".specify") / "extensions" / "agent-context" / "agent-context-config.yml"
+)
 
-    if project_name == ".":
-        here = True
-        project_name = None  # Clear project_name to use existing validation logic
 
-    if here and project_name:
-        console.print("[red]Error:[/red] Cannot specify both project name and --here flag")
-        raise typer.Exit(1)
+def _load_agent_context_config(project_root: Path) -> dict[str, Any]:
+    """Load the agent-context extension config, returning defaults on failure."""
+    from .integrations.base import IntegrationBase
 
-    if not here and not project_name:
-        console.print("[red]Error:[/red] Must specify either a project name, use '.' for current directory, or use --here flag")
-        raise typer.Exit(1)
+    defaults: dict[str, Any] = {
+        "context_file": "",
+        "context_markers": {
+            "start": IntegrationBase.CONTEXT_MARKER_START,
+            "end": IntegrationBase.CONTEXT_MARKER_END,
+        },
+    }
+    path = project_root / _AGENT_CTX_EXT_CONFIG
+    if not path.exists():
+        return defaults
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, yaml.YAMLError):
+        return defaults
+    if not isinstance(raw, dict):
+        return defaults
+    return raw
+
+
+def _save_agent_context_config(
+    project_root: Path, config: dict[str, Any]
+) -> None:
+    """Persist *config* to the agent-context extension config file."""
+    path = project_root / _AGENT_CTX_EXT_CONFIG
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(config, default_flow_style=False, sort_keys=False), encoding="utf-8")
+
+
+def _update_agent_context_config_file(
+    project_root: Path,
+    context_file: str | None,
+    *,
+    preserve_markers: bool = True,
+) -> None:
+    """Update the agent-context extension config with *context_file*.
+
+    When *preserve_markers* is True (default), any existing
+    ``context_markers`` values are kept unchanged so user customisations
+    survive integration changes and reinit.  When False, the default
+    markers are written unconditionally.
+    """
+    from .integrations.base import IntegrationBase
 
-    if here:
-        project_name = Path.cwd().name
-        project_path = Path.cwd()
+    cfg = _load_agent_context_config(project_root)
+    cfg["context_file"] = context_file or ""
+    if not preserve_markers or not isinstance(cfg.get("context_markers"), dict):
+        cfg["context_markers"] = {
+            "start": IntegrationBase.CONTEXT_MARKER_START,
+            "end": IntegrationBase.CONTEXT_MARKER_END,
+        }
+    _save_agent_context_config(project_root, cfg)
 
-        existing_items = list(project_path.iterdir())
-        if existing_items:
-            console.print(f"[yellow]Warning:[/yellow] Current directory is not empty ({len(existing_items)} items)")
-            console.print("[yellow]Template files will be merged with existing content and may overwrite existing files[/yellow]")
-            if force:
-                console.print("[cyan]--force supplied: skipping confirmation and proceeding with merge[/cyan]")
-            else:
-                response = typer.confirm("Do you want to continue?")
-                if not response:
-                    console.print("[yellow]Operation cancelled[/yellow]")
-                    raise typer.Exit(0)
-    else:
-        project_path = Path(project_name).resolve()
-        if project_path.exists():
-            error_panel = Panel(
-                f"Directory '[cyan]{project_name}[/cyan]' already exists\n"
-                "Please choose a different project name or remove the existing directory.",
-                title="[red]Directory Conflict[/red]",
-                border_style="red",
-                padding=(1, 2)
-            )
-            console.print()
-            console.print(error_panel)
-            raise typer.Exit(1)
 
-    current_dir = Path.cwd()
+def _get_skills_dir(project_path: Path, selected_ai: str) -> Path:
+    """Resolve the agent-specific skills directory.
 
-    setup_lines = [
-        "[cyan]Specify Project Setup[/cyan]",
-        "",
-        f"{'Project':<15} [green]{project_path.name}[/green]",
-        f"{'Working Path':<15} [dim]{current_dir}[/dim]",
-    ]
+    Returns ``project_path / <agent_folder> / "skills"``, falling back
+    to ``project_path / ".agents/skills"`` for unknown agents.
+    """
+    agent_config = AGENT_CONFIG.get(selected_ai, {})
+    agent_folder = agent_config.get("folder", "")
+    if agent_folder:
+        return project_path / agent_folder.rstrip("/") / "skills"
+    return project_path / ".agents" / "skills"
 
-    if not here:
-        setup_lines.append(f"{'Target Path':<15} [dim]{project_path}[/dim]")
 
-    console.print(Panel("\n".join(setup_lines), border_style="cyan", padding=(1, 2)))
+def resolve_active_skills_dir(project_root: Path) -> Path | None:
+    """Return the active skills directory, creating it on demand when enabled.
 
-    should_init_git = False
-    if not no_git:
-        should_init_git = check_tool("git")
-        if not should_init_git:
-            console.print("[yellow]Git not found - will skip repository initialization[/yellow]")
+    Reads ``.specify/init-options.json`` to determine whether skills are
+    enabled and which agent was selected.  Only ``ai_skills`` set to boolean
+    ``True`` creates the directory safely (symlink/containment checks); when
+    ``ai_skills`` is not boolean ``True``, only Kimi's native-skills fallback
+    is honoured, and the native skills directory must already exist.
 
-    if ai_assistant:
-        if ai_assistant not in AGENT_CONFIG:
-            console.print(f"[red]Error:[/red] Invalid AI assistant '{ai_assistant}'. Choose from: {', '.join(AGENT_CONFIG.keys())}")
-            raise typer.Exit(1)
-        selected_ai = ai_assistant
-    else:
-        # Create options dict for selection (agent_key: display_name)
-        ai_choices = {key: config["name"] for key, config in AGENT_CONFIG.items()}
-        selected_ai = select_with_arrows(
-            ai_choices, 
-            "Choose your AI assistant:", 
-            "copilot"
-        )
+    Returns:
+        The skills directory ``Path``, or ``None`` if skills are not active.
 
-    if not ignore_agent_tools:
-        agent_config = AGENT_CONFIG.get(selected_ai)
-        if agent_config and agent_config["requires_cli"]:
-            install_url = agent_config["install_url"]
-            if not check_tool(selected_ai):
-                error_panel = Panel(
-                    f"[cyan]{selected_ai}[/cyan] not found\n"
-                    f"Install from: [cyan]{install_url}[/cyan]\n"
-                    f"{agent_config['name']} is required to continue with this project type.\n\n"
-                    "Tip: Use [cyan]--ignore-agent-tools[/cyan] to skip this check",
-                    title="[red]Agent Detection Error[/red]",
-                    border_style="red",
-                    padding=(1, 2)
-                )
-                console.print()
-                console.print(error_panel)
-                raise typer.Exit(1)
+    Raises:
+        ValueError: If the resolved skills path escapes the project root,
+            a parent component is a symlink, or a path component exists
+            but is not a directory.
+        OSError: If the directory cannot be created (e.g. permission denied).
+    """
+    from .shared_infra import _ensure_safe_shared_directory
 
-    if script_type:
-        if script_type not in SCRIPT_TYPE_CHOICES:
-            console.print(f"[red]Error:[/red] Invalid script type '{script_type}'. Choose from: {', '.join(SCRIPT_TYPE_CHOICES.keys())}")
-            raise typer.Exit(1)
-        selected_script = script_type
-    else:
-        default_script = "ps" if os.name == "nt" else "sh"
+    opts = load_init_options(project_root)
+    if not isinstance(opts, dict):
+        opts = {}
 
-        if sys.stdin.isatty():
-            selected_script = select_with_arrows(SCRIPT_TYPE_CHOICES, "Choose script type (or press Enter)", default_script)
-        else:
-            selected_script = default_script
-
-    console.print(f"[cyan]Selected AI assistant:[/cyan] {selected_ai}")
-    console.print(f"[cyan]Selected script type:[/cyan] {selected_script}")
-
-    tracker = StepTracker("Initialize Specify Project")
-
-    sys._specify_tracker_active = True
-
-    tracker.add("precheck", "Check required tools")
-    tracker.complete("precheck", "ok")
-    tracker.add("ai-select", "Select AI assistant")
-    tracker.complete("ai-select", f"{selected_ai}")
-    tracker.add("script-select", "Select script type")
-    tracker.complete("script-select", selected_script)
-    for key, label in [
-        ("fetch", "Fetch latest release"),
-        ("download", "Download template"),
-        ("extract", "Extract template"),
-        ("zip-list", "Archive contents"),
-        ("extracted-summary", "Extraction summary"),
-        ("chmod", "Ensure scripts executable"),
-        ("cleanup", "Cleanup"),
-        ("git", "Initialize git repository"),
-        ("final", "Finalize")
-    ]:
-        tracker.add(key, label)
-
-    # Track git error message outside Live context so it persists
-    git_error_message = None
-
-    with Live(tracker.render(), console=console, refresh_per_second=8, transient=True) as live:
-        tracker.attach_refresh(lambda: live.update(tracker.render()))
-        try:
-            verify = not skip_tls
-            local_ssl_context = ssl_context if verify else False
-            local_client = httpx.Client(verify=local_ssl_context)
-
-            download_and_extract_template(project_path, selected_ai, selected_script, here, verbose=False, tracker=tracker, client=local_client, debug=debug, github_token=github_token)
-
-            ensure_executable_scripts(project_path, tracker=tracker)
-
-            if not no_git:
-                tracker.start("git")
-                if is_git_repo(project_path):
-                    tracker.complete("git", "existing repo detected")
-                elif should_init_git:
-                    success, error_msg = init_git_repo(project_path, quiet=True)
-                    if success:
-                        tracker.complete("git", "initialized")
-                    else:
-                        tracker.error("git", "init failed")
-                        git_error_message = error_msg
-                else:
-                    tracker.skip("git", "git not available")
-            else:
-                tracker.skip("git", "--no-git flag")
+    agent = opts.get("ai")
+    if not isinstance(agent, str) or not agent:
+        return None
 
-            tracker.complete("final", "project ready")
-        except Exception as e:
-            tracker.error("final", str(e))
-            console.print(Panel(f"Initialization failed: {e}", title="Failure", border_style="red"))
-            if debug:
-                _env_pairs = [
-                    ("Python", sys.version.split()[0]),
-                    ("Platform", sys.platform),
-                    ("CWD", str(Path.cwd())),
-                ]
-                _label_width = max(len(k) for k, _ in _env_pairs)
-                env_lines = [f"{k.ljust(_label_width)} → [bright_black]{v}[/bright_black]" for k, v in _env_pairs]
-                console.print(Panel("\n".join(env_lines), title="Debug Environment", border_style="magenta"))
-            if not here and project_path.exists():
-                shutil.rmtree(project_path)
-            raise typer.Exit(1)
-        finally:
-            pass
+    ai_skills_enabled = _is_ai_skills_enabled(opts)
+    if not ai_skills_enabled and agent != "kimi":
+        return None
 
-    console.print(tracker.render())
-    console.print("\n[bold green]Project ready.[/bold green]")
-    
-    # Show git error details if initialization failed
-    if git_error_message:
-        console.print()
-        git_error_panel = Panel(
-            f"[yellow]Warning:[/yellow] Git repository initialization failed\n\n"
-            f"{git_error_message}\n\n"
-            f"[dim]You can initialize git manually later with:[/dim]\n"
-            f"[cyan]cd {project_path if not here else '.'}[/cyan]\n"
-            f"[cyan]git init[/cyan]\n"
-            f"[cyan]git add .[/cyan]\n"
-            f"[cyan]git commit -m \"Initial commit\"[/cyan]",
-            title="[red]Git Initialization Failed[/red]",
-            border_style="red",
-            padding=(1, 2)
-        )
-        console.print(git_error_panel)
-
-    # Agent folder security notice
-    agent_config = AGENT_CONFIG.get(selected_ai)
-    if agent_config:
-        agent_folder = agent_config["folder"]
-        security_notice = Panel(
-            f"Some agents may store credentials, auth tokens, or other identifying and private artifacts in the agent folder within your project.\n"
-            f"Consider adding [cyan]{agent_folder}[/cyan] (or parts of it) to [cyan].gitignore[/cyan] to prevent accidental credential leakage.",
-            title="[yellow]Agent Folder Security[/yellow]",
-            border_style="yellow",
-            padding=(1, 2)
+    skills_dir = _get_skills_dir(project_root, agent)
+
+    if not ai_skills_enabled:
+        # Kimi native-skills fallback when ai_skills is not boolean True:
+        # use the native skills directory only if it already exists.
+        if not skills_dir.is_dir():
+            return None
+        _ensure_safe_shared_directory(
+            project_root, skills_dir,
+            create=False, context="agent skills directory",
         )
-        console.print()
-        console.print(security_notice)
+        return skills_dir
+
+    # ai_skills is boolean True: create the directory safely.
+    _ensure_safe_shared_directory(
+        project_root, skills_dir, context="agent skills directory",
+    )
+    return skills_dir
+
+
+def _cli_error_detail(exc: BaseException) -> str:
+    """Return a compact one-line exception detail for CLI output."""
+    detail = str(exc).replace("\n", " ").strip()
+    return detail or exc.__class__.__name__
+
+
+def _cli_phase_label(phase: str, target_kind: str, target: str | None = None) -> str:
+    """Format a stable operation label for user-visible diagnostics."""
+    label = f"{phase} {target_kind}".strip()
+    if target:
+        label = f"{label} '{target}'"
+    return label
+
+
+def _print_cli_warning(
+    phase: str,
+    target_kind: str,
+    target: str | None,
+    exc: BaseException,
+    *,
+    continuing: str | None = None,
+) -> None:
+    """Print a warning that names the failed CLI phase and target."""
+    label = _cli_phase_label(phase, target_kind, target)
+    console.print(f"[yellow]Warning:[/yellow] Failed to {label}: {_cli_error_detail(exc)}")
+    if continuing:
+        console.print(f"[dim]{continuing}[/dim]")
+
+
+# Constants kept for backward compatibility with presets and extensions.
+DEFAULT_SKILLS_DIR = ".agents/skills"
+SKILL_DESCRIPTIONS = {
+    "specify": "Create or update feature specifications from natural language descriptions.",
+    "plan": "Generate technical implementation plans from feature specifications.",
+    "tasks": "Break down implementation plans into actionable task lists.",
+    "implement": "Execute all tasks from the task breakdown to build the feature.",
+    "analyze": "Perform cross-artifact consistency analysis across spec.md, plan.md, and tasks.md.",
+    "clarify": "Structured clarification workflow for underspecified requirements.",
+    "constitution": "Create or update project governing principles and development guidelines.",
+    "checklist": "Generate custom quality checklists for validating requirements completeness and clarity.",
+    "taskstoissues": "Convert tasks from tasks.md into GitHub issues.",
+}
+
+
+# ===== init command =====
+# Moved to commands/init.py — registered here to preserve CLI surface.
+from .commands import init as _init_cmd  # noqa: E402
+_init_cmd.register(app)
 
-    steps_lines = []
-    if not here:
-        steps_lines.append(f"1. Go to the project folder: [cyan]cd {project_name}[/cyan]")
-        step_num = 2
-    else:
-        steps_lines.append("1. You're already in the project directory!")
-        step_num = 2
-
-    # Add Codex-specific setup step if needed
-    if selected_ai == "codex":
-        codex_path = project_path / ".codex"
-        quoted_path = shlex.quote(str(codex_path))
-        if os.name == "nt":  # Windows
-            cmd = f"setx CODEX_HOME {quoted_path}"
-        else:  # Unix-like systems
-            cmd = f"export CODEX_HOME={quoted_path}"
-        
-        steps_lines.append(f"{step_num}. Set [cyan]CODEX_HOME[/cyan] environment variable before running Codex: [cyan]{cmd}[/cyan]")
-        step_num += 1
-
-    steps_lines.append(f"{step_num}. Start using slash commands with your AI agent:")
-
-    steps_lines.append("   2.1 [cyan]/speckit.constitution[/] - Establish project principles")
-    steps_lines.append("   2.2 [cyan]/speckit.specify[/] - Create baseline specification")
-    steps_lines.append("   2.3 [cyan]/speckit.plan[/] - Create implementation plan")
-    steps_lines.append("   2.4 [cyan]/speckit.tasks[/] - Generate actionable tasks")
-    steps_lines.append("   2.5 [cyan]/speckit.implement[/] - Execute implementation")
-
-    steps_panel = Panel("\n".join(steps_lines), title="Next Steps", border_style="cyan", padding=(1,2))
-    console.print()
-    console.print(steps_panel)
-
-    enhancement_lines = [
-        "Optional commands that you can use for your specs [bright_black](improve quality & confidence)[/bright_black]",
-        "",
-        f"○ [cyan]/speckit.clarify[/] [bright_black](optional)[/bright_black] - Ask structured questions to de-risk ambiguous areas before planning (run before [cyan]/speckit.plan[/] if used)",
-        f"○ [cyan]/speckit.analyze[/] [bright_black](optional)[/bright_black] - Cross-artifact consistency & alignment report (after [cyan]/speckit.tasks[/], before [cyan]/speckit.implement[/])",
-        f"○ [cyan]/speckit.checklist[/] [bright_black](optional)[/bright_black] - Generate quality checklists to validate requirements completeness, clarity, and consistency (after [cyan]/speckit.plan[/])"
-    ]
-    enhancements_panel = Panel("\n".join(enhancement_lines), title="Enhancement Commands", border_style="cyan", padding=(1,2))
-    console.print()
-    console.print(enhancements_panel)
 
 @app.command()
 def check():
@@ -1241,6 +460,8 @@ def check():
 
     agent_results = {}
     for agent_key, agent_config in AGENT_CONFIG.items():
+        if agent_key == "generic":
+            continue  # Generic is not a real agent to check
         agent_name = agent_config["name"]
         requires_cli = agent_config["requires_cli"]
 
@@ -1255,10 +476,10 @@ def check():
 
     # Check VS Code variants (not in agent config)
     tracker.add("code", "Visual Studio Code")
-    code_ok = check_tool("code", tracker=tracker)
+    check_tool("code", tracker=tracker)
 
     tracker.add("code-insiders", "Visual Studio Code Insiders")
-    code_insiders_ok = check_tool("code-insiders", tracker=tracker)
+    check_tool("code-insiders", tracker=tracker)
 
     console.print(tracker.render())
 
@@ -1268,71 +489,68 @@ def check():
         console.print("[dim]Tip: Install git for repository management[/dim]")
 
     if not any(agent_results.values()):
-        console.print("[dim]Tip: Install an AI assistant for the best experience[/dim]")
+        console.print("[dim]Tip: Install a coding agent for the best experience[/dim]")
+
+    console.print("[dim]Tip: Run 'specify self check' to verify you have the latest CLI version[/dim]")
+
+
+def _feature_capabilities() -> dict[str, bool]:
+    """Return stable local CLI capability flags for humans and agents."""
+    return {
+        "controlled_multi_install_integrations": True,
+        "integration_use_command": True,
+        "multi_install_safe_registry_metadata": True,
+        "integration_upgrade_command": True,
+        "self_check_command": True,
+        "workflow_catalog": True,
+        "bundled_templates": True,
+    }
+
 
 @app.command()
-def version():
+def version(
+    features: bool = typer.Option(
+        False,
+        "--features",
+        help="Show local CLI feature capabilities.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit feature capabilities as JSON. Requires --features.",
+    ),
+):
     """Display version and system information."""
     import platform
-    import importlib.metadata
-    
+
+    cli_version = get_speckit_version()
+
+    if json_output and not features:
+        console.print("[red]Error:[/red] --json requires --features.")
+        raise typer.Exit(1)
+
+    if features:
+        capabilities = _feature_capabilities()
+        if json_output:
+            payload = {"version": cli_version, "features": capabilities}
+            console.print(json.dumps(payload, indent=2))
+            return
+
+        console.print(f"Spec Kit CLI: {cli_version}")
+        console.print()
+        console.print("Features:")
+        for key, enabled in capabilities.items():
+            label = key.replace("_", " ")
+            console.print(f"- {label}: {'yes' if enabled else 'no'}")
+        return
+
     show_banner()
-    
-    # Get CLI version from package metadata
-    cli_version = "unknown"
-    try:
-        cli_version = importlib.metadata.version("specify-cli")
-    except Exception:
-        # Fallback: try reading from pyproject.toml if running from source
-        try:
-            import tomllib
-            pyproject_path = Path(__file__).parent.parent.parent / "pyproject.toml"
-            if pyproject_path.exists():
-                with open(pyproject_path, "rb") as f:
-                    data = tomllib.load(f)
-                    cli_version = data.get("project", {}).get("version", "unknown")
-        except Exception:
-            pass
-    
-    # Fetch latest template release version
-    repo_owner = "github"
-    repo_name = "spec-kit"
-    api_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest"
-    
-    template_version = "unknown"
-    release_date = "unknown"
-    
-    try:
-        response = client.get(
-            api_url,
-            timeout=10,
-            follow_redirects=True,
-            headers=_github_auth_headers(),
-        )
-        if response.status_code == 200:
-            release_data = response.json()
-            template_version = release_data.get("tag_name", "unknown")
-            # Remove 'v' prefix if present
-            if template_version.startswith("v"):
-                template_version = template_version[1:]
-            release_date = release_data.get("published_at", "unknown")
-            if release_date != "unknown":
-                # Format the date nicely
-                try:
-                    dt = datetime.fromisoformat(release_date.replace('Z', '+00:00'))
-                    release_date = dt.strftime("%Y-%m-%d")
-                except Exception:
-                    pass
-    except Exception:
-        pass
 
     info_table = Table(show_header=False, box=None, padding=(0, 2))
     info_table.add_column("Key", style="cyan", justify="right")
     info_table.add_column("Value", style="white")
 
     info_table.add_row("CLI Version", cli_version)
-    info_table.add_row("Template Version", template_version)
-    info_table.add_row("Released", release_date)
     info_table.add_row("", "")
     info_table.add_row("Python", platform.python_version())
     info_table.add_row("Platform", platform.system())
@@ -1349,9 +567,2875 @@ def version():
     console.print(panel)
     console.print()
 
-def main():
-    app()
+app.add_typer(_self_app, name="self")
 
-if __name__ == "__main__":
-    main()
 
+# ===== Extension Commands =====
+
+extension_app = typer.Typer(
+    name="extension",
+    help="Manage spec-kit extensions",
+    add_completion=False,
+)
+app.add_typer(extension_app, name="extension")
+
+catalog_app = typer.Typer(
+    name="catalog",
+    help="Manage extension catalogs",
+    add_completion=False,
+)
+extension_app.add_typer(catalog_app, name="catalog")
+
+preset_app = typer.Typer(
+    name="preset",
+    help="Manage spec-kit presets",
+    add_completion=False,
+)
+app.add_typer(preset_app, name="preset")
+
+preset_catalog_app = typer.Typer(
+    name="catalog",
+    help="Manage preset catalogs",
+    add_completion=False,
+)
+preset_app.add_typer(preset_catalog_app, name="catalog")
+
+
+# ===== Integration Commands =====
+
+# Moved to integrations/_commands.py — registered here to preserve CLI surface.
+from .integrations._commands import register as _register_integration_cmds  # noqa: E402
+_register_integration_cmds(app)
+
+# Re-exported from integrations/_helpers.py to preserve the public import surface.
+from .integrations._helpers import (  # noqa: E402
+    _clear_init_options_for_integration as _clear_init_options_for_integration,
+    _update_init_options_for_integration as _update_init_options_for_integration,
+)
+
+
+def _require_specify_project() -> Path:
+    """Return the current project root if it is a spec-kit project, else exit."""
+    project_root = Path.cwd()
+    if (project_root / ".specify").is_dir():
+        return project_root
+    console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+    console.print("Run this command from a spec-kit project root")
+    raise typer.Exit(1)
+
+
+
+# ===== Preset Commands =====
+
+
+@preset_app.command("list")
+def preset_list():
+    """List installed presets."""
+    from .presets import PresetManager
+
+    project_root = _require_specify_project()
+    manager = PresetManager(project_root)
+    installed = manager.list_installed()
+
+    if not installed:
+        console.print("[yellow]No presets installed.[/yellow]")
+        console.print("\nInstall a preset with:")
+        console.print("  [cyan]specify preset add <pack-name>[/cyan]")
+        return
+
+    console.print("\n[bold cyan]Installed Presets:[/bold cyan]\n")
+    for pack in installed:
+        status = "[green]enabled[/green]" if pack.get("enabled", True) else "[red]disabled[/red]"
+        pri = pack.get('priority', 10)
+        console.print(f"  [bold]{pack['name']}[/bold] ({pack['id']}) v{pack['version']} — {status} — priority {pri}")
+        console.print(f"    {pack['description']}")
+        if pack.get("tags"):
+            tags_str = ", ".join(pack["tags"])
+            console.print(f"    [dim]Tags: {tags_str}[/dim]")
+        console.print(f"    [dim]Templates: {pack['template_count']}[/dim]")
+        console.print()
+
+
+@preset_app.command("add")
+def preset_add(
+    preset_id: str = typer.Argument(None, help="Preset ID to install from catalog"),
+    from_url: str = typer.Option(None, "--from", help="Install from a URL (ZIP file)"),
+    dev: str = typer.Option(None, "--dev", help="Install from local directory (development mode)"),
+    priority: int = typer.Option(10, "--priority", help="Resolution priority (lower = higher precedence, default 10)"),
+):
+    """Install a preset."""
+    from .presets import (
+        PresetManager,
+        PresetCatalog,
+        PresetError,
+        PresetValidationError,
+        PresetCompatibilityError,
+    )
+
+    project_root = _require_specify_project()
+    # Validate priority
+    if priority < 1:
+        console.print("[red]Error:[/red] Priority must be a positive integer (1 or higher)")
+        raise typer.Exit(1)
+
+    manager = PresetManager(project_root)
+    speckit_version = get_speckit_version()
+
+    try:
+        if dev:
+            dev_path = Path(dev).resolve()
+            if not dev_path.exists():
+                console.print(f"[red]Error:[/red] Directory not found: {dev}")
+                raise typer.Exit(1)
+
+            console.print(f"Installing preset from [cyan]{dev_path}[/cyan]...")
+            manifest = manager.install_from_directory(dev_path, speckit_version, priority)
+            console.print(f"[green]✓[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+
+        elif from_url:
+            # Validate URL scheme before downloading
+            from urllib.parse import urlparse as _urlparse
+            _parsed = _urlparse(from_url)
+            _is_localhost = _parsed.hostname in ("localhost", "127.0.0.1", "::1")
+            if _parsed.scheme != "https" and not (_parsed.scheme == "http" and _is_localhost):
+                console.print(f"[red]Error:[/red] URL must use HTTPS (got {_parsed.scheme}://). HTTP is only allowed for localhost.")
+                raise typer.Exit(1)
+
+            console.print(f"Installing preset from [cyan]{from_url}[/cyan]...")
+            import urllib.request
+            import urllib.error
+            import tempfile
+
+            with tempfile.TemporaryDirectory() as tmpdir:
+                zip_path = Path(tmpdir) / "preset.zip"
+                try:
+                    from specify_cli.authentication.http import open_url as _open_url
+
+                    with _open_url(from_url, timeout=60) as response:
+                        zip_path.write_bytes(response.read())
+                except urllib.error.URLError as e:
+                    console.print(f"[red]Error:[/red] Failed to download: {e}")
+                    raise typer.Exit(1)
+
+                manifest = manager.install_from_zip(zip_path, speckit_version, priority)
+
+            console.print(f"[green]✓[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+
+        elif preset_id:
+            # Try bundled preset first, then catalog
+            bundled_path = _locate_bundled_preset(preset_id)
+            if bundled_path:
+                console.print(f"Installing bundled preset [cyan]{preset_id}[/cyan]...")
+                manifest = manager.install_from_directory(bundled_path, speckit_version, priority)
+                console.print(f"[green]✓[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+            else:
+                catalog = PresetCatalog(project_root)
+                pack_info = catalog.get_pack_info(preset_id)
+
+                if not pack_info:
+                    console.print(f"[red]Error:[/red] Preset '{preset_id}' not found in catalog")
+                    raise typer.Exit(1)
+
+                # Bundled presets should have been caught above; if we reach
+                # here the bundled files are missing from the installation.
+                if pack_info.get("bundled") and not pack_info.get("download_url"):
+                    from .extensions import REINSTALL_COMMAND
+                    console.print(
+                        f"[red]Error:[/red] Preset '{preset_id}' is bundled with spec-kit "
+                        f"but could not be found in the installed package."
+                    )
+                    console.print(
+                        "\nThis usually means the spec-kit installation is incomplete or corrupted."
+                    )
+                    console.print("Try reinstalling spec-kit:")
+                    console.print(f"  {REINSTALL_COMMAND}")
+                    raise typer.Exit(1)
+
+                if not pack_info.get("_install_allowed", True):
+                    catalog_name = pack_info.get("_catalog_name", "unknown")
+                    console.print(f"[red]Error:[/red] Preset '{preset_id}' is from the '{catalog_name}' catalog which is discovery-only (install not allowed).")
+                    console.print("Add the catalog with --install-allowed or install from the preset's repository directly with --from.")
+                    raise typer.Exit(1)
+
+                console.print(f"Installing preset [cyan]{pack_info.get('name', preset_id)}[/cyan]...")
+
+                try:
+                    zip_path = catalog.download_pack(preset_id)
+                    manifest = manager.install_from_zip(zip_path, speckit_version, priority)
+                    console.print(f"[green]✓[/green] Preset '{manifest.name}' v{manifest.version} installed (priority {priority})")
+                finally:
+                    if 'zip_path' in locals() and zip_path.exists():
+                        zip_path.unlink(missing_ok=True)
+        else:
+            console.print("[red]Error:[/red] Specify a preset ID, --from URL, or --dev path")
+            raise typer.Exit(1)
+
+    except PresetCompatibilityError as e:
+        console.print(f"[red]Compatibility Error:[/red] {e}")
+        raise typer.Exit(1)
+    except PresetValidationError as e:
+        console.print(f"[red]Validation Error:[/red] {e}")
+        raise typer.Exit(1)
+    except PresetError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@preset_app.command("remove")
+def preset_remove(
+    preset_id: str = typer.Argument(..., help="Preset ID to remove"),
+):
+    """Remove an installed preset."""
+    from .presets import PresetManager
+
+    project_root = _require_specify_project()
+    manager = PresetManager(project_root)
+
+    if not manager.registry.is_installed(preset_id):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed")
+        raise typer.Exit(1)
+
+    if manager.remove(preset_id):
+        console.print(f"[green]✓[/green] Preset '{preset_id}' removed successfully")
+    else:
+        console.print(f"[red]Error:[/red] Failed to remove preset '{preset_id}'")
+        raise typer.Exit(1)
+
+
+@preset_app.command("search")
+def preset_search(
+    query: str = typer.Argument(None, help="Search query"),
+    tag: str = typer.Option(None, "--tag", help="Filter by tag"),
+    author: str = typer.Option(None, "--author", help="Filter by author"),
+):
+    """Search for presets in the catalog."""
+    from .presets import PresetCatalog, PresetError
+
+    project_root = _require_specify_project()
+    catalog = PresetCatalog(project_root)
+
+    try:
+        results = catalog.search(query=query, tag=tag, author=author)
+    except PresetError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not results:
+        console.print("[yellow]No presets found matching your criteria.[/yellow]")
+        return
+
+    console.print(f"\n[bold cyan]Presets ({len(results)} found):[/bold cyan]\n")
+    for pack in results:
+        console.print(f"  [bold]{pack.get('name', pack['id'])}[/bold] ({pack['id']}) v{pack.get('version', '?')}")
+        console.print(f"    {pack.get('description', '')}")
+        if pack.get("tags"):
+            tags_str = ", ".join(pack["tags"])
+            console.print(f"    [dim]Tags: {tags_str}[/dim]")
+        console.print()
+
+
+@preset_app.command("resolve")
+def preset_resolve(
+    template_name: str = typer.Argument(..., help="Template name to resolve (e.g., spec-template)"),
+):
+    """Show which template will be resolved for a given name."""
+    from .presets import PresetResolver
+
+    project_root = _require_specify_project()
+    resolver = PresetResolver(project_root)
+    layers = resolver.collect_all_layers(template_name)
+
+    if layers:
+        # Use the highest-priority layer for display because the final output
+        # may be composed and may not map to resolve_with_source()'s single path.
+        display_layer = layers[0]
+        console.print(f"  [bold]{template_name}[/bold]: {display_layer['path']}")
+        console.print(f"    [dim](top layer from: {display_layer['source']})[/dim]")
+
+        has_composition = (
+            layers[0]["strategy"] != "replace"
+            and any(layer["strategy"] != "replace" for layer in layers)
+        )
+        if has_composition:
+            # Verify composition is actually possible
+            try:
+                composed = resolver.resolve_content(template_name)
+            except Exception as exc:
+                composed = None
+                console.print(f"    [yellow]Warning: composition error: {exc}[/yellow]")
+            if composed is None:
+                console.print("    [yellow]Warning: composition cannot produce output (no base layer with 'replace' strategy)[/yellow]")
+            else:
+                console.print("    [dim]Final output is composed from multiple preset layers; the path above is the highest-priority contributing layer.[/dim]")
+            console.print("\n  [bold]Composition chain:[/bold]")
+            # Compute the effective base: first replace layer scanning from
+            # highest priority (matching resolve_content top-down logic).
+            # Only show layers from the base upward (lower layers are ignored).
+            effective_base_idx = None
+            for idx, lyr in enumerate(layers):
+                if lyr["strategy"] == "replace":
+                    effective_base_idx = idx
+                    break
+            # Show only contributing layers (base and above)
+            if effective_base_idx is not None:
+                contributing = layers[:effective_base_idx + 1]
+            else:
+                contributing = layers
+            for i, layer in enumerate(reversed(contributing)):
+                strategy_label = layer["strategy"]
+                if strategy_label == "replace" and i == 0:
+                    strategy_label = "base"
+                console.print(f"    {i + 1}. [{strategy_label}] {layer['source']} → {layer['path']}")
+    else:
+        # No layers found — fall back to resolve_with_source for non-composition cases
+        result = resolver.resolve_with_source(template_name)
+        if result:
+            console.print(f"  [bold]{template_name}[/bold]: {result['path']}")
+            console.print(f"    [dim](from: {result['source']})[/dim]")
+        else:
+            console.print(f"  [yellow]{template_name}[/yellow]: not found")
+            console.print("    [dim]No template with this name exists in the resolution stack[/dim]")
+
+
+@preset_app.command("info")
+def preset_info(
+    preset_id: str = typer.Argument(..., help="Preset ID to get info about"),
+):
+    """Show detailed information about a preset."""
+    from .extensions import normalize_priority
+    from .presets import PresetCatalog, PresetManager, PresetError
+
+    project_root = _require_specify_project()
+    # Check if installed locally first
+    manager = PresetManager(project_root)
+    local_pack = manager.get_pack(preset_id)
+
+    if local_pack:
+        console.print(f"\n[bold cyan]Preset: {local_pack.name}[/bold cyan]\n")
+        console.print(f"  ID:          {local_pack.id}")
+        console.print(f"  Version:     {local_pack.version}")
+        console.print(f"  Description: {local_pack.description}")
+        if local_pack.author:
+            console.print(f"  Author:      {local_pack.author}")
+        if local_pack.tags:
+            console.print(f"  Tags:        {', '.join(local_pack.tags)}")
+        console.print(f"  Templates:   {len(local_pack.templates)}")
+        for tmpl in local_pack.templates:
+            console.print(f"    - {tmpl['name']} ({tmpl['type']}): {tmpl.get('description', '')}")
+        repo = local_pack.data.get("preset", {}).get("repository")
+        if repo:
+            console.print(f"  Repository:  {repo}")
+        license_val = local_pack.data.get("preset", {}).get("license")
+        if license_val:
+            console.print(f"  License:     {license_val}")
+        console.print("\n  [green]Status: installed[/green]")
+        # Get priority from registry
+        pack_metadata = manager.registry.get(preset_id)
+        priority = normalize_priority(pack_metadata.get("priority") if isinstance(pack_metadata, dict) else None)
+        console.print(f"  [dim]Priority:[/dim] {priority}")
+        console.print()
+        return
+
+    # Fall back to catalog
+    catalog = PresetCatalog(project_root)
+    try:
+        pack_info = catalog.get_pack_info(preset_id)
+    except PresetError:
+        pack_info = None
+
+    if not pack_info:
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' not found (not installed and not in catalog)")
+        raise typer.Exit(1)
+
+    console.print(f"\n[bold cyan]Preset: {pack_info.get('name', preset_id)}[/bold cyan]\n")
+    console.print(f"  ID:          {pack_info['id']}")
+    console.print(f"  Version:     {pack_info.get('version', '?')}")
+    console.print(f"  Description: {pack_info.get('description', '')}")
+    if pack_info.get("author"):
+        console.print(f"  Author:      {pack_info['author']}")
+    if pack_info.get("tags"):
+        console.print(f"  Tags:        {', '.join(pack_info['tags'])}")
+    if pack_info.get("repository"):
+        console.print(f"  Repository:  {pack_info['repository']}")
+    if pack_info.get("license"):
+        console.print(f"  License:     {pack_info['license']}")
+    console.print("\n  [yellow]Status: not installed[/yellow]")
+    console.print(f"  Install with: [cyan]specify preset add {preset_id}[/cyan]")
+    console.print()
+
+
+@preset_app.command("set-priority")
+def preset_set_priority(
+    preset_id: str = typer.Argument(help="Preset ID"),
+    priority: int = typer.Argument(help="New priority (lower = higher precedence)"),
+):
+    """Set the resolution priority of an installed preset."""
+    from .presets import PresetManager
+
+    project_root = _require_specify_project()
+    # Validate priority
+    if priority < 1:
+        console.print("[red]Error:[/red] Priority must be a positive integer (1 or higher)")
+        raise typer.Exit(1)
+
+    manager = PresetManager(project_root)
+
+    # Check if preset is installed
+    if not manager.registry.is_installed(preset_id):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed")
+        raise typer.Exit(1)
+
+    # Get current metadata
+    metadata = manager.registry.get(preset_id)
+    if metadata is None or not isinstance(metadata, dict):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' not found in registry (corrupted state)")
+        raise typer.Exit(1)
+
+    from .extensions import normalize_priority
+    raw_priority = metadata.get("priority")
+    # Only skip if the stored value is already a valid int equal to requested priority
+    # This ensures corrupted values (e.g., "high") get repaired even when setting to default (10)
+    if isinstance(raw_priority, int) and raw_priority == priority:
+        console.print(f"[yellow]Preset '{preset_id}' already has priority {priority}[/yellow]")
+        raise typer.Exit(0)
+
+    old_priority = normalize_priority(raw_priority)
+
+    # Update priority
+    manager.registry.update(preset_id, {"priority": priority})
+
+    console.print(f"[green]✓[/green] Preset '{preset_id}' priority changed: {old_priority} → {priority}")
+    console.print("\n[dim]Lower priority = higher precedence in template resolution[/dim]")
+
+
+@preset_app.command("enable")
+def preset_enable(
+    preset_id: str = typer.Argument(help="Preset ID to enable"),
+):
+    """Enable a disabled preset."""
+    from .presets import PresetManager
+
+    project_root = _require_specify_project()
+    manager = PresetManager(project_root)
+
+    # Check if preset is installed
+    if not manager.registry.is_installed(preset_id):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed")
+        raise typer.Exit(1)
+
+    # Get current metadata
+    metadata = manager.registry.get(preset_id)
+    if metadata is None or not isinstance(metadata, dict):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' not found in registry (corrupted state)")
+        raise typer.Exit(1)
+
+    if metadata.get("enabled", True):
+        console.print(f"[yellow]Preset '{preset_id}' is already enabled[/yellow]")
+        raise typer.Exit(0)
+
+    # Enable the preset
+    manager.registry.update(preset_id, {"enabled": True})
+
+    console.print(f"[green]✓[/green] Preset '{preset_id}' enabled")
+    console.print("\nTemplates from this preset will now be included in resolution.")
+    console.print("[dim]Note: Previously registered commands/skills remain active.[/dim]")
+
+
+@preset_app.command("disable")
+def preset_disable(
+    preset_id: str = typer.Argument(help="Preset ID to disable"),
+):
+    """Disable a preset without removing it."""
+    from .presets import PresetManager
+
+    project_root = _require_specify_project()
+    manager = PresetManager(project_root)
+
+    # Check if preset is installed
+    if not manager.registry.is_installed(preset_id):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed")
+        raise typer.Exit(1)
+
+    # Get current metadata
+    metadata = manager.registry.get(preset_id)
+    if metadata is None or not isinstance(metadata, dict):
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' not found in registry (corrupted state)")
+        raise typer.Exit(1)
+
+    if not metadata.get("enabled", True):
+        console.print(f"[yellow]Preset '{preset_id}' is already disabled[/yellow]")
+        raise typer.Exit(0)
+
+    # Disable the preset
+    manager.registry.update(preset_id, {"enabled": False})
+
+    console.print(f"[green]✓[/green] Preset '{preset_id}' disabled")
+    console.print("\nTemplates from this preset will be skipped during resolution.")
+    console.print("[dim]Note: Previously registered commands/skills remain active until preset removal.[/dim]")
+    console.print(f"To re-enable: specify preset enable {preset_id}")
+
+
+# ===== Preset Catalog Commands =====
+
+
+@preset_catalog_app.command("list")
+def preset_catalog_list():
+    """List all active preset catalogs."""
+    from .presets import PresetCatalog, PresetValidationError
+
+    project_root = _require_specify_project()
+    catalog = PresetCatalog(project_root)
+
+    try:
+        active_catalogs = catalog.get_active_catalogs()
+    except PresetValidationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    console.print("\n[bold cyan]Active Preset Catalogs:[/bold cyan]\n")
+    for entry in active_catalogs:
+        install_str = (
+            "[green]install allowed[/green]"
+            if entry.install_allowed
+            else "[yellow]discovery only[/yellow]"
+        )
+        console.print(f"  [bold]{entry.name}[/bold] (priority {entry.priority})")
+        if entry.description:
+            console.print(f"     {entry.description}")
+        console.print(f"     URL: {entry.url}")
+        console.print(f"     Install: {install_str}")
+        console.print()
+
+    config_path = project_root / ".specify" / "preset-catalogs.yml"
+    user_config_path = Path.home() / ".specify" / "preset-catalogs.yml"
+    if os.environ.get("SPECKIT_PRESET_CATALOG_URL"):
+        console.print("[dim]Catalog configured via SPECKIT_PRESET_CATALOG_URL environment variable.[/dim]")
+    else:
+        try:
+            proj_loaded = config_path.exists() and catalog._load_catalog_config(config_path) is not None
+        except PresetValidationError:
+            proj_loaded = False
+        if proj_loaded:
+            console.print(f"[dim]Config: {_display_project_path(project_root, config_path)}[/dim]")
+        else:
+            try:
+                user_loaded = user_config_path.exists() and catalog._load_catalog_config(user_config_path) is not None
+            except PresetValidationError:
+                user_loaded = False
+            if user_loaded:
+                console.print("[dim]Config: ~/.specify/preset-catalogs.yml[/dim]")
+            else:
+                console.print("[dim]Using built-in default catalog stack.[/dim]")
+                console.print(
+                    "[dim]Add .specify/preset-catalogs.yml to customize.[/dim]"
+                )
+
+
+@preset_catalog_app.command("add")
+def preset_catalog_add(
+    url: str = typer.Argument(help="Catalog URL (must use HTTPS)"),
+    name: str = typer.Option(..., "--name", help="Catalog name"),
+    priority: int = typer.Option(10, "--priority", help="Priority (lower = higher priority)"),
+    install_allowed: bool = typer.Option(
+        False, "--install-allowed/--no-install-allowed",
+        help="Allow presets from this catalog to be installed",
+    ),
+    description: str = typer.Option("", "--description", help="Description of the catalog"),
+):
+    """Add a catalog to .specify/preset-catalogs.yml."""
+    from .presets import PresetCatalog, PresetValidationError
+
+    project_root = _require_specify_project()
+    specify_dir = project_root / ".specify"
+
+    # Validate URL
+    tmp_catalog = PresetCatalog(project_root)
+    try:
+        tmp_catalog._validate_catalog_url(url)
+    except PresetValidationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    config_path = specify_dir / "preset-catalogs.yml"
+
+    # Load existing config
+    if config_path.exists():
+        try:
+            config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except Exception as e:
+            config_label = _display_project_path(project_root, config_path)
+            console.print(f"[red]Error:[/red] Failed to read {config_label}: {e}")
+            raise typer.Exit(1)
+    else:
+        config = {}
+
+    catalogs = config.get("catalogs", [])
+    if not isinstance(catalogs, list):
+        console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+        raise typer.Exit(1)
+
+    # Check for duplicate name
+    for existing in catalogs:
+        if isinstance(existing, dict) and existing.get("name") == name:
+            console.print(f"[yellow]Warning:[/yellow] A catalog named '{name}' already exists.")
+            console.print("Use 'specify preset catalog remove' first, or choose a different name.")
+            raise typer.Exit(1)
+
+    catalogs.append({
+        "name": name,
+        "url": url,
+        "priority": priority,
+        "install_allowed": install_allowed,
+        "description": description,
+    })
+
+    config["catalogs"] = catalogs
+    config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False, allow_unicode=True), encoding="utf-8")
+
+    install_label = "install allowed" if install_allowed else "discovery only"
+    console.print(f"\n[green]✓[/green] Added catalog '[bold]{name}[/bold]' ({install_label})")
+    console.print(f"  URL: {url}")
+    console.print(f"  Priority: {priority}")
+    console.print(f"\nConfig saved to {_display_project_path(project_root, config_path)}")
+
+
+@preset_catalog_app.command("remove")
+def preset_catalog_remove(
+    name: str = typer.Argument(help="Catalog name to remove"),
+):
+    """Remove a catalog from .specify/preset-catalogs.yml."""
+    project_root = _require_specify_project()
+    specify_dir = project_root / ".specify"
+
+    config_path = specify_dir / "preset-catalogs.yml"
+    if not config_path.exists():
+        console.print("[red]Error:[/red] No preset catalog config found. Nothing to remove.")
+        raise typer.Exit(1)
+
+    try:
+        config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except Exception:
+        console.print("[red]Error:[/red] Failed to read preset catalog config.")
+        raise typer.Exit(1)
+
+    catalogs = config.get("catalogs", [])
+    if not isinstance(catalogs, list):
+        console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+        raise typer.Exit(1)
+    original_count = len(catalogs)
+    catalogs = [c for c in catalogs if isinstance(c, dict) and c.get("name") != name]
+
+    if len(catalogs) == original_count:
+        console.print(f"[red]Error:[/red] Catalog '{name}' not found.")
+        raise typer.Exit(1)
+
+    config["catalogs"] = catalogs
+    config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False, allow_unicode=True), encoding="utf-8")
+
+    console.print(f"[green]✓[/green] Removed catalog '{name}'")
+    if not catalogs:
+        console.print("\n[dim]No catalogs remain in config. Built-in defaults will be used.[/dim]")
+
+
+# ===== Extension Commands =====
+
+
+def _resolve_installed_extension(
+    argument: str,
+    installed_extensions: list,
+    command_name: str = "command",
+    allow_not_found: bool = False,
+) -> tuple[Optional[str], Optional[str]]:
+    """Resolve an extension argument (ID or display name) to an installed extension.
+
+    Args:
+        argument: Extension ID or display name provided by user
+        installed_extensions: List of installed extension dicts from manager.list_installed()
+        command_name: Name of the command for error messages (e.g., "enable", "disable")
+        allow_not_found: If True, return (None, None) when not found instead of raising
+
+    Returns:
+        Tuple of (extension_id, display_name), or (None, None) if allow_not_found=True and not found
+
+    Raises:
+        typer.Exit: If extension not found (and allow_not_found=False) or name is ambiguous
+    """
+    from rich.table import Table
+
+    # First, try exact ID match
+    for ext in installed_extensions:
+        if ext["id"] == argument:
+            return (ext["id"], ext["name"])
+
+    # If not found by ID, try display name match
+    name_matches = [ext for ext in installed_extensions if ext["name"].lower() == argument.lower()]
+
+    if len(name_matches) == 1:
+        # Unique display-name match
+        return (name_matches[0]["id"], name_matches[0]["name"])
+    elif len(name_matches) > 1:
+        # Ambiguous display-name match
+        console.print(
+            f"[red]Error:[/red] Extension name '{argument}' is ambiguous. "
+            "Multiple installed extensions share this name:"
+        )
+        table = Table(title="Matching extensions")
+        table.add_column("ID", style="cyan", no_wrap=True)
+        table.add_column("Name", style="white")
+        table.add_column("Version", style="green")
+        for ext in name_matches:
+            table.add_row(ext.get("id", ""), ext.get("name", ""), str(ext.get("version", "")))
+        console.print(table)
+        console.print("\nPlease rerun using the extension ID:")
+        console.print(f"  [bold]specify extension {command_name} <extension-id>[/bold]")
+        raise typer.Exit(1)
+    else:
+        # No match by ID or display name
+        if allow_not_found:
+            return (None, None)
+        console.print(f"[red]Error:[/red] Extension '{argument}' is not installed")
+        raise typer.Exit(1)
+
+
+def _resolve_catalog_extension(
+    argument: str,
+    catalog,
+    command_name: str = "info",
+) -> tuple[Optional[dict], Optional[Exception]]:
+    """Resolve an extension argument (ID or display name) from the catalog.
+
+    Args:
+        argument: Extension ID or display name provided by user
+        catalog: ExtensionCatalog instance
+        command_name: Name of the command for error messages
+
+    Returns:
+        Tuple of (extension_info, catalog_error)
+        - If found: (ext_info_dict, None)
+        - If catalog error: (None, error)
+        - If not found: (None, None)
+    """
+    from rich.table import Table
+    from .extensions import ExtensionError
+
+    try:
+        # First try by ID
+        ext_info = catalog.get_extension_info(argument)
+        if ext_info:
+            return (ext_info, None)
+
+        # Try by display name - search using argument as query, then filter for exact match
+        search_results = catalog.search(query=argument)
+        name_matches = [ext for ext in search_results if ext["name"].lower() == argument.lower()]
+
+        if len(name_matches) == 1:
+            return (name_matches[0], None)
+        elif len(name_matches) > 1:
+            # Ambiguous display-name match in catalog
+            console.print(
+                f"[red]Error:[/red] Extension name '{argument}' is ambiguous. "
+                "Multiple catalog extensions share this name:"
+            )
+            table = Table(title="Matching extensions")
+            table.add_column("ID", style="cyan", no_wrap=True)
+            table.add_column("Name", style="white")
+            table.add_column("Version", style="green")
+            table.add_column("Catalog", style="dim")
+            for ext in name_matches:
+                table.add_row(
+                    ext.get("id", ""),
+                    ext.get("name", ""),
+                    str(ext.get("version", "")),
+                    ext.get("_catalog_name", ""),
+                )
+            console.print(table)
+            console.print("\nPlease rerun using the extension ID:")
+            console.print(f"  [bold]specify extension {command_name} <extension-id>[/bold]")
+            raise typer.Exit(1)
+
+        # Not found
+        return (None, None)
+
+    except ExtensionError as e:
+        return (None, e)
+
+
+@extension_app.command("list")
+def extension_list(
+    available: bool = typer.Option(False, "--available", help="Show available extensions from catalog"),
+    all_extensions: bool = typer.Option(False, "--all", help="Show both installed and available"),
+):
+    """List installed extensions."""
+    from .extensions import ExtensionManager
+
+    project_root = _require_specify_project()
+    manager = ExtensionManager(project_root)
+    installed = manager.list_installed()
+
+    if not installed and not (available or all_extensions):
+        console.print("[yellow]No extensions installed.[/yellow]")
+        console.print("\nInstall an extension with:")
+        console.print("  specify extension add <extension-name>")
+        return
+
+    if installed:
+        console.print("\n[bold cyan]Installed Extensions:[/bold cyan]\n")
+
+        for ext in installed:
+            status_icon = "✓" if ext["enabled"] else "✗"
+            status_color = "green" if ext["enabled"] else "red"
+
+            console.print(f"  [{status_color}]{status_icon}[/{status_color}] [bold]{ext['name']}[/bold] (v{ext['version']})")
+            console.print(f"     [dim]{ext['id']}[/dim]")
+            console.print(f"     {ext['description']}")
+            console.print(f"     Commands: {ext['command_count']} | Hooks: {ext['hook_count']} | Priority: {ext['priority']} | Status: {'Enabled' if ext['enabled'] else 'Disabled'}")
+            console.print()
+
+    if available or all_extensions:
+        console.print("\nInstall an extension:")
+        console.print("  [cyan]specify extension add <name>[/cyan]")
+
+
+@catalog_app.command("list")
+def catalog_list():
+    """List all active extension catalogs."""
+    from .extensions import ExtensionCatalog, ValidationError
+
+    project_root = _require_specify_project()
+    catalog = ExtensionCatalog(project_root)
+
+    try:
+        active_catalogs = catalog.get_active_catalogs()
+    except ValidationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    console.print("\n[bold cyan]Active Extension Catalogs:[/bold cyan]\n")
+    for entry in active_catalogs:
+        install_str = (
+            "[green]install allowed[/green]"
+            if entry.install_allowed
+            else "[yellow]discovery only[/yellow]"
+        )
+        console.print(f"  [bold]{entry.name}[/bold] (priority {entry.priority})")
+        if entry.description:
+            console.print(f"     {entry.description}")
+        console.print(f"     URL: {entry.url}")
+        console.print(f"     Install: {install_str}")
+        console.print()
+
+    config_path = project_root / ".specify" / "extension-catalogs.yml"
+    user_config_path = Path.home() / ".specify" / "extension-catalogs.yml"
+    if os.environ.get("SPECKIT_CATALOG_URL"):
+        console.print("[dim]Catalog configured via SPECKIT_CATALOG_URL environment variable.[/dim]")
+    else:
+        try:
+            proj_loaded = config_path.exists() and catalog._load_catalog_config(config_path) is not None
+        except ValidationError:
+            proj_loaded = False
+        if proj_loaded:
+            console.print(f"[dim]Config: {_display_project_path(project_root, config_path)}[/dim]")
+        else:
+            try:
+                user_loaded = user_config_path.exists() and catalog._load_catalog_config(user_config_path) is not None
+            except ValidationError:
+                user_loaded = False
+            if user_loaded:
+                console.print("[dim]Config: ~/.specify/extension-catalogs.yml[/dim]")
+            else:
+                console.print("[dim]Using built-in default catalog stack.[/dim]")
+                console.print(
+                    "[dim]Add .specify/extension-catalogs.yml to customize.[/dim]"
+                )
+
+
+@catalog_app.command("add")
+def catalog_add(
+    url: str = typer.Argument(help="Catalog URL (must use HTTPS)"),
+    name: str = typer.Option(..., "--name", help="Catalog name"),
+    priority: int = typer.Option(10, "--priority", help="Priority (lower = higher priority)"),
+    install_allowed: bool = typer.Option(
+        False, "--install-allowed/--no-install-allowed",
+        help="Allow extensions from this catalog to be installed",
+    ),
+    description: str = typer.Option("", "--description", help="Description of the catalog"),
+):
+    """Add a catalog to .specify/extension-catalogs.yml."""
+    from .extensions import ExtensionCatalog, ValidationError
+
+    project_root = _require_specify_project()
+    specify_dir = project_root / ".specify"
+
+    # Validate URL
+    tmp_catalog = ExtensionCatalog(project_root)
+    try:
+        tmp_catalog._validate_catalog_url(url)
+    except ValidationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    config_path = specify_dir / "extension-catalogs.yml"
+
+    # Load existing config
+    if config_path.exists():
+        try:
+            config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except Exception as e:
+            config_label = _display_project_path(project_root, config_path)
+            console.print(f"[red]Error:[/red] Failed to read {config_label}: {e}")
+            raise typer.Exit(1)
+    else:
+        config = {}
+
+    catalogs = config.get("catalogs", [])
+    if not isinstance(catalogs, list):
+        console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+        raise typer.Exit(1)
+
+    # Check for duplicate name
+    for existing in catalogs:
+        if isinstance(existing, dict) and existing.get("name") == name:
+            console.print(f"[yellow]Warning:[/yellow] A catalog named '{name}' already exists.")
+            console.print("Use 'specify extension catalog remove' first, or choose a different name.")
+            raise typer.Exit(1)
+
+    catalogs.append({
+        "name": name,
+        "url": url,
+        "priority": priority,
+        "install_allowed": install_allowed,
+        "description": description,
+    })
+
+    config["catalogs"] = catalogs
+    config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False, allow_unicode=True), encoding="utf-8")
+
+    install_label = "install allowed" if install_allowed else "discovery only"
+    console.print(f"\n[green]✓[/green] Added catalog '[bold]{name}[/bold]' ({install_label})")
+    console.print(f"  URL: {url}")
+    console.print(f"  Priority: {priority}")
+    console.print(f"\nConfig saved to {_display_project_path(project_root, config_path)}")
+
+
+@catalog_app.command("remove")
+def catalog_remove(
+    name: str = typer.Argument(help="Catalog name to remove"),
+):
+    """Remove a catalog from .specify/extension-catalogs.yml."""
+    project_root = _require_specify_project()
+    specify_dir = project_root / ".specify"
+
+    config_path = specify_dir / "extension-catalogs.yml"
+    if not config_path.exists():
+        console.print("[red]Error:[/red] No catalog config found. Nothing to remove.")
+        raise typer.Exit(1)
+
+    try:
+        config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except Exception:
+        console.print("[red]Error:[/red] Failed to read catalog config.")
+        raise typer.Exit(1)
+
+    catalogs = config.get("catalogs", [])
+    if not isinstance(catalogs, list):
+        console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+        raise typer.Exit(1)
+    original_count = len(catalogs)
+    catalogs = [c for c in catalogs if isinstance(c, dict) and c.get("name") != name]
+
+    if len(catalogs) == original_count:
+        console.print(f"[red]Error:[/red] Catalog '{name}' not found.")
+        raise typer.Exit(1)
+
+    config["catalogs"] = catalogs
+    config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False, allow_unicode=True), encoding="utf-8")
+
+    console.print(f"[green]✓[/green] Removed catalog '{name}'")
+    if not catalogs:
+        console.print("\n[dim]No catalogs remain in config. Built-in defaults will be used.[/dim]")
+
+
+@extension_app.command("add")
+def extension_add(
+    extension: str = typer.Argument(help="Extension name or path"),
+    dev: bool = typer.Option(False, "--dev", help="Install from local directory"),
+    from_url: Optional[str] = typer.Option(None, "--from", help="Install from custom URL"),
+    force: bool = typer.Option(False, "--force", help="Overwrite if already installed"),
+    priority: int = typer.Option(10, "--priority", help="Resolution priority (lower = higher precedence, default 10)"),
+):
+    """Install an extension."""
+    from .extensions import ExtensionManager, ExtensionCatalog, ExtensionError, ValidationError, CompatibilityError, REINSTALL_COMMAND
+
+    project_root = _require_specify_project()
+    # Validate priority
+    if priority < 1:
+        console.print("[red]Error:[/red] Priority must be a positive integer (1 or higher)")
+        raise typer.Exit(1)
+
+    manager = ExtensionManager(project_root)
+    speckit_version = get_speckit_version()
+
+    if force:
+        console.print("[yellow]--force:[/yellow] Will overwrite if already installed")
+
+    # Prompt for URL-based installs BEFORE the spinner so the user can
+    # actually see and respond to the confirmation (the Rich status
+    # spinner overwrites the typer.confirm prompt line, making it appear
+    # as though the command is hung).
+    # Guard with ``not dev`` so that --dev + --from does not show a
+    # confusing confirmation for a URL that will be ignored.
+    if from_url and not dev:
+        from urllib.parse import urlparse
+        from rich.markup import escape as _escape_markup
+
+        parsed = urlparse(from_url)
+        is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+
+        if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
+            console.print("[red]Error:[/red] URL must use HTTPS for security.")
+            console.print("HTTP is only allowed for localhost URLs.")
+            raise typer.Exit(1)
+
+        safe_url = _escape_markup(from_url)
+
+        # Warn about untrusted sources — default-deny confirmation
+        console.print()
+        console.print(Panel(
+            f"[bold]You are installing an extension from an external URL that is not\n"
+            f"listed in any of your configured extension catalogs.[/bold]\n\n"
+            f"URL: {safe_url}\n\n"
+            f"Only install extensions from sources you trust.",
+            title="[bold yellow]⚠ Untrusted Source[/bold yellow]",
+            border_style="yellow",
+            padding=(1, 2),
+        ))
+        console.print()
+        confirm = typer.confirm("Continue with installation?", default=False)
+        if not confirm:
+            console.print("Cancelled")
+            raise typer.Exit(0)
+
+    try:
+        with console.status(f"[cyan]Installing extension: {extension}[/cyan]"):
+            if dev:
+                # Install from local directory
+                source_path = Path(extension).expanduser().resolve()
+                if not source_path.exists():
+                    console.print(f"[red]Error:[/red] Directory not found: {source_path}")
+                    raise typer.Exit(1)
+
+                if not (source_path / "extension.yml").exists():
+                    console.print(f"[red]Error:[/red] No extension.yml found in {source_path}")
+                    raise typer.Exit(1)
+
+                if force:
+                    console.print(f"[yellow]--force:[/yellow] Installing from [cyan]{source_path}[/cyan] (will overwrite if already installed)...")
+
+                manifest = manager.install_from_directory(
+                    source_path,
+                    speckit_version,
+                    priority=priority,
+                    link_commands=True,
+                    force=force
+                )
+
+            elif from_url:
+                # Install from URL (ZIP file)
+                import urllib.error
+
+                console.print(f"Downloading from {safe_url}...")
+
+                # Download ZIP to temp location
+                download_dir = project_root / ".specify" / "extensions" / ".cache" / "downloads"
+                download_dir.mkdir(parents=True, exist_ok=True)
+                zip_path = download_dir / f"{extension}-url-download.zip"
+
+                try:
+                    from specify_cli.authentication.http import open_url as _open_url
+
+                    with _open_url(from_url, timeout=60) as response:
+                        zip_data = response.read()
+                    zip_path.write_bytes(zip_data)
+
+                    # Install from downloaded ZIP
+                    manifest = manager.install_from_zip(zip_path, speckit_version, priority=priority, force=force)
+                except urllib.error.URLError as e:
+                    console.print(f"[red]Error:[/red] Failed to download from {safe_url}: {e}")
+                    raise typer.Exit(1)
+                finally:
+                    # Clean up downloaded ZIP
+                    if zip_path.exists():
+                        zip_path.unlink()
+
+            else:
+                # Try bundled extensions first (shipped with spec-kit)
+                bundled_path = _locate_bundled_extension(extension)
+                if bundled_path is not None:
+                    manifest = manager.install_from_directory(
+                        bundled_path, speckit_version, priority=priority, force=force
+                    )
+                else:
+                    # Install from catalog (also resolves display names to IDs)
+                    catalog = ExtensionCatalog(project_root)
+
+                    # Check if extension exists in catalog (supports both ID and display name)
+                    ext_info, catalog_error = _resolve_catalog_extension(extension, catalog, "add")
+                    if catalog_error:
+                        console.print(f"[red]Error:[/red] Could not query extension catalog: {catalog_error}")
+                        raise typer.Exit(1)
+                    if not ext_info:
+                        console.print(f"[red]Error:[/red] Extension '{extension}' not found in catalog")
+                        console.print("\nSearch available extensions:")
+                        console.print("  specify extension search")
+                        raise typer.Exit(1)
+
+                    # If catalog resolved a display name to an ID, check bundled again
+                    resolved_id = ext_info['id']
+                    if resolved_id != extension:
+                        bundled_path = _locate_bundled_extension(resolved_id)
+                        if bundled_path is not None:
+                            manifest = manager.install_from_directory(
+                                bundled_path, speckit_version, priority=priority, force=force
+                            )
+
+                    if bundled_path is None:
+                        # Bundled extensions without a download URL must come from the local package
+                        if ext_info.get("bundled") and not ext_info.get("download_url"):
+                            console.print(
+                                f"[red]Error:[/red] Extension '{ext_info['id']}' is bundled with spec-kit "
+                                f"but could not be found in the installed package."
+                            )
+                            console.print(
+                                "\nThis usually means the spec-kit installation is incomplete or corrupted."
+                            )
+                            console.print("Try reinstalling spec-kit:")
+                            console.print(f"  {REINSTALL_COMMAND}")
+                            raise typer.Exit(1)
+
+                        # Enforce install_allowed policy
+                        if not ext_info.get("_install_allowed", True):
+                            catalog_name = ext_info.get("_catalog_name", "community")
+                            console.print(
+                                f"[red]Error:[/red] '{extension}' is available in the "
+                                f"'{catalog_name}' catalog but installation is not allowed from that catalog."
+                            )
+                            console.print(
+                                f"\nTo enable installation, add '{extension}' to an approved catalog "
+                                f"(install_allowed: true) in .specify/extension-catalogs.yml."
+                            )
+                            raise typer.Exit(1)
+
+                        # Download extension ZIP (use resolved ID, not original argument which may be display name)
+                        extension_id = ext_info['id']
+                        console.print(f"Downloading {ext_info['name']} v{ext_info.get('version', 'unknown')}...")
+                        zip_path = catalog.download_extension(extension_id)
+
+                        try:
+                            # Install from downloaded ZIP
+                            manifest = manager.install_from_zip(zip_path, speckit_version, priority=priority, force=force)
+                        finally:
+                            # Clean up downloaded ZIP
+                            if zip_path.exists():
+                                zip_path.unlink()
+
+        console.print("\n[green]✓[/green] Extension installed successfully!")
+        console.print(f"\n[bold]{manifest.name}[/bold] (v{manifest.version})")
+        console.print(f"  {manifest.description}")
+
+        for warning in manifest.warnings:
+            console.print(f"\n[yellow]⚠  Compatibility warning:[/yellow] {warning}")
+
+        is_cline = load_init_options(project_root).get("ai") == "cline"
+
+        if is_cline:
+            from specify_cli.integrations.cline import format_cline_command_name
+
+        console.print("\n[bold cyan]Provided commands:[/bold cyan]")
+        for cmd in manifest.commands:
+            cmd_name = cmd['name']
+            if is_cline:
+                cmd_name = format_cline_command_name(cmd_name)
+            console.print(f"  • {cmd_name} - {cmd.get('description', '')}")
+
+        # Report agent skills registration
+        reg_meta = manager.registry.get(manifest.id)
+        reg_skills = reg_meta.get("registered_skills", []) if reg_meta else []
+        # Normalize to guard against corrupted registry entries
+        if not isinstance(reg_skills, list):
+            reg_skills = []
+        if reg_skills:
+            console.print(f"\n[green]✓[/green] {len(reg_skills)} agent skill(s) auto-registered")
+
+        console.print("\n[yellow]⚠[/yellow]  Configuration may be required")
+        console.print(f"   Check: .specify/extensions/{manifest.id}/")
+
+    except ValidationError as e:
+        console.print(f"\n[red]Validation Error:[/red] {e}")
+        raise typer.Exit(1)
+    except CompatibilityError as e:
+        console.print(f"\n[red]Compatibility Error:[/red] {e}")
+        raise typer.Exit(1)
+    except ExtensionError as e:
+        console.print(f"\n[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@extension_app.command("remove")
+def extension_remove(
+    extension: str = typer.Argument(help="Extension ID or name to remove"),
+    keep_config: bool = typer.Option(False, "--keep-config", help="Don't remove config files"),
+    force: bool = typer.Option(False, "--force", help="Skip confirmation"),
+):
+    """Uninstall an extension."""
+    from .extensions import ExtensionManager
+
+    project_root = _require_specify_project()
+    manager = ExtensionManager(project_root)
+
+    # Resolve extension ID from argument (handles ambiguous names)
+    installed = manager.list_installed()
+    extension_id, display_name = _resolve_installed_extension(extension, installed, "remove")
+
+    # Get extension info for command and skill counts
+    ext_manifest = manager.get_extension(extension_id)
+    reg_meta = manager.registry.get(extension_id)
+    # Derive cmd_count from the registry's registered_commands (includes aliases)
+    # rather than from the manifest (primary commands only). Use max() across
+    # agents to get the per-agent count; sum() would double-count since users
+    # think in logical commands, not per-agent file counts.
+    # Use get() without a default so we can distinguish "key missing" (fall back
+    # to manifest) from "key present but empty dict" (zero commands registered).
+    registered_commands = reg_meta.get("registered_commands") if isinstance(reg_meta, dict) else None
+    if isinstance(registered_commands, dict):
+        cmd_count = max(
+            (len(v) for v in registered_commands.values() if isinstance(v, list)),
+            default=0,
+        )
+    else:
+        cmd_count = len(ext_manifest.commands) if ext_manifest else 0
+    raw_skills = reg_meta.get("registered_skills") if reg_meta else None
+    skill_count = len(raw_skills) if isinstance(raw_skills, list) else 0
+
+    # Confirm removal
+    if not force:
+        console.print("\n[yellow]⚠  This will remove:[/yellow]")
+        console.print(f"   • {cmd_count} command{'s' if cmd_count != 1 else ''} per agent")
+        if skill_count:
+            console.print(f"   • {skill_count} agent skill(s)")
+        console.print(f"   • Extension directory: .specify/extensions/{extension_id}/")
+        if not keep_config:
+            console.print("   • Config files (will be backed up)")
+        console.print()
+
+        confirm = typer.confirm("Continue?")
+        if not confirm:
+            console.print("Cancelled")
+            raise typer.Exit(0)
+
+    # Remove extension
+    success = manager.remove(extension_id, keep_config=keep_config)
+
+    if success:
+        console.print(f"\n[green]✓[/green] Extension '{display_name}' removed successfully")
+        if keep_config:
+            console.print(f"\nConfig files preserved in .specify/extensions/{extension_id}/")
+        else:
+            console.print(f"\nConfig files backed up to .specify/extensions/.backup/{extension_id}/")
+        console.print(f"\nTo reinstall: specify extension add {extension_id}")
+    else:
+        console.print("[red]Error:[/red] Failed to remove extension")
+        raise typer.Exit(1)
+
+
+@extension_app.command("search")
+def extension_search(
+    query: str = typer.Argument(None, help="Search query (optional)"),
+    tag: Optional[str] = typer.Option(None, "--tag", help="Filter by tag"),
+    author: Optional[str] = typer.Option(None, "--author", help="Filter by author"),
+    verified: bool = typer.Option(False, "--verified", help="Show only verified extensions"),
+):
+    """Search for available extensions in catalog."""
+    from .extensions import ExtensionCatalog, ExtensionError
+
+    project_root = _require_specify_project()
+    catalog = ExtensionCatalog(project_root)
+
+    try:
+        console.print("🔍 Searching extension catalog...")
+        results = catalog.search(query=query, tag=tag, author=author, verified_only=verified)
+
+        if not results:
+            console.print("\n[yellow]No extensions found matching criteria[/yellow]")
+            if query or tag or author or verified:
+                console.print("\nTry:")
+                console.print("  • Broader search terms")
+                console.print("  • Remove filters")
+                console.print("  • specify extension search (show all)")
+            raise typer.Exit(0)
+
+        console.print(f"\n[green]Found {len(results)} extension(s):[/green]\n")
+
+        for ext in results:
+            # Extension header
+            verified_badge = " [green]✓ Verified[/green]" if ext.get("verified") else ""
+            console.print(f"[bold]{ext['name']}[/bold] (v{ext['version']}){verified_badge}")
+            console.print(f"  {ext['description']}")
+
+            # Metadata
+            console.print(f"\n  [dim]Author:[/dim] {ext.get('author', 'Unknown')}")
+            if ext.get('tags'):
+                tags_str = ", ".join(ext['tags'])
+                console.print(f"  [dim]Tags:[/dim] {tags_str}")
+
+            # Source catalog
+            catalog_name = ext.get("_catalog_name", "")
+            install_allowed = ext.get("_install_allowed", True)
+            if catalog_name:
+                if install_allowed:
+                    console.print(f"  [dim]Catalog:[/dim] {catalog_name}")
+                else:
+                    console.print(f"  [dim]Catalog:[/dim] {catalog_name} [yellow](discovery only — not installable)[/yellow]")
+
+            # Stats
+            stats = []
+            if ext.get('downloads') is not None:
+                stats.append(f"Downloads: {ext['downloads']:,}")
+            if ext.get('stars') is not None:
+                stats.append(f"Stars: {ext['stars']}")
+            if stats:
+                console.print(f"  [dim]{' | '.join(stats)}[/dim]")
+
+            # Links
+            if ext.get('repository'):
+                console.print(f"  [dim]Repository:[/dim] {ext['repository']}")
+
+            # Install command (show warning if not installable)
+            if install_allowed:
+                console.print(f"\n  [cyan]Install:[/cyan] specify extension add {ext['id']}")
+            else:
+                console.print(f"\n  [yellow]⚠[/yellow]  Not directly installable from '{catalog_name}'.")
+                console.print(
+                    f"  Add to an approved catalog with install_allowed: true, "
+                    f"or install from a ZIP URL: specify extension add {ext['id']} --from <zip-url>"
+                )
+            console.print()
+
+    except ExtensionError as e:
+        console.print(f"\n[red]Error:[/red] {e}")
+        console.print("\nTip: The catalog may be temporarily unavailable. Try again later.")
+        raise typer.Exit(1)
+
+
+@extension_app.command("info")
+def extension_info(
+    extension: str = typer.Argument(help="Extension ID or name"),
+):
+    """Show detailed information about an extension."""
+    from .extensions import ExtensionCatalog, ExtensionManager, normalize_priority
+
+    project_root = _require_specify_project()
+    catalog = ExtensionCatalog(project_root)
+    manager = ExtensionManager(project_root)
+    installed = manager.list_installed()
+
+    # Try to resolve from installed extensions first (by ID or name)
+    # Use allow_not_found=True since the extension may be catalog-only
+    resolved_installed_id, resolved_installed_name = _resolve_installed_extension(
+        extension, installed, "info", allow_not_found=True
+    )
+
+    # Try catalog lookup (with error handling)
+    # If we resolved an installed extension by display name, use its ID for catalog lookup
+    # to ensure we get the correct catalog entry (not a different extension with same name)
+    lookup_key = resolved_installed_id if resolved_installed_id else extension
+    ext_info, catalog_error = _resolve_catalog_extension(lookup_key, catalog, "info")
+
+    # Case 1: Found in catalog - show full catalog info
+    if ext_info:
+        _print_extension_info(ext_info, manager)
+        return
+
+    # Case 2: Installed locally but catalog lookup failed or not in catalog
+    if resolved_installed_id:
+        # Get local manifest info
+        ext_manifest = manager.get_extension(resolved_installed_id)
+        metadata = manager.registry.get(resolved_installed_id)
+        metadata_is_dict = isinstance(metadata, dict)
+        if not metadata_is_dict:
+            console.print(
+                "[yellow]Warning:[/yellow] Extension metadata appears to be corrupted; "
+                "some information may be unavailable."
+            )
+        version = metadata.get("version", "unknown") if metadata_is_dict else "unknown"
+
+        console.print(f"\n[bold]{resolved_installed_name}[/bold] (v{version})")
+        console.print(f"ID: {resolved_installed_id}")
+        console.print()
+
+        if ext_manifest:
+            console.print(f"{ext_manifest.description}")
+            console.print()
+            # Author is optional in extension.yml, safely retrieve it
+            author = ext_manifest.data.get("extension", {}).get("author")
+            if author:
+                console.print(f"[dim]Author:[/dim] {author}")
+                console.print()
+
+            if ext_manifest.commands:
+                console.print("[bold]Commands:[/bold]")
+                for cmd in ext_manifest.commands:
+                    console.print(f"  • {cmd['name']}: {cmd.get('description', '')}")
+                console.print()
+
+        # Show catalog status
+        if catalog_error:
+            console.print(f"[yellow]Catalog unavailable:[/yellow] {catalog_error}")
+            console.print("[dim]Note: Using locally installed extension; catalog info could not be verified.[/dim]")
+        else:
+            console.print("[yellow]Note:[/yellow] Not found in catalog (custom/local extension)")
+
+        console.print()
+        console.print("[green]✓ Installed[/green]")
+        priority = normalize_priority(metadata.get("priority") if metadata_is_dict else None)
+        console.print(f"[dim]Priority:[/dim] {priority}")
+        console.print(f"\nTo remove: specify extension remove {resolved_installed_id}")
+        return
+
+    # Case 3: Not found anywhere
+    if catalog_error:
+        console.print(f"[red]Error:[/red] Could not query extension catalog: {catalog_error}")
+        console.print("\nTry again when online, or use the extension ID directly.")
+    else:
+        console.print(f"[red]Error:[/red] Extension '{extension}' not found")
+        console.print("\nTry: specify extension search")
+    raise typer.Exit(1)
+
+
+def _print_extension_info(ext_info: dict, manager):
+    """Print formatted extension info from catalog data."""
+    from .extensions import normalize_priority
+
+    # Header
+    verified_badge = " [green]✓ Verified[/green]" if ext_info.get("verified") else ""
+    console.print(f"\n[bold]{ext_info['name']}[/bold] (v{ext_info['version']}){verified_badge}")
+    console.print(f"ID: {ext_info['id']}")
+    console.print()
+
+    # Description
+    console.print(f"{ext_info['description']}")
+    console.print()
+
+    # Author and License
+    console.print(f"[dim]Author:[/dim] {ext_info.get('author', 'Unknown')}")
+    console.print(f"[dim]License:[/dim] {ext_info.get('license', 'Unknown')}")
+
+    # Source catalog
+    if ext_info.get("_catalog_name"):
+        install_allowed = ext_info.get("_install_allowed", True)
+        install_note = "" if install_allowed else " [yellow](discovery only)[/yellow]"
+        console.print(f"[dim]Source catalog:[/dim] {ext_info['_catalog_name']}{install_note}")
+    console.print()
+
+    # Requirements
+    if ext_info.get('requires'):
+        console.print("[bold]Requirements:[/bold]")
+        reqs = ext_info['requires']
+        if reqs.get('speckit_version'):
+            console.print(f"  • Spec Kit: {reqs['speckit_version']}")
+        if reqs.get('tools'):
+            for tool in reqs['tools']:
+                tool_name = tool['name']
+                tool_version = tool.get('version', 'any')
+                required = " (required)" if tool.get('required') else " (optional)"
+                console.print(f"  • {tool_name}: {tool_version}{required}")
+        console.print()
+
+    # Provides
+    if ext_info.get('provides'):
+        console.print("[bold]Provides:[/bold]")
+        provides = ext_info['provides']
+        if provides.get('commands'):
+            console.print(f"  • Commands: {provides['commands']}")
+        if provides.get('hooks'):
+            console.print(f"  • Hooks: {provides['hooks']}")
+        console.print()
+
+    # Tags
+    if ext_info.get('tags'):
+        tags_str = ", ".join(ext_info['tags'])
+        console.print(f"[bold]Tags:[/bold] {tags_str}")
+        console.print()
+
+    # Statistics
+    stats = []
+    if ext_info.get('downloads') is not None:
+        stats.append(f"Downloads: {ext_info['downloads']:,}")
+    if ext_info.get('stars') is not None:
+        stats.append(f"Stars: {ext_info['stars']}")
+    if stats:
+        console.print(f"[bold]Statistics:[/bold] {' | '.join(stats)}")
+        console.print()
+
+    # Links
+    console.print("[bold]Links:[/bold]")
+    if ext_info.get('repository'):
+        console.print(f"  • Repository: {ext_info['repository']}")
+    if ext_info.get('homepage'):
+        console.print(f"  • Homepage: {ext_info['homepage']}")
+    if ext_info.get('documentation'):
+        console.print(f"  • Documentation: {ext_info['documentation']}")
+    if ext_info.get('changelog'):
+        console.print(f"  • Changelog: {ext_info['changelog']}")
+    console.print()
+
+    # Installation status and command
+    is_installed = manager.registry.is_installed(ext_info['id'])
+    install_allowed = ext_info.get("_install_allowed", True)
+    if is_installed:
+        console.print("[green]✓ Installed[/green]")
+        metadata = manager.registry.get(ext_info['id'])
+        priority = normalize_priority(metadata.get("priority") if isinstance(metadata, dict) else None)
+        console.print(f"[dim]Priority:[/dim] {priority}")
+        console.print(f"\nTo remove: specify extension remove {ext_info['id']}")
+    elif install_allowed:
+        console.print("[yellow]Not installed[/yellow]")
+        console.print(f"\n[cyan]Install:[/cyan] specify extension add {ext_info['id']}")
+    else:
+        catalog_name = ext_info.get("_catalog_name", "community")
+        console.print("[yellow]Not installed[/yellow]")
+        console.print(
+            f"\n[yellow]⚠[/yellow]  '{ext_info['id']}' is available in the '{catalog_name}' catalog "
+            f"but not in your approved catalog. Add it to .specify/extension-catalogs.yml "
+            f"with install_allowed: true to enable installation."
+        )
+
+
+@extension_app.command("update")
+def extension_update(
+    extension: str = typer.Argument(None, help="Extension ID or name to update (or all)"),
+):
+    """Update extension(s) to latest version."""
+    from .extensions import (
+        ExtensionManager,
+        ExtensionCatalog,
+        ExtensionError,
+        ValidationError,
+        CommandRegistrar,
+        HookExecutor,
+        normalize_priority,
+    )
+    from packaging import version as pkg_version
+    import shutil
+
+    project_root = _require_specify_project()
+    manager = ExtensionManager(project_root)
+    catalog = ExtensionCatalog(project_root)
+    speckit_version = get_speckit_version()
+
+    try:
+        # Get list of extensions to update
+        installed = manager.list_installed()
+        if extension:
+            # Update specific extension - resolve ID from argument (handles ambiguous names)
+            extension_id, _ = _resolve_installed_extension(extension, installed, "update")
+            extensions_to_update = [extension_id]
+        else:
+            # Update all extensions
+            extensions_to_update = [ext["id"] for ext in installed]
+
+        if not extensions_to_update:
+            console.print("[yellow]No extensions installed[/yellow]")
+            raise typer.Exit(0)
+
+        console.print("🔄 Checking for updates...\n")
+
+        updates_available = []
+
+        for ext_id in extensions_to_update:
+            # Get installed version
+            metadata = manager.registry.get(ext_id)
+            if metadata is None or not isinstance(metadata, dict) or "version" not in metadata:
+                console.print(f"⚠  {ext_id}: Registry entry corrupted or missing (skipping)")
+                continue
+            try:
+                installed_version = pkg_version.Version(metadata["version"])
+            except pkg_version.InvalidVersion:
+                console.print(
+                    f"⚠  {ext_id}: Invalid installed version '{metadata.get('version')}' in registry (skipping)"
+                )
+                continue
+
+            # Get catalog info
+            ext_info = catalog.get_extension_info(ext_id)
+            if not ext_info:
+                console.print(f"⚠  {ext_id}: Not found in catalog (skipping)")
+                continue
+
+            # Check if installation is allowed from this catalog
+            if not ext_info.get("_install_allowed", True):
+                console.print(f"⚠  {ext_id}: Updates not allowed from '{ext_info.get('_catalog_name', 'catalog')}' (skipping)")
+                continue
+
+            try:
+                catalog_version = pkg_version.Version(ext_info["version"])
+            except pkg_version.InvalidVersion:
+                console.print(
+                    f"⚠  {ext_id}: Invalid catalog version '{ext_info.get('version')}' (skipping)"
+                )
+                continue
+
+            if catalog_version > installed_version:
+                updates_available.append(
+                    {
+                        "id": ext_id,
+                        "name": ext_info.get("name", ext_id),  # Display name for status messages
+                        "installed": str(installed_version),
+                        "available": str(catalog_version),
+                        "download_url": ext_info.get("download_url"),
+                    }
+                )
+            else:
+                console.print(f"✓ {ext_id}: Up to date (v{installed_version})")
+
+        if not updates_available:
+            console.print("\n[green]All extensions are up to date![/green]")
+            raise typer.Exit(0)
+
+        # Show available updates
+        console.print("\n[bold]Updates available:[/bold]\n")
+        for update in updates_available:
+            console.print(
+                f"  • {update['id']}: {update['installed']} → {update['available']}"
+            )
+
+        console.print()
+        confirm = typer.confirm("Update these extensions?")
+        if not confirm:
+            console.print("Cancelled")
+            raise typer.Exit(0)
+
+        # Perform updates with atomic backup/restore
+        console.print()
+        updated_extensions = []
+        failed_updates = []
+        registrar = CommandRegistrar()
+        hook_executor = HookExecutor(project_root)
+        from .agents import CommandRegistrar as _AgentReg  # used in backup and rollback paths
+
+        # UNSET sentinel: backup not yet captured (exception before backup step)
+        UNSET = object()
+
+        for update in updates_available:
+            extension_id = update["id"]
+            ext_name = update["name"]  # Use display name for user-facing messages
+            console.print(f"📦 Updating {ext_name}...")
+
+            # Backup paths
+            backup_base = manager.extensions_dir / ".backup" / f"{extension_id}-update"
+            backup_ext_dir = backup_base / "extension"
+            backup_commands_dir = backup_base / "commands"
+            backup_config_dir = backup_base / "config"
+
+            # Store backup state
+            backup_registry_entry = None  # None means registry entry not yet captured
+            backup_installed = UNSET  # Original installed list from extensions.yml
+            backup_hooks = None  # None means backup step 4 not yet reached; {} or {...} means backup was captured
+            backed_up_command_files = {}
+
+            try:
+                # 1. Backup registry entry (always, even if extension dir doesn't exist)
+                backup_registry_entry = manager.registry.get(extension_id)
+
+                # 2. Backup extension directory
+                extension_dir = manager.extensions_dir / extension_id
+                if extension_dir.exists():
+                    backup_base.mkdir(parents=True, exist_ok=True)
+                    if backup_ext_dir.exists():
+                        shutil.rmtree(backup_ext_dir)
+                    shutil.copytree(extension_dir, backup_ext_dir)
+
+                    # Backup config files separately so they can be restored
+                    # after a successful install (install_from_directory clears dest dir).
+                    config_files = list(extension_dir.glob("*-config.yml")) + list(
+                        extension_dir.glob("*-config.local.yml")
+                    )
+                    for cfg_file in config_files:
+                        backup_config_dir.mkdir(parents=True, exist_ok=True)
+                        shutil.copy2(cfg_file, backup_config_dir / cfg_file.name)
+
+                # 3. Backup command files for all agents
+                registered_commands = backup_registry_entry.get("registered_commands", {}) if isinstance(backup_registry_entry, dict) else {}
+                for agent_name, cmd_names in registered_commands.items():
+                    if agent_name not in registrar.AGENT_CONFIGS:
+                        continue
+                    agent_config = registrar.AGENT_CONFIGS[agent_name]
+                    commands_dir = _AgentReg._resolve_agent_dir(
+                        agent_name, agent_config, project_root
+                    )
+
+                    for cmd_name in cmd_names:
+                        output_name = _AgentReg._compute_output_name(agent_name, cmd_name, agent_config)
+                        cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"
+                        if cmd_file.exists():
+                            backup_cmd_path = backup_commands_dir / agent_name / cmd_file.name
+                            backup_cmd_path.parent.mkdir(parents=True, exist_ok=True)
+                            shutil.copy2(cmd_file, backup_cmd_path)
+                            backed_up_command_files[str(cmd_file)] = str(backup_cmd_path)
+
+                        # Also backup copilot prompt files
+                        if agent_name == "copilot":
+                            prompt_file = project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"
+                            if prompt_file.exists():
+                                backup_prompt_path = backup_commands_dir / "copilot-prompts" / prompt_file.name
+                                backup_prompt_path.parent.mkdir(parents=True, exist_ok=True)
+                                shutil.copy2(prompt_file, backup_prompt_path)
+                                backed_up_command_files[str(prompt_file)] = str(backup_prompt_path)
+
+                # 4. Backup hooks and installed list from extensions.yml
+                # get_project_config() always normalizes installed->[] and hooks->{},
+                # so no sentinel is needed to distinguish key-absent from key-empty.
+                config = hook_executor.get_project_config()
+                if isinstance(config, dict):
+                    import copy
+                    # Deep-copy so nested mapping entries (e.g. version-pin dicts)
+                    # are not affected by in-place mutations during the update.
+                    backup_installed = copy.deepcopy(config.get("installed", []))
+                    backup_hooks = {}
+                    for hook_name, hook_list in config.get("hooks", {}).items():
+                        if not isinstance(hook_list, list):
+                            continue
+                        ext_hooks = [h for h in hook_list if isinstance(h, dict) and h.get("extension") == extension_id]
+                        if ext_hooks:
+                            backup_hooks[hook_name] = ext_hooks
+
+                # 5. Download new version
+                zip_path = catalog.download_extension(extension_id)
+                try:
+                    # 6. Validate extension ID from ZIP BEFORE modifying installation
+                    # Handle both root-level and nested extension.yml (GitHub auto-generated ZIPs)
+                    with zipfile.ZipFile(zip_path, "r") as zf:
+                        import yaml
+                        manifest_data = None
+                        namelist = zf.namelist()
+
+                        # First try root-level extension.yml
+                        if "extension.yml" in namelist:
+                            with zf.open("extension.yml") as f:
+                                manifest_data = yaml.safe_load(f) or {}
+                        else:
+                            # Look for extension.yml in a single top-level subdirectory
+                            # (e.g., "repo-name-branch/extension.yml")
+                            manifest_paths = [n for n in namelist if n.endswith("/extension.yml") and n.count("/") == 1]
+                            if len(manifest_paths) == 1:
+                                with zf.open(manifest_paths[0]) as f:
+                                    manifest_data = yaml.safe_load(f) or {}
+
+                        if manifest_data is None:
+                            raise ValueError("Downloaded extension archive is missing 'extension.yml'")
+
+                    zip_extension_id = manifest_data.get("extension", {}).get("id")
+                    if zip_extension_id != extension_id:
+                        raise ValueError(
+                            f"Extension ID mismatch: expected '{extension_id}', got '{zip_extension_id}'"
+                        )
+
+                    # 7. Remove old extension (handles command file cleanup and registry removal)
+                    manager.remove(extension_id, keep_config=True)
+
+                    # 8. Install new version
+                    _ = manager.install_from_zip(zip_path, speckit_version)
+
+                    # Restore user config files from backup after successful install.
+                    new_extension_dir = manager.extensions_dir / extension_id
+                    if backup_config_dir.exists() and new_extension_dir.exists():
+                        for cfg_file in backup_config_dir.iterdir():
+                            if cfg_file.is_file():
+                                shutil.copy2(cfg_file, new_extension_dir / cfg_file.name)
+
+                    # 9. Restore metadata from backup (installed_at, enabled state)
+                    if backup_registry_entry and isinstance(backup_registry_entry, dict):
+                        # Copy current registry entry to avoid mutating internal
+                        # registry state before explicit restore().
+                        current_metadata = manager.registry.get(extension_id)
+                        if current_metadata is None or not isinstance(current_metadata, dict):
+                            raise RuntimeError(
+                                f"Registry entry for '{extension_id}' missing or corrupted after install — update incomplete"
+                            )
+                        new_metadata = dict(current_metadata)
+
+                        # Preserve the original installation timestamp
+                        if "installed_at" in backup_registry_entry:
+                            new_metadata["installed_at"] = backup_registry_entry["installed_at"]
+
+                        # Preserve the original priority (normalized to handle corruption)
+                        if "priority" in backup_registry_entry:
+                            new_metadata["priority"] = normalize_priority(backup_registry_entry["priority"])
+
+                        # If extension was disabled before update, disable it again
+                        if not backup_registry_entry.get("enabled", True):
+                            new_metadata["enabled"] = False
+
+                        # Use restore() instead of update() because update() always
+                        # preserves the existing installed_at, ignoring our override
+                        manager.registry.restore(extension_id, new_metadata)
+
+                        # Also disable hooks in extensions.yml if extension was disabled
+                        if not backup_registry_entry.get("enabled", True):
+                            config = hook_executor.get_project_config()
+                            if "hooks" in config:
+                                for hook_name in config["hooks"]:
+                                    for hook in config["hooks"][hook_name]:
+                                        if hook.get("extension") == extension_id:
+                                            hook["enabled"] = False
+                                hook_executor.save_project_config(config)
+                finally:
+                    # Clean up downloaded ZIP
+                    if zip_path.exists():
+                        zip_path.unlink()
+
+                # 10. Clean up backup on success
+                if backup_base.exists():
+                    shutil.rmtree(backup_base)
+
+                console.print(f"   [green]✓[/green] Updated to v{update['available']}")
+                updated_extensions.append(ext_name)
+
+            except KeyboardInterrupt:
+                raise
+            except Exception as e:
+                console.print(f"   [red]✗[/red] Failed: {e}")
+                failed_updates.append((ext_name, str(e)))
+
+                # Rollback on failure
+                console.print(f"   [yellow]↩[/yellow] Rolling back {ext_name}...")
+
+                try:
+                    # Restore extension directory
+                    # Only perform destructive rollback if backup exists (meaning we
+                    # actually modified the extension). This avoids deleting a valid
+                    # installation when failure happened before changes were made.
+                    extension_dir = manager.extensions_dir / extension_id
+                    if backup_ext_dir.exists():
+                        if extension_dir.exists():
+                            shutil.rmtree(extension_dir)
+                        shutil.copytree(backup_ext_dir, extension_dir)
+
+                    # Remove any NEW command files created by failed install
+                    # (files that weren't in the original backup)
+                    try:
+                        new_registry_entry = manager.registry.get(extension_id)
+                        if new_registry_entry is None or not isinstance(new_registry_entry, dict):
+                            new_registered_commands = {}
+                        else:
+                            new_registered_commands = new_registry_entry.get("registered_commands", {})
+                        for agent_name, cmd_names in new_registered_commands.items():
+                            if agent_name not in registrar.AGENT_CONFIGS:
+                                continue
+                            agent_config = registrar.AGENT_CONFIGS[agent_name]
+                            commands_dir = _AgentReg._resolve_agent_dir(
+                                agent_name, agent_config, project_root
+                            )
+
+                            for cmd_name in cmd_names:
+                                output_name = _AgentReg._compute_output_name(agent_name, cmd_name, agent_config)
+                                cmd_file = commands_dir / f"{output_name}{agent_config['extension']}"
+                                # Delete if it exists and wasn't in our backup
+                                if cmd_file.exists() and str(cmd_file) not in backed_up_command_files:
+                                    cmd_file.unlink()
+
+                                # Also handle copilot prompt files
+                                if agent_name == "copilot":
+                                    prompt_file = project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"
+                                    if prompt_file.exists() and str(prompt_file) not in backed_up_command_files:
+                                        prompt_file.unlink()
+                    except KeyError:
+                        pass  # No new registry entry exists, nothing to clean up
+
+                    # Restore backed up command files
+                    for original_path, backup_path in backed_up_command_files.items():
+                        backup_file = Path(backup_path)
+                        if backup_file.exists():
+                            original_file = Path(original_path)
+                            original_file.parent.mkdir(parents=True, exist_ok=True)
+                            shutil.copy2(backup_file, original_file)
+
+                    # Restore metadata in extensions.yml (hooks and installed list).
+                    # Only run if backup step 4 was reached (backup_hooks is not None);
+                    # otherwise we have no safe baseline to restore from and could corrupt
+                    # the config by removing pre-existing hooks.
+                    if backup_hooks is not None:
+                        config = hook_executor.get_project_config()
+                        if not isinstance(config, dict):
+                            config = {}
+
+                        modified = False
+
+                        # 1. Restore hooks in extensions.yml
+                        if not isinstance(config.get("hooks"), dict):
+                            config["hooks"] = {}
+                            modified = True
+
+                        # Remove any hooks for this extension added by the failed install
+                        for hook_name in list(config["hooks"].keys()):
+                            hooks_list = config["hooks"][hook_name]
+                            if not isinstance(hooks_list, list):
+                                config["hooks"][hook_name] = []
+                                modified = True
+                                continue
+
+                            original_len = len(hooks_list)
+                            config["hooks"][hook_name] = [
+                                h for h in hooks_list
+                                if isinstance(h, dict) and h.get("extension") != extension_id
+                            ]
+                            if len(config["hooks"][hook_name]) != original_len:
+                                modified = True
+
+                        # Add back the backed-up hooks
+                        if backup_hooks:
+                            for hook_name, hooks in backup_hooks.items():
+                                if not isinstance(config["hooks"].get(hook_name), list):
+                                    config["hooks"][hook_name] = []
+                                config["hooks"][hook_name].extend(hooks)
+                                modified = True
+
+                        # 2. Restore installed list in extensions.yml
+                        if backup_installed is not UNSET:
+                            if config.get("installed") != backup_installed:
+                                config["installed"] = backup_installed
+                                modified = True
+
+                        if modified:
+                            hook_executor.save_project_config(config)
+
+                    # Restore registry entry (use restore() since entry was removed)
+                    if backup_registry_entry:
+                        manager.registry.restore(extension_id, backup_registry_entry)
+
+                    console.print("   [green]✓[/green] Rollback successful")
+                    # Clean up backup directory only on successful rollback
+                    if backup_base.exists():
+                        shutil.rmtree(backup_base)
+                except Exception as rollback_error:
+                    console.print(f"   [red]✗[/red] Rollback failed: {rollback_error}")
+                    console.print(f"   [dim]Backup preserved at: {backup_base}[/dim]")
+
+        # Summary
+        console.print()
+        if updated_extensions:
+            console.print(f"[green]✓[/green] Successfully updated {len(updated_extensions)} extension(s)")
+        if failed_updates:
+            console.print(f"[red]✗[/red] Failed to update {len(failed_updates)} extension(s):")
+            for ext_name, error in failed_updates:
+                console.print(f"   • {ext_name}: {error}")
+            raise typer.Exit(1)
+
+    except ValidationError as e:
+        console.print(f"\n[red]Validation Error:[/red] {e}")
+        raise typer.Exit(1)
+    except ExtensionError as e:
+        console.print(f"\n[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@extension_app.command("enable")
+def extension_enable(
+    extension: str = typer.Argument(help="Extension ID or name to enable"),
+):
+    """Enable a disabled extension."""
+    from .extensions import ExtensionManager, HookExecutor
+
+    project_root = _require_specify_project()
+    manager = ExtensionManager(project_root)
+    hook_executor = HookExecutor(project_root)
+
+    # Resolve extension ID from argument (handles ambiguous names)
+    installed = manager.list_installed()
+    extension_id, display_name = _resolve_installed_extension(extension, installed, "enable")
+
+    # Update registry
+    metadata = manager.registry.get(extension_id)
+    if metadata is None or not isinstance(metadata, dict):
+        console.print(f"[red]Error:[/red] Extension '{extension_id}' not found in registry (corrupted state)")
+        raise typer.Exit(1)
+
+    if metadata.get("enabled", True):
+        console.print(f"[yellow]Extension '{display_name}' is already enabled[/yellow]")
+        raise typer.Exit(0)
+
+    manager.registry.update(extension_id, {"enabled": True})
+
+    # Enable hooks in extensions.yml
+    config = hook_executor.get_project_config()
+    if "hooks" in config:
+        for hook_name in config["hooks"]:
+            for hook in config["hooks"][hook_name]:
+                if hook.get("extension") == extension_id:
+                    hook["enabled"] = True
+        hook_executor.save_project_config(config)
+
+    console.print(f"[green]✓[/green] Extension '{display_name}' enabled")
+
+
+@extension_app.command("disable")
+def extension_disable(
+    extension: str = typer.Argument(help="Extension ID or name to disable"),
+):
+    """Disable an extension without removing it."""
+    from .extensions import ExtensionManager, HookExecutor
+
+    project_root = _require_specify_project()
+    manager = ExtensionManager(project_root)
+    hook_executor = HookExecutor(project_root)
+
+    # Resolve extension ID from argument (handles ambiguous names)
+    installed = manager.list_installed()
+    extension_id, display_name = _resolve_installed_extension(extension, installed, "disable")
+
+    # Update registry
+    metadata = manager.registry.get(extension_id)
+    if metadata is None or not isinstance(metadata, dict):
+        console.print(f"[red]Error:[/red] Extension '{extension_id}' not found in registry (corrupted state)")
+        raise typer.Exit(1)
+
+    if not metadata.get("enabled", True):
+        console.print(f"[yellow]Extension '{display_name}' is already disabled[/yellow]")
+        raise typer.Exit(0)
+
+    manager.registry.update(extension_id, {"enabled": False})
+
+    # Disable hooks in extensions.yml
+    config = hook_executor.get_project_config()
+    if "hooks" in config:
+        for hook_name in config["hooks"]:
+            for hook in config["hooks"][hook_name]:
+                if hook.get("extension") == extension_id:
+                    hook["enabled"] = False
+        hook_executor.save_project_config(config)
+
+    console.print(f"[green]✓[/green] Extension '{display_name}' disabled")
+    console.print("\nCommands will no longer be available. Hooks will not execute.")
+    console.print(f"To re-enable: specify extension enable {extension_id}")
+
+
+@extension_app.command("set-priority")
+def extension_set_priority(
+    extension: str = typer.Argument(help="Extension ID or name"),
+    priority: int = typer.Argument(help="New priority (lower = higher precedence)"),
+):
+    """Set the resolution priority of an installed extension."""
+    from .extensions import ExtensionManager
+
+    project_root = _require_specify_project()
+    # Validate priority
+    if priority < 1:
+        console.print("[red]Error:[/red] Priority must be a positive integer (1 or higher)")
+        raise typer.Exit(1)
+
+    manager = ExtensionManager(project_root)
+
+    # Resolve extension ID from argument (handles ambiguous names)
+    installed = manager.list_installed()
+    extension_id, display_name = _resolve_installed_extension(extension, installed, "set-priority")
+
+    # Get current metadata
+    metadata = manager.registry.get(extension_id)
+    if metadata is None or not isinstance(metadata, dict):
+        console.print(f"[red]Error:[/red] Extension '{extension_id}' not found in registry (corrupted state)")
+        raise typer.Exit(1)
+
+    from .extensions import normalize_priority
+    raw_priority = metadata.get("priority")
+    # Only skip if the stored value is already a valid int equal to requested priority
+    # This ensures corrupted values (e.g., "high") get repaired even when setting to default (10)
+    if isinstance(raw_priority, int) and raw_priority == priority:
+        console.print(f"[yellow]Extension '{display_name}' already has priority {priority}[/yellow]")
+        raise typer.Exit(0)
+
+    old_priority = normalize_priority(raw_priority)
+
+    # Update priority
+    manager.registry.update(extension_id, {"priority": priority})
+
+    console.print(f"[green]✓[/green] Extension '{display_name}' priority changed: {old_priority} → {priority}")
+    console.print("\n[dim]Lower priority = higher precedence in template resolution[/dim]")
+
+
+# ===== Workflow Commands =====
+
+workflow_app = typer.Typer(
+    name="workflow",
+    help="Manage and run automation workflows",
+    add_completion=False,
+)
+app.add_typer(workflow_app, name="workflow")
+
+workflow_catalog_app = typer.Typer(
+    name="catalog",
+    help="Manage workflow catalogs",
+    add_completion=False,
+)
+workflow_app.add_typer(workflow_catalog_app, name="catalog")
+
+
+def _parse_input_values(input_values: list[str] | None) -> dict[str, Any]:
+    """Parse repeated ``key=value`` CLI inputs into a dict.
+
+    Shared by ``workflow run`` and ``workflow resume``. Exits with an error
+    on any entry missing ``=``.
+    """
+    inputs: dict[str, Any] = {}
+    for kv in input_values or []:
+        if "=" not in kv:
+            console.print(f"[red]Error:[/red] Invalid input format: {kv!r} (expected key=value)")
+            raise typer.Exit(1)
+        key, _, value = kv.partition("=")
+        inputs[key.strip()] = value.strip()
+    return inputs
+
+
+def _workflow_run_payload(state: Any) -> dict[str, Any]:
+    """Machine-readable summary of a run/resume outcome."""
+    return {
+        "run_id": state.run_id,
+        "workflow_id": state.workflow_id,
+        "status": state.status.value,
+        "current_step_id": state.current_step_id,
+        "current_step_index": state.current_step_index,
+    }
+
+
+def _emit_workflow_json(payload: dict[str, Any]) -> None:
+    """Write a workflow payload as machine-readable JSON to stdout.
+
+    Uses the builtin ``print`` rather than ``console.print`` so Rich
+    markup interpretation, syntax highlighting, and line-wrapping can
+    never alter the emitted JSON.
+    """
+    print(json.dumps(payload, indent=2))
+
+
+@contextlib.contextmanager
+def _stdout_to_stderr_when(active: bool):
+    """Redirect everything written to stdout onto stderr while *active*.
+
+    Suppressing the banner and the step-start callback is not enough to
+    keep a ``--json`` stream clean: individual steps may still write to
+    stdout while the engine runs — the gate step prints its prompt,
+    and the prompt step runs a subprocess that inherits the process's
+    stdout file descriptor. Either would corrupt the single JSON object.
+
+    Redirecting at the file-descriptor level (``dup2``) captures both
+    Python-level writes and inherited-fd subprocess output, so step
+    progress lands on stderr (still visible to a human) while stdout
+    carries only the emitted JSON. A no-op when *active* is false.
+    """
+    if not active:
+        yield
+        return
+    sys.stdout.flush()
+    saved_stdout_fd = os.dup(1)
+    try:
+        os.dup2(2, 1)  # fd 1 (stdout) now points at fd 2 (stderr)
+        with contextlib.redirect_stdout(sys.stderr):
+            yield
+    finally:
+        sys.stdout.flush()
+        os.dup2(saved_stdout_fd, 1)  # restore the real stdout
+        os.close(saved_stdout_fd)
+
+
+@workflow_app.command("run")
+def workflow_run(
+    source: str = typer.Argument(..., help="Workflow ID or YAML file path"),
+    input_values: list[str] | None = typer.Option(
+        None, "--input", "-i", help="Input values as key=value pairs"
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the run outcome as a single JSON object instead of formatted text.",
+    ),
+):
+    """Run a workflow from an installed ID or local YAML path."""
+    from .workflows.engine import WorkflowEngine
+
+    source_path = Path(source).expanduser()
+    is_file_source = source_path.suffix.lower() in (".yml", ".yaml") and source_path.is_file()
+
+    if is_file_source:
+        # When running a YAML file directly, use cwd as project root
+        # without requiring a .specify/ project directory.
+        project_root = Path.cwd()
+        specify_dir = project_root / ".specify"
+        if specify_dir.is_symlink():
+            console.print("[red]Error:[/red] Refusing to use symlinked .specify path in current directory")
+            raise typer.Exit(1)
+        if specify_dir.exists() and not specify_dir.is_dir():
+            console.print("[red]Error:[/red] .specify path exists but is not a directory")
+            raise typer.Exit(1)
+    else:
+        project_root = _require_specify_project()
+
+    engine = WorkflowEngine(project_root)
+    if not json_output:
+        engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
+
+    try:
+        definition = engine.load_workflow(source_path if is_file_source else source)
+    except FileNotFoundError:
+        console.print(f"[red]Error:[/red] Workflow not found: {source}")
+        raise typer.Exit(1)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] Invalid workflow: {exc}")
+        raise typer.Exit(1)
+
+    # Validate
+    errors = engine.validate(definition)
+    if errors:
+        console.print("[red]Workflow validation failed:[/red]")
+        for err in errors:
+            console.print(f"  • {err}")
+        raise typer.Exit(1)
+
+    # Parse inputs
+    inputs = _parse_input_values(input_values)
+
+    if not json_output:
+        console.print(f"\n[bold cyan]Running workflow:[/bold cyan] {definition.name} ({definition.id})")
+        console.print(f"[dim]Version: {definition.version}[/dim]\n")
+
+    try:
+        with _stdout_to_stderr_when(json_output):
+            state = engine.execute(definition, inputs)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+    except Exception as exc:
+        console.print(f"[red]Workflow failed:[/red] {exc}")
+        raise typer.Exit(1)
+
+    if json_output:
+        _emit_workflow_json(_workflow_run_payload(state))
+        return
+
+    status_colors = {
+        "completed": "green",
+        "paused": "yellow",
+        "failed": "red",
+        "aborted": "red",
+    }
+    color = status_colors.get(state.status.value, "white")
+    console.print(f"\n[{color}]Status: {state.status.value}[/{color}]")
+    console.print(f"[dim]Run ID: {state.run_id}[/dim]")
+
+    if state.status.value == "paused":
+        console.print(f"\nResume with: [cyan]specify workflow resume {state.run_id}[/cyan]")
+
+
+@workflow_app.command("resume")
+def workflow_resume(
+    run_id: str = typer.Argument(..., help="Run ID to resume"),
+    input_values: list[str] | None = typer.Option(
+        None, "--input", "-i", help="Updated input values as key=value pairs"
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the resume outcome as a single JSON object instead of formatted text.",
+    ),
+):
+    """Resume a paused or failed workflow run."""
+    from .workflows.engine import WorkflowEngine
+
+    project_root = _require_specify_project()
+    engine = WorkflowEngine(project_root)
+    if not json_output:
+        engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
+
+    inputs = _parse_input_values(input_values)
+
+    try:
+        with _stdout_to_stderr_when(json_output):
+            state = engine.resume(run_id, inputs or None)
+    except FileNotFoundError:
+        console.print(f"[red]Error:[/red] Run not found: {run_id}")
+        raise typer.Exit(1)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+    except Exception as exc:
+        console.print(f"[red]Resume failed:[/red] {exc}")
+        raise typer.Exit(1)
+
+    if json_output:
+        _emit_workflow_json(_workflow_run_payload(state))
+        return
+
+    status_colors = {
+        "completed": "green",
+        "paused": "yellow",
+        "failed": "red",
+        "aborted": "red",
+    }
+    color = status_colors.get(state.status.value, "white")
+    console.print(f"\n[{color}]Status: {state.status.value}[/{color}]")
+
+
+@workflow_app.command("status")
+def workflow_status(
+    run_id: str | None = typer.Argument(None, help="Run ID to inspect (shows all if omitted)"),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit run status as a single JSON object instead of formatted text.",
+    ),
+):
+    """Show workflow run status."""
+    from .workflows.engine import WorkflowEngine
+
+    project_root = _require_specify_project()
+    engine = WorkflowEngine(project_root)
+
+    if run_id:
+        try:
+            from .workflows.engine import RunState
+            state = RunState.load(run_id, project_root)
+        except FileNotFoundError:
+            console.print(f"[red]Error:[/red] Run not found: {run_id}")
+            raise typer.Exit(1)
+
+        if json_output:
+            # Build on the shared run/resume payload so the common fields
+            # (including current_step_index) stay identical across commands.
+            payload = {
+                **_workflow_run_payload(state),
+                "created_at": state.created_at,
+                "updated_at": state.updated_at,
+                "steps": {
+                    sid: sd.get("status", "unknown")
+                    for sid, sd in state.step_results.items()
+                },
+            }
+            _emit_workflow_json(payload)
+            return
+
+        status_colors = {
+            "completed": "green",
+            "paused": "yellow",
+            "failed": "red",
+            "aborted": "red",
+            "running": "blue",
+            "created": "dim",
+        }
+        color = status_colors.get(state.status.value, "white")
+
+        console.print(f"\n[bold cyan]Workflow Run: {state.run_id}[/bold cyan]")
+        console.print(f"  Workflow: {state.workflow_id}")
+        console.print(f"  Status:   [{color}]{state.status.value}[/{color}]")
+        console.print(f"  Created:  {state.created_at}")
+        console.print(f"  Updated:  {state.updated_at}")
+
+        if state.current_step_id:
+            console.print(f"  Current:  {state.current_step_id}")
+
+        if state.step_results:
+            console.print(f"\n  [bold]Steps ({len(state.step_results)}):[/bold]")
+            for step_id, step_data in state.step_results.items():
+                s = step_data.get("status", "unknown")
+                sc = {"completed": "green", "failed": "red", "paused": "yellow"}.get(s, "white")
+                console.print(f"    [{sc}]●[/{sc}] {step_id}: {s}")
+    else:
+        runs = engine.list_runs()
+
+        if json_output:
+            payload = {
+                "runs": [
+                    {
+                        "run_id": r["run_id"],
+                        "workflow_id": r.get("workflow_id"),
+                        "status": r.get("status", "unknown"),
+                        "updated_at": r.get("updated_at"),
+                    }
+                    for r in runs
+                ]
+            }
+            _emit_workflow_json(payload)
+            return
+
+        if not runs:
+            console.print("[yellow]No workflow runs found.[/yellow]")
+            return
+
+        console.print("\n[bold cyan]Workflow Runs:[/bold cyan]\n")
+        for run_data in runs:
+            s = run_data.get("status", "unknown")
+            sc = {"completed": "green", "failed": "red", "paused": "yellow", "running": "blue"}.get(s, "white")
+            console.print(
+                f"  [{sc}]●[/{sc}] {run_data['run_id']}  "
+                f"{run_data.get('workflow_id', '?')}  "
+                f"[{sc}]{s}[/{sc}]  "
+                f"[dim]{run_data.get('updated_at', '?')}[/dim]"
+            )
+
+
+@workflow_app.command("list")
+def workflow_list():
+    """List installed workflows."""
+    from .workflows.catalog import WorkflowRegistry
+
+    project_root = _require_specify_project()
+    registry = WorkflowRegistry(project_root)
+    installed = registry.list()
+
+    if not installed:
+        console.print("[yellow]No workflows installed.[/yellow]")
+        console.print("\nInstall a workflow with:")
+        console.print("  [cyan]specify workflow add <workflow-id>[/cyan]")
+        return
+
+    console.print("\n[bold cyan]Installed Workflows:[/bold cyan]\n")
+    for wf_id, wf_data in installed.items():
+        console.print(f"  [bold]{wf_data.get('name', wf_id)}[/bold] ({wf_id}) v{wf_data.get('version', '?')}")
+        desc = wf_data.get("description", "")
+        if desc:
+            console.print(f"    {desc}")
+        console.print()
+
+
+@workflow_app.command("add")
+def workflow_add(
+    source: str = typer.Argument(..., help="Workflow ID, URL, or local path"),
+):
+    """Install a workflow from catalog, URL, or local path."""
+    from .workflows.catalog import WorkflowCatalog, WorkflowRegistry, WorkflowCatalogError
+    from .workflows.engine import WorkflowDefinition
+
+    project_root = _require_specify_project()
+    registry = WorkflowRegistry(project_root)
+    workflows_dir = project_root / ".specify" / "workflows"
+
+    def _validate_and_install_local(yaml_path: Path, source_label: str) -> None:
+        """Validate and install a workflow from a local YAML file."""
+        try:
+            definition = WorkflowDefinition.from_yaml(yaml_path)
+        except (ValueError, yaml.YAMLError) as exc:
+            console.print(f"[red]Error:[/red] Invalid workflow YAML: {exc}")
+            raise typer.Exit(1)
+        if not definition.id or not definition.id.strip():
+            console.print("[red]Error:[/red] Workflow definition has an empty or missing 'id'")
+            raise typer.Exit(1)
+
+        from .workflows.engine import validate_workflow
+        errors = validate_workflow(definition)
+        if errors:
+            console.print("[red]Error:[/red] Workflow validation failed:")
+            for err in errors:
+                console.print(f"  \u2022 {err}")
+            raise typer.Exit(1)
+
+        dest_dir = workflows_dir / definition.id
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        import shutil
+        shutil.copy2(yaml_path, dest_dir / "workflow.yml")
+        registry.add(definition.id, {
+            "name": definition.name,
+            "version": definition.version,
+            "description": definition.description,
+            "source": source_label,
+        })
+        console.print(f"[green]✓[/green] Workflow '{definition.name}' ({definition.id}) installed")
+
+    # Try as URL (http/https)
+    if source.startswith("http://") or source.startswith("https://"):
+        from ipaddress import ip_address
+        from urllib.parse import urlparse
+        from specify_cli.authentication.http import open_url as _open_url
+
+        parsed_src = urlparse(source)
+        src_host = parsed_src.hostname or ""
+        src_loopback = src_host == "localhost"
+        if not src_loopback:
+            try:
+                src_loopback = ip_address(src_host).is_loopback
+            except ValueError:
+                # Host is not an IP literal (e.g., a DNS name); keep default non-loopback.
+                pass
+        if parsed_src.scheme != "https" and not (parsed_src.scheme == "http" and src_loopback):
+            console.print("[red]Error:[/red] Only HTTPS URLs are allowed, except HTTP for localhost.")
+            raise typer.Exit(1)
+
+        import tempfile
+        try:
+            with _open_url(source, timeout=30) as resp:
+                final_url = resp.geturl()
+                final_parsed = urlparse(final_url)
+                final_host = final_parsed.hostname or ""
+                final_lb = final_host == "localhost"
+                if not final_lb:
+                    try:
+                        final_lb = ip_address(final_host).is_loopback
+                    except ValueError:
+                        # Redirect host is not an IP literal; keep loopback as determined above.
+                        pass
+                if final_parsed.scheme != "https" and not (final_parsed.scheme == "http" and final_lb):
+                    console.print(f"[red]Error:[/red] URL redirected to non-HTTPS: {final_url}")
+                    raise typer.Exit(1)
+                with tempfile.NamedTemporaryFile(suffix=".yml", delete=False) as tmp:
+                    tmp.write(resp.read())
+                    tmp_path = Path(tmp.name)
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            console.print(f"[red]Error:[/red] Failed to download workflow: {exc}")
+            raise typer.Exit(1)
+        try:
+            _validate_and_install_local(tmp_path, source)
+        finally:
+            tmp_path.unlink(missing_ok=True)
+        return
+
+    # Try as a local file/directory
+    source_path = Path(source)
+    if source_path.exists():
+        if source_path.is_file() and source_path.suffix in (".yml", ".yaml"):
+            _validate_and_install_local(source_path, str(source_path))
+            return
+        elif source_path.is_dir():
+            wf_file = source_path / "workflow.yml"
+            if not wf_file.exists():
+                console.print(f"[red]Error:[/red] No workflow.yml found in {source}")
+                raise typer.Exit(1)
+            _validate_and_install_local(wf_file, str(source_path))
+            return
+
+    # Try from catalog
+    catalog = WorkflowCatalog(project_root)
+    try:
+        info = catalog.get_workflow_info(source)
+    except WorkflowCatalogError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    if not info:
+        console.print(f"[red]Error:[/red] Workflow '{source}' not found in catalog")
+        raise typer.Exit(1)
+
+    if not info.get("_install_allowed", True):
+        console.print(f"[yellow]Warning:[/yellow] Workflow '{source}' is from a discovery-only catalog")
+        console.print("Direct installation is not enabled for this catalog source.")
+        raise typer.Exit(1)
+
+    workflow_url = info.get("url")
+    if not workflow_url:
+        console.print(f"[red]Error:[/red] Workflow '{source}' does not have an install URL in the catalog")
+        raise typer.Exit(1)
+
+    # Validate URL scheme (HTTPS required, HTTP allowed for localhost only)
+    from ipaddress import ip_address
+    from urllib.parse import urlparse
+
+    parsed_url = urlparse(workflow_url)
+    url_host = parsed_url.hostname or ""
+    is_loopback = False
+    if url_host == "localhost":
+        is_loopback = True
+    else:
+        try:
+            is_loopback = ip_address(url_host).is_loopback
+        except ValueError:
+            # Host is not an IP literal (e.g., a regular hostname); treat as non-loopback.
+            pass
+    if parsed_url.scheme != "https" and not (parsed_url.scheme == "http" and is_loopback):
+        console.print(
+            f"[red]Error:[/red] Workflow '{source}' has an invalid install URL. "
+            "Only HTTPS URLs are allowed, except HTTP for localhost/loopback."
+        )
+        raise typer.Exit(1)
+
+    workflow_dir = workflows_dir / source
+    # Validate that source is a safe directory name (no path traversal)
+    try:
+        workflow_dir.resolve().relative_to(workflows_dir.resolve())
+    except ValueError:
+        console.print(f"[red]Error:[/red] Invalid workflow ID: {source!r}")
+        raise typer.Exit(1)
+    workflow_file = workflow_dir / "workflow.yml"
+
+    try:
+        from specify_cli.authentication.http import open_url as _open_url
+
+        workflow_dir.mkdir(parents=True, exist_ok=True)
+        with _open_url(workflow_url, timeout=30) as response:
+            # Validate final URL after redirects
+            final_url = response.geturl()
+            final_parsed = urlparse(final_url)
+            final_host = final_parsed.hostname or ""
+            final_loopback = final_host == "localhost"
+            if not final_loopback:
+                try:
+                    final_loopback = ip_address(final_host).is_loopback
+                except ValueError:
+                    # Host is not an IP literal (e.g., a regular hostname); treat as non-loopback.
+                    pass
+            if final_parsed.scheme != "https" and not (final_parsed.scheme == "http" and final_loopback):
+                if workflow_dir.exists():
+                    import shutil
+                    shutil.rmtree(workflow_dir, ignore_errors=True)
+                console.print(
+                    f"[red]Error:[/red] Workflow '{source}' redirected to non-HTTPS URL: {final_url}"
+                )
+                raise typer.Exit(1)
+            workflow_file.write_bytes(response.read())
+    except Exception as exc:
+        if workflow_dir.exists():
+            import shutil
+            shutil.rmtree(workflow_dir, ignore_errors=True)
+        console.print(f"[red]Error:[/red] Failed to install workflow '{source}' from catalog: {exc}")
+        raise typer.Exit(1)
+
+    # Validate the downloaded workflow before registering
+    try:
+        definition = WorkflowDefinition.from_yaml(workflow_file)
+    except (ValueError, yaml.YAMLError) as exc:
+        import shutil
+        shutil.rmtree(workflow_dir, ignore_errors=True)
+        console.print(f"[red]Error:[/red] Downloaded workflow is invalid: {exc}")
+        raise typer.Exit(1)
+
+    from .workflows.engine import validate_workflow
+    errors = validate_workflow(definition)
+    if errors:
+        import shutil
+        shutil.rmtree(workflow_dir, ignore_errors=True)
+        console.print("[red]Error:[/red] Downloaded workflow validation failed:")
+        for err in errors:
+            console.print(f"  \u2022 {err}")
+        raise typer.Exit(1)
+
+    # Enforce that the workflow's internal ID matches the catalog key
+    if definition.id and definition.id != source:
+        import shutil
+        shutil.rmtree(workflow_dir, ignore_errors=True)
+        console.print(
+            f"[red]Error:[/red] Workflow ID in YAML ({definition.id!r}) "
+            f"does not match catalog key ({source!r}). "
+            f"The catalog entry may be misconfigured."
+        )
+        raise typer.Exit(1)
+
+    registry.add(source, {
+        "name": definition.name or info.get("name", source),
+        "version": definition.version or info.get("version", "0.0.0"),
+        "description": definition.description or info.get("description", ""),
+        "source": "catalog",
+        "catalog_name": info.get("_catalog_name", ""),
+        "url": workflow_url,
+    })
+    console.print(f"[green]✓[/green] Workflow '{info.get('name', source)}' installed from catalog")
+
+
+@workflow_app.command("remove")
+def workflow_remove(
+    workflow_id: str = typer.Argument(..., help="Workflow ID to uninstall"),
+):
+    """Uninstall a workflow."""
+    from .workflows.catalog import WorkflowRegistry
+
+    project_root = _require_specify_project()
+    registry = WorkflowRegistry(project_root)
+
+    if not registry.is_installed(workflow_id):
+        console.print(f"[red]Error:[/red] Workflow '{workflow_id}' is not installed")
+        raise typer.Exit(1)
+
+    # Remove workflow files
+    workflow_dir = project_root / ".specify" / "workflows" / workflow_id
+    if workflow_dir.exists():
+        import shutil
+        shutil.rmtree(workflow_dir)
+
+    registry.remove(workflow_id)
+    console.print(f"[green]✓[/green] Workflow '{workflow_id}' removed")
+
+
+@workflow_app.command("search")
+def workflow_search(
+    query: str | None = typer.Argument(None, help="Search query"),
+    tag: str | None = typer.Option(None, "--tag", help="Filter by tag"),
+):
+    """Search workflow catalogs."""
+    from .workflows.catalog import WorkflowCatalog, WorkflowCatalogError
+
+    project_root = _require_specify_project()
+    catalog = WorkflowCatalog(project_root)
+
+    try:
+        results = catalog.search(query=query, tag=tag)
+    except WorkflowCatalogError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    if not results:
+        console.print("[yellow]No workflows found.[/yellow]")
+        return
+
+    console.print(f"\n[bold cyan]Workflows ({len(results)}):[/bold cyan]\n")
+    for wf in results:
+        console.print(f"  [bold]{wf.get('name', wf.get('id', '?'))}[/bold] ({wf.get('id', '?')}) v{wf.get('version', '?')}")
+        desc = wf.get("description", "")
+        if desc:
+            console.print(f"    {desc}")
+        tags = wf.get("tags", [])
+        if tags:
+            console.print(f"    [dim]Tags: {', '.join(tags)}[/dim]")
+        console.print()
+
+
+@workflow_app.command("info")
+def workflow_info(
+    workflow_id: str = typer.Argument(..., help="Workflow ID"),
+):
+    """Show workflow details and step graph."""
+    from .workflows.catalog import WorkflowCatalog, WorkflowRegistry, WorkflowCatalogError
+    from .workflows.engine import WorkflowEngine
+
+    project_root = _require_specify_project()
+
+    # Check installed first
+    registry = WorkflowRegistry(project_root)
+    installed = registry.get(workflow_id)
+
+    engine = WorkflowEngine(project_root)
+
+    definition = None
+    try:
+        definition = engine.load_workflow(workflow_id)
+    except FileNotFoundError:
+        # Local workflow definition not found on disk; fall back to
+        # catalog/registry lookup below.
+        pass
+
+    if definition:
+        console.print(f"\n[bold cyan]{definition.name}[/bold cyan] ({definition.id})")
+        console.print(f"  Version:     {definition.version}")
+        if definition.author:
+            console.print(f"  Author:      {definition.author}")
+        if definition.description:
+            console.print(f"  Description: {definition.description}")
+        if definition.default_integration:
+            console.print(f"  Integration: {definition.default_integration}")
+        if installed:
+            console.print("  [green]Installed[/green]")
+
+        if definition.inputs:
+            console.print("\n  [bold]Inputs:[/bold]")
+            for name, inp in definition.inputs.items():
+                if isinstance(inp, dict):
+                    req = "required" if inp.get("required") else "optional"
+                    console.print(f"    {name} ({inp.get('type', 'string')}) — {req}")
+
+        if definition.steps:
+            console.print(f"\n  [bold]Steps ({len(definition.steps)}):[/bold]")
+            for step in definition.steps:
+                stype = step.get("type", "command")
+                console.print(f"    → {step.get('id', '?')} [{stype}]")
+        return
+
+    # Try catalog
+    catalog = WorkflowCatalog(project_root)
+    try:
+        info = catalog.get_workflow_info(workflow_id)
+    except WorkflowCatalogError:
+        info = None
+
+    if info:
+        console.print(f"\n[bold cyan]{info.get('name', workflow_id)}[/bold cyan] ({workflow_id})")
+        console.print(f"  Version:     {info.get('version', '?')}")
+        if info.get("description"):
+            console.print(f"  Description: {info['description']}")
+        if info.get("tags"):
+            console.print(f"  Tags:        {', '.join(info['tags'])}")
+        console.print("  [yellow]Not installed[/yellow]")
+    else:
+        console.print(f"[red]Error:[/red] Workflow '{workflow_id}' not found")
+        raise typer.Exit(1)
+
+
+@workflow_catalog_app.command("list")
+def workflow_catalog_list():
+    """List configured workflow catalog sources."""
+    from .workflows.catalog import WorkflowCatalog, WorkflowCatalogError
+
+    project_root = _require_specify_project()
+    catalog = WorkflowCatalog(project_root)
+
+    try:
+        configs = catalog.get_catalog_configs()
+    except WorkflowCatalogError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    console.print("\n[bold cyan]Workflow Catalog Sources:[/bold cyan]\n")
+    for i, cfg in enumerate(configs):
+        install_status = "[green]install allowed[/green]" if cfg["install_allowed"] else "[yellow]discovery only[/yellow]"
+        console.print(f"  [{i}] [bold]{cfg['name']}[/bold] — {install_status}")
+        console.print(f"      {cfg['url']}")
+        if cfg.get("description"):
+            console.print(f"      [dim]{cfg['description']}[/dim]")
+        console.print()
+
+
+@workflow_catalog_app.command("add")
+def workflow_catalog_add(
+    url: str = typer.Argument(..., help="Catalog URL to add"),
+    name: str = typer.Option(None, "--name", help="Catalog name"),
+):
+    """Add a workflow catalog source."""
+    from .workflows.catalog import WorkflowCatalog, WorkflowValidationError
+
+    project_root = _require_specify_project()
+    catalog = WorkflowCatalog(project_root)
+    try:
+        catalog.add_catalog(url, name)
+    except WorkflowValidationError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] Catalog source added: {url}")
+
+
+@workflow_catalog_app.command("remove")
+def workflow_catalog_remove(
+    index: int = typer.Argument(..., help="Catalog index to remove (from 'catalog list')"),
+):
+    """Remove a workflow catalog source by index."""
+    from .workflows.catalog import WorkflowCatalog, WorkflowValidationError
+
+    project_root = _require_specify_project()
+    catalog = WorkflowCatalog(project_root)
+    try:
+        removed_name = catalog.remove_catalog(index)
+    except WorkflowValidationError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]✓[/green] Catalog source '{removed_name}' removed")
+
+
+def main():
+    # On Windows the default stdout/stderr code page (e.g. cp1252) cannot encode
+    # the Rich banner and box-drawing glyphs, so the CLI crashes with
+    # UnicodeEncodeError whenever output is not a UTF-8 TTY (piped, redirected to
+    # a file, or running under a legacy code page). Force UTF-8 with graceful
+    # replacement so output degrades instead of aborting. No-op on POSIX.
+    if sys.platform == "win32":
+        for _stream in (sys.stdout, sys.stderr):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")
+            except (AttributeError, ValueError, OSError):
+                pass
+    app()
+
+if __name__ == "__main__":
+    main()