π« Toolkit to help you get started with SDD or any other process!
Add Zed integration (#2780)
Ahmet TOK1150d32aee71
diff --git a/docs/index.md b/docs/index.mdindex c8b02d98c..5772d6cc9 100644--- a/docs/index.md+++ b/docs/index.md@@ -4,7 +4,7 @@**Define what to build before building it β with any AI coding agent.**-Spec Kit is a toolkit for [Spec-Driven Development](concepts/sdd.md) (SDD), a methodology that puts specifications at the center of AI-assisted software development. Instead of jumping straight to code, you describe *what* to build, refine it through structured phases, and let your AI coding agent implement it.+Spec Kit is a toolkit for [Spec-Driven Development](concepts/sdd.md) (SDD), a methodology that puts specifications at the center of AI-assisted software development. Instead of jumping straight to code, you describe _what_ to build, refine it through structured phases, and let your AI coding agent implement it.<a href="installation.md" class="btn btn-primary btn-lg">Install Spec Kit</a> <a href="quickstart.md" class="btn btn-outline-primary btn-lg">Quick Start</a>@@ -31,7 +31,7 @@ Define what to build before building it. Rich templates, quality checklists, and### Use any coding agent-<span class="pillar-stat">30 integrations</span> β Copilot, Gemini, Codex, Windsurf, Claude, Forge, Kiro, and more. Switch freely between agents with a single command. No lock-in.+<span class="pillar-stat">30+ integrations</span> β Copilot, Gemini, Codex, Windsurf, Zed, Claude, Forge, Kiro, and more. Switch freely between agents with a single command. No lock-in.Run `specify init` with your agent of choice and Spec Kit sets up the right command files, context rules, and directory structures automatically. If your agent isn't listed, the `generic` integration is an escape hatch for any tool.@@ -90,7 +90,7 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a<span class="stat-label">Contributors</span></div><div class="stat-item">- <span class="stat-number">30</span>+ <span class="stat-number">30+</span><span class="stat-label">Integrations</span></div><div class="stat-item">diff --git a/docs/reference/integrations.md b/docs/reference/integrations.mdindex d7480ac29..a79038977 100644--- a/docs/reference/integrations.md+++ b/docs/reference/integrations.md@@ -38,6 +38,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify| [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli) | `tabnine` | || [Trae](https://www.trae.ai/) | `trae` | Skills-based integration; skills are installed automatically || [Windsurf](https://windsurf.com/) | `windsurf` | |+| [Zed](https://zed.dev/) | `zed` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `/speckit-<command>` || Generic | `generic` | Bring your own agent β use `--integration generic --integration-options="--commands-dir <path>"` for AI coding agents not listed above |## List Available Integrationsdiff --git a/src/specify_cli/_invocation_style.py b/src/specify_cli/_invocation_style.pynew file mode 100644index 000000000..a61f699a5--- /dev/null+++ b/src/specify_cli/_invocation_style.py@@ -0,0 +1,45 @@+"""Agent invocation-style constants and helpers.++Agents that scaffold skills (``speckit-<name>/SKILL.md``) use different+slash-command invocation formats depending on the agent. This module+centralises the mapping so that ``HookExecutor._render_hook_invocation``+and ``specify init``'s next-steps output stay consistent.+"""++from __future__ import annotations++# Agents that always render /speckit-<name>, regardless of ai_skills.+ALWAYS_SLASH_AGENTS: frozenset[str] = frozenset({"devin", "trae", "zed"})++# Agents that render /speckit-<name> only when ai_skills is enabled.+CONDITIONAL_SLASH_AGENTS: frozenset[str] = frozenset(+ {+ "agy",+ "claude",+ "copilot",+ "cursor-agent",+ "hermes",+ "lingma",+ "rovodev",+ "vibe",+ }+)+++def is_slash_skills_agent(selected_ai: str | None, ai_skills_enabled: bool) -> bool:+ """Return ``True`` if *selected_ai* uses ``/speckit-<name>`` invocations.++ The decision is based on the agent sets defined in this module:++ * Agents in `ALWAYS_SLASH_AGENTS` always use slash invocations.+ * Agents in `CONDITIONAL_SLASH_AGENTS` only use them when+ *ai_skills_enabled* is ``True``.+ * All other agents return ``False``.+ """+ if selected_ai is None:+ return False+ if not isinstance(selected_ai, str):+ return False+ return selected_ai in ALWAYS_SLASH_AGENTS or (+ selected_ai in CONDITIONAL_SLASH_AGENTS and ai_skills_enabled+ )diff --git a/src/specify_cli/commands/init.py b/src/specify_cli/commands/init.pyindex 8307bb7cf..227f0f975 100644--- a/src/specify_cli/commands/init.py+++ b/src/specify_cli/commands/init.py@@ -1,4 +1,5 @@"""specify init command."""+from __future__ import annotationsimport os@@ -35,7 +36,9 @@ def ensure_constitution_from_template() -> None:"""Copy constitution template to memory if it doesn't exist."""memory_constitution = project_path / ".specify" / "memory" / "constitution.md"- template_constitution = project_path / ".specify" / "templates" / "constitution-template.md"+ template_constitution = (+ project_path / ".specify" / "templates" / "constitution-template.md"+ )if memory_constitution.exists():if tracker:@@ -62,24 +65,75 @@ def ensure_constitution_from_template(tracker.add("constitution", "Constitution setup")tracker.error("constitution", str(e))else:- console.print(f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]")+ console.print(+ f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]"+ )def register(app: typer.Typer) -> None:@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)"),- 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 coding agent tools like Claude Code"),- 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="Deprecated (no-op). Previously: skip SSL/TLS verification.", hidden=True),- debug: bool = typer.Option(False, "--debug", help="Deprecated. Previously: show verbose diagnostic output; currently only prints additional diagnostic details on failure.", hidden=True),- github_token: str = typer.Option(None, "--github-token", help="Deprecated (no-op). Previously: GitHub token for API requests.", hidden=True),- offline: bool = typer.Option(False, "--offline", help="Deprecated (no-op). All scaffolding now uses bundled assets.", hidden=True),- preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"),- integration: str = typer.Option(None, "--integration", help="AI coding agent integration to use (e.g. --integration copilot). See 'specify check' for available integrations."),- integration_options: str = typer.Option(None, "--integration-options", help='Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")'),+ project_name: str = typer.Argument(+ None,+ help="Name for your new project directory (optional if using --here, or use '.' for current directory)",+ ),+ 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 coding agent tools like Claude Code",+ ),+ 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="Deprecated (no-op). Previously: skip SSL/TLS verification.",+ hidden=True,+ ),+ debug: bool = typer.Option(+ False,+ "--debug",+ help="Deprecated. Previously: show verbose diagnostic output; currently only prints additional diagnostic details on failure.",+ hidden=True,+ ),+ github_token: str = typer.Option(+ None,+ "--github-token",+ help="Deprecated (no-op). Previously: GitHub token for API requests.",+ hidden=True,+ ),+ offline: bool = typer.Option(+ False,+ "--offline",+ help="Deprecated (no-op). All scaffolding now uses bundled assets.",+ hidden=True,+ ),+ preset: str = typer.Option(+ None,+ "--preset",+ help="Install a preset during initialization (by preset ID)",+ ),+ integration: str = typer.Option(+ None,+ "--integration",+ help="AI coding agent integration to use (e.g. --integration copilot). See 'specify check' for available integrations.",+ ),+ integration_options: str = typer.Option(+ None,+ "--integration-options",+ help='Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")',+ ),):"""Initialize a new Specify project.@@ -121,15 +175,18 @@ def register(app: typer.Typer) -> None:ensure_executable_scripts,save_init_options,)+ from ..integration_runtime import (+ with_integration_setting as _with_integration_setting,+ )from ..integrations._commands import (_parse_integration_options,_write_integration_json,)- from ..integration_runtime import with_integration_setting as _with_integration_settingshow_banner()from ..integrations import INTEGRATION_REGISTRY, get_integration+if integration:resolved_integration = get_integration(integration)if not resolved_integration:@@ -143,15 +200,17 @@ def register(app: typer.Typer) -> None:project_name = Noneif here and project_name:- console.print("[red]Error:[/red] Cannot specify both project name and --here flag")+ console.print(+ "[red]Error:[/red] Cannot specify both project name and --here flag"+ )raise typer.Exit(1)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")+ console.print(+ "[red]Error:[/red] Must specify either a project name, use '.' for current directory, or use --here flag"+ )raise typer.Exit(1)--dir_existed_before = Falseif here:project_name = Path.cwd().name@@ -160,10 +219,16 @@ def register(app: typer.Typer) -> None: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]")+ 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]")+ console.print(+ "[cyan]--force supplied: skipping confirmation and proceeding with merge[/cyan]"+ )else:response = typer.confirm("Do you want to continue?")if not response:@@ -174,14 +239,22 @@ def register(app: typer.Typer) -> None:dir_existed_before = project_path.exists()if project_path.exists():if not project_path.is_dir():- console.print(f"[red]Error:[/red] '{project_name}' exists but is not a directory.")+ console.print(+ f"[red]Error:[/red] '{project_name}' exists but is not a directory."+ )raise typer.Exit(1)existing_items = list(project_path.iterdir())if force:if existing_items:- console.print(f"[yellow]Warning:[/yellow] Directory '{project_name}' is not empty ({len(existing_items)} items)")- console.print("[yellow]Template files will be merged with existing content and may overwrite existing files[/yellow]")- console.print(f"[cyan]--force supplied: merging into existing directory '[cyan]{project_name}[/cyan]'[/cyan]")+ console.print(+ f"[yellow]Warning:[/yellow] Directory '{project_name}' is not empty ({len(existing_items)} items)"+ )+ console.print(+ "[yellow]Template files will be merged with existing content and may overwrite existing files[/yellow]"+ )+ console.print(+ f"[cyan]--force supplied: merging into existing directory '[cyan]{project_name}[/cyan]'[/cyan]"+ )else:error_panel = Panel(f"Directory already exists: '[cyan]{project_name}[/cyan]'\n"@@ -189,7 +262,7 @@ def register(app: typer.Typer) -> None:"Use [bold]--force[/bold] to merge into the existing directory.",title="[red]Directory Conflict[/red]",border_style="red",- padding=(1, 2)+ padding=(1, 2),)console.print()console.print(error_panel)@@ -197,7 +270,9 @@ def register(app: typer.Typer) -> None:if integration:if integration not in AGENT_CONFIG:- console.print(f"[red]Error:[/red] Invalid integration '{integration}'. Choose from: {', '.join(AGENT_CONFIG.keys())}")+ console.print(+ f"[red]Error:[/red] Invalid integration '{integration}'. Choose from: {', '.join(AGENT_CONFIG.keys())}"+ )raise typer.Exit(1)selected_ai = integrationelif not _stdin_is_interactive():@@ -221,8 +296,12 @@ def register(app: typer.Typer) -> None:raise typer.Exit(1)if selected_ai == "generic" and not integration_options:- console.print("[red]Error:[/red] --integration generic requires --integration-options with --commands-dir")- console.print('[dim]Example: specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/"[/dim]')+ console.print(+ "[red]Error:[/red] --integration generic requires --integration-options with --commands-dir"+ )+ console.print(+ '[dim]Example: specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/"[/dim]'+ )raise typer.Exit(1)current_dir = Path.cwd()@@ -237,7 +316,9 @@ def register(app: typer.Typer) -> None: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)))+ console.print(+ Panel("\n".join(setup_lines), border_style="cyan", padding=(1, 2))+ )if not ignore_agent_tools:agent_config = AGENT_CONFIG.get(selected_ai)@@ -251,7 +332,7 @@ def register(app: typer.Typer) -> None:"Tip: Use [cyan]--ignore-agent-tools[/cyan] to skip this check",title="[red]Agent Detection Error[/red]",border_style="red",- padding=(1, 2)+ padding=(1, 2),)console.print()console.print(error_panel)@@ -259,14 +340,20 @@ def register(app: typer.Typer) -> None: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())}")+ 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_typeelse:default_script = "ps" if os.name == "nt" else "sh"if _stdin_is_interactive():- selected_script = select_with_arrows(SCRIPT_TYPE_CHOICES, "Choose script type (or press Enter)", default_script)+ selected_script = select_with_arrows(+ SCRIPT_TYPE_CHOICES,+ "Choose script type (or press Enter)",+ default_script,+ )else:selected_script = default_script@@ -294,23 +381,31 @@ def register(app: typer.Typer) -> None:]:tracker.add(key, label)- with Live(tracker.render(), console=console, refresh_per_second=8, transient=True) as live:+ with Live(+ tracker.render(), console=console, refresh_per_second=8, transient=True+ ) as live:tracker.attach_refresh(lambda: live.update(tracker.render()))try:from ..integrations.manifest import IntegrationManifest+tracker.start("integration")manifest = IntegrationManifest(- resolved_integration.key, project_path, version=get_speckit_version()+ resolved_integration.key,+ project_path,+ version=get_speckit_version(),)integration_parsed_options: dict[str, Any] = {}if integration_options:- extra = _parse_integration_options(resolved_integration, integration_options)+ extra = _parse_integration_options(+ resolved_integration, integration_options+ )if extra:integration_parsed_options.update(extra)resolved_integration.setup(- project_path, manifest,+ project_path,+ manifest,parsed_options=integration_parsed_options or None,script_type=selected_script,raw_options=integration_options,@@ -332,7 +427,10 @@ def register(app: typer.Typer) -> None:integration_settings,)- tracker.complete("integration", resolved_integration.config.get("name", resolved_integration.key))+ tracker.complete(+ "integration",+ resolved_integration.config.get("name", resolved_integration.key),+ )tracker.start("shared-infra")_install_shared_infra_or_exit(@@ -340,9 +438,13 @@ def register(app: typer.Typer) -> None:selected_script,tracker=tracker,force=force,- invoke_separator=resolved_integration.effective_invoke_separator(integration_parsed_options),+ invoke_separator=resolved_integration.effective_invoke_separator(+ integration_parsed_options+ ),+ )+ tracker.complete(+ "shared-infra", f"scripts ({selected_script}) + templates")- tracker.complete("shared-infra", f"scripts ({selected_script}) + templates")ensure_constitution_from_template(project_path, tracker=tracker)@@ -351,29 +453,38 @@ def register(app: typer.Typer) -> None:if bundled_wf:from ..workflows.catalog import WorkflowRegistryfrom ..workflows.engine import WorkflowDefinition+wf_registry = WorkflowRegistry(project_path)if wf_registry.is_installed("speckit"):tracker.complete("workflow", "already installed")else:import shutil as _shutil- dest_wf = project_path / ".specify" / "workflows" / "speckit"++ dest_wf = (+ project_path / ".specify" / "workflows" / "speckit"+ )dest_wf.mkdir(parents=True, exist_ok=True)_shutil.copy2(bundled_wf / "workflow.yml",dest_wf / "workflow.yml",)- definition = WorkflowDefinition.from_yaml(dest_wf / "workflow.yml")- wf_registry.add("speckit", {- "name": definition.name,- "version": definition.version,- "description": definition.description,- "source": "bundled",- })+ definition = WorkflowDefinition.from_yaml(+ dest_wf / "workflow.yml"+ )+ wf_registry.add(+ "speckit",+ {+ "name": definition.name,+ "version": definition.version,+ "description": definition.description,+ "source": "bundled",+ },+ )tracker.complete("workflow", "speckit installed")else:tracker.skip("workflow", "bundled workflow not found")except Exception as wf_err:- sanitized_wf = str(wf_err).replace('\n', ' ').strip()+ sanitized_wf = str(wf_err).replace("\n", " ").strip()tracker.error("workflow", f"install failed: {sanitized_wf[:120]}")init_opts = {@@ -385,7 +496,10 @@ def register(app: typer.Typer) -> None:"speckit_version": get_speckit_version(),}from ..integrations.base import SkillsIntegration as _SkillsPersist- if isinstance(resolved_integration, _SkillsPersist) or getattr(resolved_integration, "_skills_mode", False):++ if isinstance(resolved_integration, _SkillsPersist) or getattr(+ resolved_integration, "_skills_mode", False+ ):init_opts["ai_skills"] = Truesave_init_options(project_path, init_opts)@@ -394,6 +508,7 @@ def register(app: typer.Typer) -> None:# registration can read ai_skills + integration key.try:from ..extensions import ExtensionManager as _ExtMgr+bundled_ac = _locate_bundled_extension("agent-context")if bundled_ac:ac_mgr = _ExtMgr(project_path)@@ -406,13 +521,14 @@ def register(app: typer.Typer) -> None:tracker.complete("agent-context", "extension installed")else:from ..extensions import REINSTALL_COMMAND as _ac_reinstall+tracker.error("agent-context",f"bundled extension not found β installation may be "f"incomplete. Run: {_ac_reinstall}",)except Exception as ac_err:- sanitized_ac = str(ac_err).replace('\n', ' ').strip()+ sanitized_ac = str(ac_err).replace("\n", " ").strip()tracker.error("agent-context",f"extension install failed: {sanitized_ac[:120]}",@@ -432,24 +548,34 @@ def register(app: typer.Typer) -> None:if preset:try:- from ..presets import PresetManager, PresetCatalog, PresetError+ from ..presets import PresetCatalog, PresetError, PresetManager+preset_manager = PresetManager(project_path)speckit_ver = get_speckit_version()local_path = Path(preset).resolve()if local_path.is_dir() and (local_path / "preset.yml").exists():- preset_manager.install_from_directory(local_path, speckit_ver)+ preset_manager.install_from_directory(+ local_path, speckit_ver+ )else:bundled_path = _locate_bundled_preset(preset)if bundled_path:- preset_manager.install_from_directory(bundled_path, speckit_ver)+ preset_manager.install_from_directory(+ bundled_path, speckit_ver+ )else:preset_catalog = PresetCatalog(project_path)pack_info = preset_catalog.get_pack_info(preset)if not pack_info:- console.print(f"[yellow]Warning:[/yellow] Preset '{preset}' not found in catalog. Skipping.")- elif pack_info.get("bundled") and not pack_info.get("download_url"):+ console.print(+ f"[yellow]Warning:[/yellow] Preset '{preset}' not found in catalog. Skipping."+ )+ elif pack_info.get("bundled") and not pack_info.get(+ "download_url"+ ):from ..extensions import REINSTALL_COMMAND+console.print(f"[yellow]Warning:[/yellow] Preset '{preset}' is bundled with spec-kit "f"but could not be found in the installed package."@@ -457,12 +583,16 @@ def register(app: typer.Typer) -> None:console.print("This usually means the spec-kit installation is incomplete or corrupted.")- console.print(f"Try reinstalling: {REINSTALL_COMMAND}")+ console.print(+ f"Try reinstalling: {REINSTALL_COMMAND}"+ )else:zip_path = Nonetry:zip_path = preset_catalog.download_pack(preset)- preset_manager.install_from_zip(zip_path, speckit_ver)+ preset_manager.install_from_zip(+ zip_path, speckit_ver+ )except PresetError as preset_err:_print_cli_warning("install",@@ -491,7 +621,13 @@ def register(app: typer.Typer) -> None:raiseexcept Exception as e:tracker.error("final", str(e))- console.print(Panel(f"Initialization failed: {e}", title="Failure", border_style="red"))+ console.print(+ Panel(+ f"Initialization failed: {e}",+ title="Failure",+ border_style="red",+ )+ )if debug:_env_pairs = [("Python", sys.version.split()[0]),@@ -499,8 +635,17 @@ def register(app: typer.Typer) -> None:("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"))+ 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() and not dir_existed_before:shutil.rmtree(project_path)raise typer.Exit(1)@@ -512,74 +657,132 @@ def register(app: typer.Typer) -> None:agent_config = AGENT_CONFIG.get(selected_ai)if agent_config:- agent_folder = agent_config["folder"] or integration_parsed_options.get("commands_dir")+ agent_folder = agent_config["folder"] or integration_parsed_options.get(+ "commands_dir"+ )if agent_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)+ padding=(1, 2),)console.print()console.print(security_notice)steps_lines = []if not here:- steps_lines.append(f"1. Go to the project folder: [cyan]cd {project_name}[/cyan]")+ steps_lines.append(+ f"1. Go to the project folder: [cyan]cd {project_name}[/cyan]"+ )step_num = 2else:steps_lines.append("1. You're already in the project directory!")step_num = 2from ..integrations.base import SkillsIntegration as _SkillsInt- _is_skills_integration = isinstance(resolved_integration, _SkillsInt) or getattr(resolved_integration, "_skills_mode", False)++ _is_skills_integration = isinstance(+ resolved_integration, _SkillsInt+ ) or getattr(resolved_integration, "_skills_mode", False)codex_skill_mode = selected_ai == "codex" and _is_skills_integrationclaude_skill_mode = selected_ai == "claude" and _is_skills_integrationkimi_skill_mode = selected_ai == "kimi"agy_skill_mode = selected_ai == "agy" and _is_skills_integrationtrae_skill_mode = selected_ai == "trae"- cursor_agent_skill_mode = selected_ai == "cursor-agent" and _is_skills_integration+ cursor_agent_skill_mode = (+ selected_ai == "cursor-agent" and _is_skills_integration+ )copilot_skill_mode = selected_ai == "copilot" and _is_skills_integrationdevin_skill_mode = selected_ai == "devin"+ zed_skill_mode = selected_ai == "zed" and _is_skills_integrationcline_skill_mode = selected_ai == "cline"- native_skill_mode = codex_skill_mode or claude_skill_mode or kimi_skill_mode or agy_skill_mode or trae_skill_mode or cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode+ native_skill_mode = (+ codex_skill_mode+ or claude_skill_mode+ or kimi_skill_mode+ or agy_skill_mode+ or trae_skill_mode+ or cursor_agent_skill_mode+ or copilot_skill_mode+ or devin_skill_mode+ or zed_skill_mode+ )if codex_skill_mode:- steps_lines.append(f"{step_num}. Start Codex in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]")+ steps_lines.append(+ f"{step_num}. Start Codex in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]"+ )step_num += 1if claude_skill_mode:- steps_lines.append(f"{step_num}. Start Claude in this project directory; spec-kit skills were installed to [cyan].claude/skills[/cyan]")+ steps_lines.append(+ f"{step_num}. Start Claude in this project directory; spec-kit skills were installed to [cyan].claude/skills[/cyan]"+ )step_num += 1if cursor_agent_skill_mode:- steps_lines.append(f"{step_num}. Start Cursor Agent in this project directory; spec-kit skills were installed to [cyan].cursor/skills[/cyan]")+ steps_lines.append(+ f"{step_num}. Start Cursor Agent in this project directory; spec-kit skills were installed to [cyan].cursor/skills[/cyan]"+ )step_num += 1if devin_skill_mode:- steps_lines.append(f"{step_num}. Start Devin in this project directory; spec-kit skills were installed to [cyan].devin/skills[/cyan]")+ steps_lines.append(+ f"{step_num}. Start Devin in this project directory; spec-kit skills were installed to [cyan].devin/skills[/cyan]"+ )+ step_num += 1+ if zed_skill_mode:+ steps_lines.append(+ f"{step_num}. Start Zed in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]"+ )step_num += 1usage_label = "skills" if native_skill_mode else "slash commands"+ from .._invocation_style import is_slash_skills_agent as _is_slash_skills_agent++ # `_is_skills_integration` means the integration is installed in+ # skills mode, which is the semantic equivalent of `ai_skills_enabled`+ # used by `is_slash_skills_agent()`.+ _ai_skills_enabled = _is_skills_integration+def _display_cmd(name: str) -> str:- if codex_skill_mode or agy_skill_mode or trae_skill_mode:+ if codex_skill_mode:return f"$speckit-{name}"- if claude_skill_mode:- return f"/speckit-{name}"if kimi_skill_mode:return f"/skill:speckit-{name}"- if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or cline_skill_mode:+ if (+ _is_slash_skills_agent(selected_ai, _ai_skills_enabled)+ or cline_skill_mode+ ):return f"/speckit-{name}"return f"/speckit.{name}"- steps_lines.append(f"{step_num}. Start using {usage_label} with your coding agent:")+ steps_lines.append(+ f"{step_num}. Start using {usage_label} with your coding agent:"+ )- steps_lines.append(f" {step_num}.1 [cyan]{_display_cmd('constitution')}[/] - Establish project principles")- steps_lines.append(f" {step_num}.2 [cyan]{_display_cmd('specify')}[/] - Create baseline specification")- steps_lines.append(f" {step_num}.3 [cyan]{_display_cmd('plan')}[/] - Create implementation plan")- steps_lines.append(f" {step_num}.4 [cyan]{_display_cmd('tasks')}[/] - Generate actionable tasks")- steps_lines.append(f" {step_num}.5 [cyan]{_display_cmd('implement')}[/] - Execute implementation")+ steps_lines.append(+ f" {step_num}.1 [cyan]{_display_cmd('constitution')}[/] - Establish project principles"+ )+ steps_lines.append(+ f" {step_num}.2 [cyan]{_display_cmd('specify')}[/] - Create baseline specification"+ )+ steps_lines.append(+ f" {step_num}.3 [cyan]{_display_cmd('plan')}[/] - Create implementation plan"+ )+ steps_lines.append(+ f" {step_num}.4 [cyan]{_display_cmd('tasks')}[/] - Generate actionable tasks"+ )+ steps_lines.append(+ f" {step_num}.5 [cyan]{_display_cmd('implement')}[/] - Execute implementation"+ )- steps_panel = Panel("\n".join(steps_lines), title="Next Steps", border_style="cyan", padding=(1, 2))+ steps_panel = Panel(+ "\n".join(steps_lines),+ title="Next Steps",+ border_style="cyan",+ padding=(1, 2),+ )console.print()console.print(steps_panel)@@ -593,9 +796,16 @@ def register(app: typer.Typer) -> None:"",f"β [cyan]{_display_cmd('clarify')}[/] [bright_black](optional)[/bright_black] - Ask structured questions to de-risk ambiguous areas before planning (run before [cyan]{_display_cmd('plan')}[/] if used)",f"β [cyan]{_display_cmd('analyze')}[/] [bright_black](optional)[/bright_black] - Cross-artifact consistency & alignment report (after [cyan]{_display_cmd('tasks')}[/], before [cyan]{_display_cmd('implement')}[/])",- f"β [cyan]{_display_cmd('checklist')}[/] [bright_black](optional)[/bright_black] - Generate quality checklists to validate requirements completeness, clarity, and consistency (after [cyan]{_display_cmd('plan')}[/])"+ f"β [cyan]{_display_cmd('checklist')}[/] [bright_black](optional)[/bright_black] - Generate quality checklists to validate requirements completeness, clarity, and consistency (after [cyan]{_display_cmd('plan')}[/])",]- enhancements_title = "Enhancement Skills" if native_skill_mode else "Enhancement Commands"- enhancements_panel = Panel("\n".join(enhancement_lines), title=enhancements_title, border_style="cyan", padding=(1, 2))+ enhancements_title = (+ "Enhancement Skills" if native_skill_mode else "Enhancement Commands"+ )+ enhancements_panel = Panel(+ "\n".join(enhancement_lines),+ title=enhancements_title,+ border_style="cyan",+ padding=(1, 2),+ )console.print()console.print(enhancements_panel)diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.pyindex db53b7997..df2eae008 100644--- a/src/specify_cli/extensions.py+++ b/src/specify_cli/extensions.py@@ -6,39 +6,44 @@ Extensions are modular packages that add commands and functionality to spec-kitwithout bloating the core framework."""-import json+from __future__ import annotations++import copyimport hashlib+import jsonimport os+import re+import shutilimport tempfileimport zipfile-import shutil-import copyfrom dataclasses import dataclass-from pathlib import Path-from typing import Optional, Dict, List, Any, Callable, Setfrom datetime import datetime, timezone-import re+from pathlib import Path+from typing import Any, Callable, Dict, List, Optional, Setimport pathspec-import yamlfrom packaging import version as pkg_version-from packaging.specifiers import SpecifierSet, InvalidSpecifier+from packaging.specifiers import InvalidSpecifier, SpecifierSet-from .catalogs import CatalogEntry as BaseCatalogEntry, CatalogStackBasefrom ._init_options import is_ai_skills_enabled--_FALLBACK_CORE_COMMAND_NAMES = frozenset({- "analyze",- "clarify",- "constitution",- "implement",- "plan",- "checklist",- "specify",- "tasks",- "taskstoissues",-})+from ._invocation_style import is_slash_skills_agent+from .catalogs import CatalogEntry as BaseCatalogEntry+from .catalogs import CatalogStackBase++_FALLBACK_CORE_COMMAND_NAMES = frozenset(+ {+ "analyze",+ "checklist",+ "clarify",+ "constitution",+ "implement",+ "plan",+ "specify",+ "tasks",+ "taskstoissues",+ }+)EXTENSION_COMMAND_NAME_PATTERN = re.compile(r"^speckit\.([a-z0-9-]+)\.([a-z0-9-]+)$")VALID_EFFECTS = frozenset({"read-only", "read-write"})@@ -80,16 +85,19 @@ CORE_COMMAND_NAMES = _load_core_command_names()class ExtensionError(Exception):"""Base exception for extension-related errors."""+passclass ValidationError(ExtensionError):"""Raised when extension manifest validation fails."""+passclass CompatibilityError(ExtensionError):"""Raised when extension is incompatible with current environment."""+pass@@ -152,7 +160,7 @@ class ExtensionManifest:def _load_yaml(self, path: Path) -> dict:"""Load YAML file safely."""try:- with open(path, 'r', encoding='utf-8') as f:+ with open(path, "r", encoding="utf-8") as f:data = yaml.safe_load(f)except yaml.YAMLError as e:raise ValidationError(f"Invalid YAML in {path}: {e}")@@ -191,7 +199,7 @@ class ExtensionManifest:raise ValidationError(f"Missing extension.{field}")# Validate extension ID format- if not re.match(r'^[a-z0-9-]+$', ext["id"]):+ if not re.match(r"^[a-z0-9-]+$", ext["id"]):raise ValidationError(f"Invalid extension ID '{ext['id']}': ""must be lowercase alphanumeric with hyphens only"@@ -229,21 +237,15 @@ class ExtensionManifest:hooks = self.data.get("hooks")if "commands" in provides and not isinstance(commands, list):- raise ValidationError(- "Invalid provides.commands: expected a list"- )+ raise ValidationError("Invalid provides.commands: expected a list")if "hooks" in self.data and not isinstance(hooks, dict):- raise ValidationError(- "Invalid hooks: expected a mapping"- )+ raise ValidationError("Invalid hooks: expected a mapping")has_commands = bool(commands)has_hooks = bool(hooks)if not has_commands and not has_hooks:- raise ValidationError(- "Extension must provide at least one command or hook"- )+ raise ValidationError("Extension must provide at least one command or hook")# Validate hook values (if present).# Each event is a single mapping or a list of mappings.@@ -363,9 +365,9 @@ class ExtensionManifest:Returns the corrected name, or None if no safe correction is possible."""- parts = name.split('.')+ parts = name.split(".")if len(parts) == 2:- if parts[0] == 'speckit' or parts[0] == ext_id:+ if parts[0] == "speckit" or parts[0] == ext_id:candidate = f"speckit.{ext_id}.{parts[1]}"if EXTENSION_COMMAND_NAME_PATTERN.match(candidate):return candidate@@ -418,7 +420,7 @@ class ExtensionManifest:def get_hash(self) -> str:"""Calculate SHA256 hash of manifest file."""- with open(self.path, 'rb') as f:+ with open(self.path, "rb") as f:return f"sha256:{hashlib.sha256(f.read()).hexdigest()}"@@ -441,35 +443,26 @@ class ExtensionRegistry:def _load(self) -> dict:"""Load registry from disk."""if not self.registry_path.exists():- return {- "schema_version": self.SCHEMA_VERSION,- "extensions": {}- }+ return {"schema_version": self.SCHEMA_VERSION, "extensions": {}}try:- with open(self.registry_path, 'r') as f:+ with open(self.registry_path, "r") as f:data = json.load(f)# Validate loaded data is a dict (handles corrupted registry files)if not isinstance(data, dict):- return {- "schema_version": self.SCHEMA_VERSION,- "extensions": {}- }+ return {"schema_version": self.SCHEMA_VERSION, "extensions": {}}# Normalize extensions field (handles corrupted extensions value)if not isinstance(data.get("extensions"), dict):data["extensions"] = {}return dataexcept (json.JSONDecodeError, FileNotFoundError):# Corrupted or missing registry, start fresh- return {- "schema_version": self.SCHEMA_VERSION,- "extensions": {}- }+ return {"schema_version": self.SCHEMA_VERSION, "extensions": {}}def _save(self):"""Save registry to disk."""self.extensions_dir.mkdir(parents=True, exist_ok=True)- with open(self.registry_path, 'w') as f:+ with open(self.registry_path, "w") as f:json.dump(self.data, f, indent=2)def add(self, extension_id: str, metadata: dict):@@ -481,7 +474,7 @@ class ExtensionRegistry:"""self.data["extensions"][extension_id] = {**copy.deepcopy(metadata),- "installed_at": datetime.now(timezone.utc).isoformat()+ "installed_at": datetime.now(timezone.utc).isoformat(),}self._save()@@ -538,7 +531,9 @@ class ExtensionRegistry:ValueError: If metadata is None or not a dict"""if metadata is None or not isinstance(metadata, dict):- raise ValueError(f"Cannot restore '{extension_id}': metadata must be a dict")+ raise ValueError(+ f"Cannot restore '{extension_id}': metadata must be a dict"+ )# Ensure extensions dict exists (handle corrupted registry)if not isinstance(self.data.get("extensions"), dict):self.data["extensions"] = {}@@ -651,7 +646,9 @@ class ExtensionRegistry:if not include_disabled and not meta.get("enabled", True):continuemetadata_copy = copy.deepcopy(meta)- metadata_copy["priority"] = normalize_priority(metadata_copy.get("priority", 10))+ metadata_copy["priority"] = normalize_priority(+ metadata_copy.get("priority", 10)+ )sortable_extensions.append((ext_id, metadata_copy))return sorted(sortable_extensions,@@ -797,7 +794,9 @@ class ExtensionManager:)@staticmethod- def _load_extensionignore(source_dir: Path) -> Optional[Callable[[str, List[str]], Set[str]]]:+ def _load_extensionignore(+ source_dir: Path,+ ) -> Optional[Callable[[str, List[str]], Set[str]]]:"""Load .extensionignore and return an ignore function for shutil.copytree.The .extensionignore file uses .gitignore-compatible patterns (one per line).@@ -905,7 +904,10 @@ class ExtensionManager:raise NotADirectoryError(f"{skills_dir} is not a directory")except (OSError, ValueError) as exc:_print_cli_warning(- "resolve", "skills directory", str(skills_dir), exc,+ "resolve",+ "skills directory",+ str(skills_dir),+ exc,continuing="Continuing without skill registration.",)return None@@ -915,7 +917,10 @@ class ExtensionManager:skills_dir = resolve_active_skills_dir(self.project_root)except (ValueError, OSError) as exc:_print_cli_warning(- "resolve", "skills directory", None, exc,+ "resolve",+ "skills directory",+ None,+ exc,continuing="Continuing without skill registration.",)return None@@ -969,7 +974,6 @@ class ExtensionManager:from . import load_init_optionsfrom .agents import CommandRegistrarfrom .integrations import get_integration- import yamlwritten: List[str] = []opts = load_init_options(self.project_root)@@ -1004,7 +1008,7 @@ class ExtensionManager:# convention as hook rendering and preset skill registration.short_name_raw = cmd_nameif short_name_raw.startswith("speckit."):- short_name_raw = short_name_raw[len("speckit."):]+ short_name_raw = short_name_raw[len("speckit.") :]skill_name = f"speckit-{short_name_raw.replace('.', '-')}"# Check if skill already exists before creating the directory@@ -1074,20 +1078,16 @@ class ExtensionManager:# Derive a human-friendly title from the command nameshort_name = cmd_nameif short_name.startswith("speckit."):- short_name = short_name[len("speckit."):]+ short_name = short_name[len("speckit.") :]title_name = short_name.replace(".", " ").replace("-", " ").title()skill_content = (- f"---\n"- f"{frontmatter_text}\n"- f"---\n\n"- f"# {title_name} Skill\n\n"- f"{body}\n"+ f"---\n{frontmatter_text}\n---\n\n# {title_name} Skill\n\n{body}\n")- if integration is not None and hasattr(integration, "post_process_skill_content"):- skill_content = integration.post_process_skill_content(- skill_content- )+ if integration is not None and hasattr(+ integration, "post_process_skill_content"+ ):+ skill_content = integration.post_process_skill_content(skill_content)if link_outputs:try:@@ -1178,6 +1178,7 @@ class ExtensionManager:continuetry:import yaml as _yaml+raw = skill_md.read_text(encoding="utf-8")source = ""if raw.startswith("---"):@@ -1202,7 +1203,9 @@ class ExtensionManager:for cfg in AGENT_CONFIG.values():folder = cfg.get("folder", "")if folder:- candidate_dirs.add(self.project_root / folder.rstrip("/") / "skills")+ candidate_dirs.add(+ self.project_root / folder.rstrip("/") / "skills"+ )candidate_dirs.add(self.project_root / DEFAULT_SKILLS_DIR)for skills_candidate in candidate_dirs:@@ -1215,7 +1218,9 @@ class ExtensionManager:continuetry:skill_subdir = (skills_candidate / skill_name).resolve()- skill_subdir.relative_to(skills_candidate.resolve()) # raises if outside+ skill_subdir.relative_to(+ skills_candidate.resolve()+ ) # raises if outsideexcept (OSError, ValueError):continueif not skill_subdir.is_dir():@@ -1229,6 +1234,7 @@ class ExtensionManager:continuetry:import yaml as _yaml+raw = skill_md.read_text(encoding="utf-8")source = ""if raw.startswith("---"):@@ -1249,9 +1255,7 @@ class ExtensionManager:shutil.rmtree(skill_subdir)def check_compatibility(- self,- manifest: ExtensionManifest,- speckit_version: str+ self, manifest: ExtensionManifest, speckit_version: str) -> bool:"""Check if extension is compatible with current spec-kit version.@@ -1393,9 +1397,13 @@ class ExtensionManager:backup_config_dir.unlink()elif backup_config_dir.is_dir():for cfg_file in backup_config_dir.iterdir():- if cfg_file.is_file() and not cfg_file.is_symlink() and (- cfg_file.name.endswith("-config.yml") or- cfg_file.name.endswith("-config.local.yml")+ if (+ cfg_file.is_file()+ and not cfg_file.is_symlink()+ and (+ cfg_file.name.endswith("-config.yml")+ or cfg_file.name.endswith("-config.local.yml")+ )):shutil.copy2(cfg_file, dest_dir / cfg_file.name)shutil.rmtree(backup_config_dir)@@ -1403,15 +1411,18 @@ class ExtensionManager:backup_config_dir.unlink()# Update registry- self.registry.add(manifest.id, {- "version": manifest.version,- "source": "local",- "manifest_hash": manifest.get_hash(),- "enabled": True,- "priority": priority,- "registered_commands": registered_commands,- "registered_skills": registered_skills,- })+ self.registry.add(+ manifest.id,+ {+ "version": manifest.version,+ "source": "local",+ "manifest_hash": manifest.get_hash(),+ "enabled": True,+ "priority": priority,+ "registered_commands": registered_commands,+ "registered_skills": registered_skills,+ },+ )return manifest@@ -1446,7 +1457,7 @@ class ExtensionManager:temp_path = Path(tmpdir)# Extract ZIP safely (prevent Zip Slip attack)- with zipfile.ZipFile(zip_path, 'r') as zf:+ with zipfile.ZipFile(zip_path, "r") as zf:# Validate all paths first before extracting anythingtemp_path_resolved = temp_path.resolve()for member in zf.namelist():@@ -1495,7 +1506,9 @@ class ExtensionManager:# Get registered commands and skills before removalmetadata = self.registry.get(extension_id)- registered_commands = metadata.get("registered_commands", {}) if metadata else {}+ registered_commands = (+ metadata.get("registered_commands", {}) if metadata else {}+ )raw_skills = metadata.get("registered_skills", []) if metadata else []# Normalize: must be a list of plain strings to avoid corrupted-registry errorsif isinstance(raw_skills, list):@@ -1519,8 +1532,8 @@ class ExtensionManager:for child in extension_dir.iterdir():# Keep top-level *-config.yml and *-config.local.yml filesif child.is_file() and (- child.name.endswith("-config.yml") or- child.name.endswith("-config.local.yml")+ child.name.endswith("-config.yml")+ or child.name.endswith("-config.local.yml")):continueif child.is_dir():@@ -1592,16 +1605,25 @@ class ExtensionManager:updates: Dict[str, Any] = {}registered_commands = metadata.get("registered_commands", {})- if isinstance(registered_commands, dict) and agent_name in registered_commands:- command_names = self._valid_name_list(registered_commands.get(agent_name))+ if (+ isinstance(registered_commands, dict)+ and agent_name in registered_commands+ ):+ command_names = self._valid_name_list(+ registered_commands.get(agent_name)+ )if command_names:- registrar.unregister_commands({agent_name: command_names}, self.project_root)+ registrar.unregister_commands(+ {agent_name: command_names}, self.project_root+ )new_registered = copy.deepcopy(registered_commands)new_registered.pop(agent_name, None)updates["registered_commands"] = new_registered- registered_skills = self._valid_name_list(metadata.get("registered_skills", []))+ registered_skills = self._valid_name_list(+ metadata.get("registered_skills", [])+ )if registered_skills:# Only pass the resolved skills_dir when it actually exists.# Otherwise let _unregister_extension_skills fall back to@@ -1700,7 +1722,9 @@ class ExtensionManager:registered_skills = self._register_extension_skills(manifest, ext_dir)if registered_skills:- existing_skills = self._valid_name_list(metadata.get("registered_skills", []))+ existing_skills = self._valid_name_list(+ metadata.get("registered_skills", [])+ )merged_skills = list(dict.fromkeys(existing_skills + registered_skills))updates["registered_skills"] = merged_skills@@ -1724,30 +1748,34 @@ class ExtensionManager:try:manifest = ExtensionManifest(manifest_path)- result.append({- "id": ext_id,- "name": manifest.name,- "version": metadata.get("version", "unknown"),- "description": manifest.description,- "enabled": metadata.get("enabled", True),- "priority": normalize_priority(metadata.get("priority")),- "installed_at": metadata.get("installed_at"),- "command_count": len(manifest.commands),- "hook_count": len(manifest.hooks)- })+ result.append(+ {+ "id": ext_id,+ "name": manifest.name,+ "version": metadata.get("version", "unknown"),+ "description": manifest.description,+ "enabled": metadata.get("enabled", True),+ "priority": normalize_priority(metadata.get("priority")),+ "installed_at": metadata.get("installed_at"),+ "command_count": len(manifest.commands),+ "hook_count": len(manifest.hooks),+ }+ )except ValidationError:# Corrupted extension- result.append({- "id": ext_id,- "name": ext_id,- "version": metadata.get("version", "unknown"),- "description": "β οΈ Corrupted extension",- "enabled": False,- "priority": normalize_priority(metadata.get("priority")),- "installed_at": metadata.get("installed_at"),- "command_count": 0,- "hook_count": 0- })+ result.append(+ {+ "id": ext_id,+ "name": ext_id,+ "version": metadata.get("version", "unknown"),+ "description": "β οΈ Corrupted extension",+ "enabled": False,+ "priority": normalize_priority(metadata.get("priority")),+ "installed_at": metadata.get("installed_at"),+ "command_count": 0,+ "hook_count": 0,+ }+ )return result@@ -1800,37 +1828,46 @@ class CommandRegistrar:# Re-export AGENT_CONFIGS at class level for direct attribute accessfrom .agents import CommandRegistrar as _AgentRegistrar+AGENT_CONFIGS = _AgentRegistrar.AGENT_CONFIGSdef __init__(self):from .agents import CommandRegistrar as _Registrar+self._registrar = _Registrar()# Delegate static/utility methods@staticmethoddef parse_frontmatter(content: str) -> tuple[dict, str]:from .agents import CommandRegistrar as _Registrar+return _Registrar.parse_frontmatter(content)@staticmethoddef render_frontmatter(fm: dict) -> str:from .agents import CommandRegistrar as _Registrar+return _Registrar.render_frontmatter(fm)@staticmethoddef _write_copilot_prompt(project_root, cmd_name: str) -> None:from .agents import CommandRegistrar as _Registrar+_Registrar.write_copilot_prompt(project_root, cmd_name)def _render_markdown_command(self, frontmatter, body, ext_id):# Preserve extension-specific comment format for backward compatibilitycontext_note = f"\n<!-- Extension: {ext_id} -->\n<!-- Config: .specify/extensions/{ext_id}/ -->\n"- return self._registrar.render_frontmatter(frontmatter) + "\n" + context_note + body+ return (+ self._registrar.render_frontmatter(frontmatter) + "\n" + context_note + body+ )def _render_toml_command(self, frontmatter, body, ext_id):# Preserve extension-specific context comments for backward compatibilitybase = self._registrar.render_toml_command(frontmatter, body, ext_id)- context_lines = f"# Extension: {ext_id}\n# Config: .specify/extensions/{ext_id}/\n"+ context_lines = (+ f"# Extension: {ext_id}\n# Config: .specify/extensions/{ext_id}/\n"+ )return base.rstrip("\n") + "\n" + context_linesdef register_commands_for_agent(@@ -1846,7 +1883,11 @@ class CommandRegistrar:raise ExtensionError(f"Unsupported agent: {agent_name}")context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"return self._registrar.register_commands(- agent_name, manifest.commands, manifest.id, extension_dir, project_root,+ agent_name,+ manifest.commands,+ manifest.id,+ extension_dir,+ project_root,context_note=context_note,link_outputs=link_outputs,)@@ -1862,16 +1903,17 @@ class CommandRegistrar:"""Register extension commands for all detected agents."""context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"return self._registrar.register_commands_for_all_agents(- manifest.commands, manifest.id, extension_dir, project_root,+ manifest.commands,+ manifest.id,+ extension_dir,+ project_root,context_note=context_note,link_outputs=link_outputs,create_missing_active_skills_dir=create_missing_active_skills_dir,)def unregister_commands(- self,- registered_commands: Dict[str, List[str]],- project_root: Path+ self, registered_commands: Dict[str, List[str]], project_root: Path) -> None:"""Remove previously registered command files from agent directories."""self._registrar.unregister_commands(registered_commands, project_root)@@ -1892,7 +1934,9 @@ class CommandRegistrar:class ExtensionCatalog(CatalogStackBase):"""Manages extension catalog fetching, caching, and searching."""- DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"+ DEFAULT_CATALOG_URL = (+ "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"+ )COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"CACHE_DURATION = 3600 # 1 hour in secondsCONFIG_FILENAME = "extension-catalogs.yml"@@ -1918,6 +1962,7 @@ class ExtensionCatalog(CatalogStackBase):Delegates to :func:`specify_cli.authentication.http.build_request`."""from specify_cli.authentication.http import build_request+return build_request(url)def _open_url(@@ -1931,6 +1976,7 @@ class ExtensionCatalog(CatalogStackBase):Delegates to :func:`specify_cli.authentication.http.open_url`."""from specify_cli.authentication.http import open_url+return open_url(url, timeout, extra_headers=extra_headers)def _resolve_github_release_asset_api_url(@@ -1982,8 +2028,7 @@ class ExtensionCatalog(CatalogStackBase):raise ExtensionError(f"Invalid catalog format from {url}")if not isinstance(catalog_data.get("extensions"), dict):raise ExtensionError(- f"Invalid catalog format from {url}: "- "'extensions' must be a JSON object"+ f"Invalid catalog format from {url}: 'extensions' must be a JSON object")def get_active_catalogs(self) -> List[CatalogEntry]:@@ -2070,7 +2115,9 @@ class ExtensionCatalog(CatalogStackBase):active = self.get_active_catalogs()return active[0].url if active else self.DEFAULT_CATALOG_URL- def _fetch_single_catalog(self, entry: CatalogEntry, force_refresh: bool = False) -> Dict[str, Any]:+ def _fetch_single_catalog(+ self, entry: CatalogEntry, force_refresh: bool = False+ ) -> Dict[str, Any]:"""Fetch a single catalog with per-URL caching.For the DEFAULT_CATALOG_URL, uses legacy cache files (self.cache_file /@@ -2101,9 +2148,7 @@ class ExtensionCatalog(CatalogStackBase):is_valid = Falseif not force_refresh and cache_file.exists() and cache_meta_file.exists():try:- metadata = json.loads(- cache_meta_file.read_text(encoding="utf-8")- )+ metadata = json.loads(cache_meta_file.read_text(encoding="utf-8"))cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))if cached_at.tzinfo is None:cached_at = cached_at.replace(tzinfo=timezone.utc)@@ -2171,10 +2216,13 @@ class ExtensionCatalog(CatalogStackBase):json.dumps(catalog_data, indent=2), encoding="utf-8")cache_meta_file.write_text(- json.dumps({- "cached_at": datetime.now(timezone.utc).isoformat(),- "catalog_url": entry.url,- }, indent=2),+ json.dumps(+ {+ "cached_at": datetime.now(timezone.utc).isoformat(),+ "catalog_url": entry.url,+ },+ indent=2,+ ),encoding="utf-8",)except OSError:@@ -2187,7 +2235,9 @@ class ExtensionCatalog(CatalogStackBase):except json.JSONDecodeError as e:raise ExtensionError(f"Invalid JSON in catalog from {entry.url}: {e}")- def _get_merged_extensions(self, force_refresh: bool = False) -> List[Dict[str, Any]]:+ def _get_merged_extensions(+ self, force_refresh: bool = False+ ) -> List[Dict[str, Any]]:"""Fetch and merge extensions from all active catalogs.Higher-priority (lower priority number) catalogs win on conflicts@@ -2264,9 +2314,7 @@ class ExtensionCatalog(CatalogStackBase):return Falsetry:- metadata = json.loads(- self.cache_metadata_file.read_text(encoding="utf-8")- )+ metadata = json.loads(self.cache_metadata_file.read_text(encoding="utf-8"))cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))if cached_at.tzinfo is None:cached_at = cached_at.replace(tzinfo=timezone.utc)@@ -2437,7 +2485,9 @@ class ExtensionCatalog(CatalogStackBase):return ext_datareturn None- def download_extension(self, extension_id: str, target_dir: Optional[Path] = None) -> Path:+ def download_extension(+ self, extension_id: str, target_dir: Optional[Path] = None+ ) -> Path:"""Download extension ZIP from catalog.Args:@@ -2471,6 +2521,7 @@ class ExtensionCatalog(CatalogStackBase):# Validate download URL requires HTTPS (prevent man-in-the-middle attacks)from urllib.parse import urlparse+parsed = urlparse(download_url)is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):@@ -2495,14 +2546,18 @@ class ExtensionCatalog(CatalogStackBase):# Download the ZIP filetry:- with self._open_url(download_url, timeout=60, extra_headers=extra_headers) as response:+ with self._open_url(+ download_url, timeout=60, extra_headers=extra_headers+ ) as response:zip_data = response.read()zip_path.write_bytes(zip_data)return zip_pathexcept urllib.error.URLError as e:- raise ExtensionError(f"Failed to download extension from {download_url}: {e}")+ raise ExtensionError(+ f"Failed to download extension from {download_url}: {e}"+ )except IOError as e:raise ExtensionError(f"Failed to save extension ZIP: {e}")@@ -2614,7 +2669,7 @@ class ConfigManager:continue# Remove prefix and split into parts- config_path = key[len(prefix):].lower().split("_")+ config_path = key[len(prefix) :].lower().split("_")# Build nested dictcurrent = env_config@@ -2628,7 +2683,9 @@ class ConfigManager:return env_config- def _merge_configs(self, base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:+ def _merge_configs(+ self, base: Dict[str, Any], override: Dict[str, Any]+ ) -> Dict[str, Any]:"""Recursively merge two configuration dictionaries.Args:@@ -2641,7 +2698,11 @@ class ConfigManager:result = base.copy()for key, value in override.items():- if key in result and isinstance(result[key], dict) and isinstance(value, dict):+ if (+ key in result+ and isinstance(result[key], dict)+ and isinstance(value, dict)+ ):# Recursive merge for nested dictsresult[key] = self._merge_configs(result[key], value)else:@@ -2755,7 +2816,7 @@ class HookExecutor:command_id = command.strip()if not command_id.startswith("speckit."):return ""- return f"speckit-{command_id[len('speckit.'):].replace('.', '-')}"+ return f"speckit-{command_id[len('speckit.') :].replace('.', '-')}"def _render_hook_invocation(self, command: Any) -> str:"""Render an agent-specific invocation string for a hook command."""@@ -2769,26 +2830,26 @@ class HookExecutor:init_options = self._load_init_options()selected_ai = init_options.get("ai")ai_skills_enabled = is_ai_skills_enabled(init_options)+codex_skill_mode = selected_ai == "codex" and ai_skills_enabled- claude_skill_mode = selected_ai == "claude" and ai_skills_enabledkimi_skill_mode = selected_ai == "kimi"- cursor_skill_mode = selected_ai == "cursor-agent" and ai_skills_enabledcline_mode = selected_ai == "cline"skill_name = self._skill_name_from_command(command_id)if codex_skill_mode and skill_name:return f"${skill_name}"- if claude_skill_mode and skill_name:- return f"/{skill_name}"if kimi_skill_mode and skill_name:return f"/skill:{skill_name}"- if cursor_skill_mode and skill_name:- return f"/{skill_name}"if cline_mode:from .integrations.cline import format_cline_command_namereturn f"/{format_cline_command_name(command_id)}"+ use_slash = is_slash_skills_agent(selected_ai, ai_skills_enabled)++ if skill_name and use_slash:+ return f"/{skill_name}"+return f"/{command_id}"def get_project_config(self) -> Dict[str, Any]:@@ -2829,7 +2890,9 @@ class HookExecutor:if not isinstance(event_val, list):result["hooks"][event_key] = []else:- result["hooks"][event_key] = [h for h in event_val if isinstance(h, dict)]+ result["hooks"][event_key] = [+ h for h in event_val if isinstance(h, dict)+ ]return resultexcept (yaml.YAMLError, OSError, UnicodeError):return {@@ -2846,7 +2909,9 @@ class HookExecutor:"""self.config_file.parent.mkdir(parents=True, exist_ok=True)self.config_file.write_text(- yaml.dump(config, default_flow_style=False, sort_keys=False, allow_unicode=True),+ yaml.dump(+ config, default_flow_style=False, sort_keys=False, allow_unicode=True+ ),encoding="utf-8",)@@ -2908,7 +2973,7 @@ class HookExecutor:Returns:A sanitized, deduplicated, alphabetically-sorted list."""- _VALID_ID = re.compile(r'^[a-z0-9-]+$')+ _VALID_ID = re.compile(r"^[a-z0-9-]+$")installed = raw if isinstance(raw, list) else []@@ -2984,7 +3049,8 @@ class HookExecutor:if h_name in declared_events:continuekept = [- h for h in config["hooks"][h_name]+ h+ for h in config["hooks"][h_name]if not (isinstance(h, dict) and h.get("extension") == manifest.id)]if kept != config["hooks"][h_name]:@@ -2993,7 +3059,9 @@ class HookExecutor:# Register each hookfor hook_name, hook_config in manifest.hooks.items():- if hook_name not in config["hooks"] or not isinstance(config["hooks"][hook_name], list):+ if hook_name not in config["hooks"] or not isinstance(+ config["hooks"][hook_name], list+ ):config["hooks"][hook_name] = []changed = True@@ -3026,7 +3094,8 @@ class HookExecutor:# then leaves no orphaned entries behind.original_list = config["hooks"][hook_name]deduped = [- h for h in original_list+ h+ for h in original_listif not (isinstance(h, dict) and h.get("extension") == manifest.id)]deduped.extend(new_entries.values())@@ -3146,7 +3215,9 @@ class HookExecutor:condition = condition.strip()# Pattern: "config.key.path is set"- if match := re.match(r'config\.([a-z0-9_.]+)\s+is\s+set', condition, re.IGNORECASE):+ if match := re.match(+ r"config\.([a-z0-9_.]+)\s+is\s+set", condition, re.IGNORECASE+ ):key_path = match.group(1)if not extension_id:return False@@ -3155,7 +3226,11 @@ class HookExecutor:return config_manager.has_value(key_path)# Pattern: "config.key.path == 'value'" or "config.key.path != 'value'"- if match := re.match(r'config\.([a-z0-9_.]+)\s*(==|!=)\s*["\']([^"\']+)["\']', condition, re.IGNORECASE):+ if match := re.match(+ r'config\.([a-z0-9_.]+)\s*(==|!=)\s*["\']([^"\']+)["\']',+ condition,+ re.IGNORECASE,+ ):key_path = match.group(1)operator = match.group(2)expected_value = match.group(3)@@ -3179,12 +3254,16 @@ class HookExecutor:return normalized_value != expected_value# Pattern: "env.VAR_NAME is set"- if match := re.match(r'env\.([A-Z0-9_]+)\s+is\s+set', condition, re.IGNORECASE):+ if match := re.match(r"env\.([A-Z0-9_]+)\s+is\s+set", condition, re.IGNORECASE):var_name = match.group(1).upper()return var_name in os.environ# Pattern: "env.VAR_NAME == 'value'" or "env.VAR_NAME != 'value'"- if match := re.match(r'env\.([A-Z0-9_]+)\s*(==|!=)\s*["\']([^"\']+)["\']', condition, re.IGNORECASE):+ if match := re.match(+ r'env\.([A-Z0-9_]+)\s*(==|!=)\s*["\']([^"\']+)["\']',+ condition,+ re.IGNORECASE,+ ):var_name = match.group(1).upper()operator = match.group(2)expected_value = match.group(3)@@ -3199,9 +3278,7 @@ class HookExecutor:# Unknown condition format, default to False for safetyreturn False- def format_hook_message(- self, event_name: str, hooks: List[Dict[str, Any]]- ) -> str:+ def format_hook_message(self, event_name: str, hooks: List[Dict[str, Any]]) -> str:"""Format hook execution message for display in command output.Args:@@ -3221,9 +3298,15 @@ class HookExecutor:extension = hook.get("extension")command = hook.get("command")invocation = self._render_hook_invocation(command)- command_text = command if isinstance(command, str) and command.strip() else "<missing command>"+ command_text = (+ command+ if isinstance(command, str) and command.strip()+ else "<missing command>"+ )display_invocation = invocation or (- f"/{command_text}" if command_text != "<missing command>" else "/<missing command>"+ f"/{command_text}"+ if command_text != "<missing command>"+ else "/<missing command>")optional = hook.get("optional", True)prompt = hook.get("prompt", "")@@ -3261,11 +3344,7 @@ class HookExecutor:hooks = self.get_hooks_for_event(event_name)if not hooks:- return {- "has_hooks": False,- "hooks": [],- "message": ""- }+ return {"has_hooks": False, "hooks": [], "message": ""}# Filter hooks by conditionexecutable_hooks = []@@ -3277,13 +3356,13 @@ class HookExecutor:return {"has_hooks": False,"hooks": [],- "message": f"# No executable hooks for event '{event_name}' (conditions not met)"+ "message": f"# No executable hooks for event '{event_name}' (conditions not met)",}return {"has_hooks": True,"hooks": executable_hooks,- "message": self.format_hook_message(event_name, executable_hooks)+ "message": self.format_hook_message(event_name, executable_hooks),}def execute_hook(self, hook: Dict[str, Any]) -> Dict[str, Any]:@@ -3308,7 +3387,7 @@ class HookExecutor:"extension": hook.get("extension"),"optional": hook.get("optional", True),"description": hook.get("description", ""),- "prompt": hook.get("prompt", "")+ "prompt": hook.get("prompt", ""),}def enable_hooks(self, extension_id: str):diff --git a/src/specify_cli/integrations/__init__.py b/src/specify_cli/integrations/__init__.pyindex eae306575..07d3cc1a6 100644--- a/src/specify_cli/integrations/__init__.py+++ b/src/specify_cli/integrations/__init__.py@@ -80,6 +80,7 @@ def _register_builtins() -> None:from .trae import TraeIntegrationfrom .vibe import VibeIntegrationfrom .windsurf import WindsurfIntegration+ from .zed import ZedIntegration# -- Registration (alphabetical) --------------------------------------_register(AgyIntegration())@@ -115,6 +116,7 @@ def _register_builtins() -> None:_register(TraeIntegration())_register(VibeIntegration())_register(WindsurfIntegration())+ _register(ZedIntegration())_register_builtins()diff --git a/src/specify_cli/integrations/zed/__init__.py b/src/specify_cli/integrations/zed/__init__.pynew file mode 100644index 000000000..882d83cc5--- /dev/null+++ b/src/specify_cli/integrations/zed/__init__.py@@ -0,0 +1,34 @@+"""Zed editor integration β skills-based agent.++Zed uses the ``.agents/skills/speckit-<name>/SKILL.md`` layout so Spec Kit+commands are exposed as project-local skills that can be invoked from Zed's+slash-command menu.+"""++from __future__ import annotations++from ..base import IntegrationOption, SkillsIntegration+++class ZedIntegration(SkillsIntegration):+ """Integration for Zed editor skills."""++ key = "zed"+ config = {+ "name": "Zed",+ "folder": ".agents/",+ "commands_subdir": "skills",+ "install_url": None,+ "requires_cli": False,+ }+ registrar_config = {+ "dir": ".agents/skills",+ "format": "markdown",+ "args": "$ARGUMENTS",+ "extension": "/SKILL.md",+ }+ context_file = "AGENTS.md"++ @classmethod+ def options(cls) -> list[IntegrationOption]:+ return []diff --git a/tests/integrations/test_integration_subcommand.py b/tests/integrations/test_integration_subcommand.pyindex 4c09a9163..b62f06e82 100644--- a/tests/integrations/test_integration_subcommand.py+++ b/tests/integrations/test_integration_subcommand.py@@ -120,6 +120,7 @@ class TestIntegrationList:# Should show multiple integrationsassert "claude" in result.outputassert "gemini" in result.output+ assert "zed" in result.outputdef test_list_shows_multi_install_safe_status(self, tmp_path):project = _init_project(tmp_path, "claude")diff --git a/tests/integrations/test_integration_zed.py b/tests/integrations/test_integration_zed.pynew file mode 100644index 000000000..0172e6b27--- /dev/null+++ b/tests/integrations/test_integration_zed.py@@ -0,0 +1,164 @@+"""Tests for ZedIntegration."""++import json++import pytest++from specify_cli.integrations import get_integration++from .test_integration_base_skills import SkillsIntegrationTests+++class TestZedIntegration(SkillsIntegrationTests):+ KEY = "zed"+ FOLDER = ".agents/"+ COMMANDS_SUBDIR = "skills"+ REGISTRAR_DIR = ".agents/skills"+ CONTEXT_FILE = "AGENTS.md"++ def test_options_include_skills_flag(self):+ """Not applicable to Zed β Zed is always skills-based with no --skills flag."""+ pytest.skip("Zed is always skills-based and does not expose a --skills option")++ def test_options_do_not_include_skills_flag(self):+ """Zed is always skills-based; no --skills option is exposed."""+ i = get_integration(self.KEY)+ assert i is not None+ opts = i.options()+ skills_opts = [o for o in opts if o.name == "--skills"]+ assert len(skills_opts) == 0, (+ "Zed is always skills-based and should not expose a --skills option"+ )++ def test_requires_cli_is_false(self):+ """Zed is IDE-based; requires_cli must remain False."""+ i = get_integration(self.KEY)+ assert i is not None+ assert i.config is not None+ assert i.config["requires_cli"] is False+++class TestZedHookInvocations:+ """Zed hook messages should reference slash-invokable skills."""++ def test_hooks_render_skill_invocation(self, tmp_path):+ """Zed is always skills-based: renders /speckit-plan even with ai_skills=False."""+ from specify_cli.extensions import HookExecutor++ project = tmp_path / "zed-hooks"+ project.mkdir()+ init_options = project / ".specify" / "init-options.json"+ init_options.parent.mkdir(parents=True, exist_ok=True)+ init_options.write_text(json.dumps({"ai": "zed", "ai_skills": False}))++ hook_executor = HookExecutor(project)+ message = hook_executor.format_hook_message(+ "before_plan",+ [+ {+ "extension": "test-ext",+ "command": "speckit.plan",+ "optional": False,+ }+ ],+ )++ assert "EXECUTE_COMMAND_INVOCATION: /speckit-plan" in message++ def test_init_persists_ai_skills_for_zed(self, tmp_path, monkeypatch):+ """specify init --integration zed must persist ai_skills: true,+ so HookExecutor renders slash-skill invocations without manual+ init-options manipulation."""+ from typer.testing import CliRunner++ from specify_cli import app+ from specify_cli.extensions import HookExecutor++ project = tmp_path / "zed-init-test"+ project.mkdir()+ monkeypatch.chdir(project)+ runner = CliRunner()+ result = runner.invoke(+ app,+ [+ "init",+ "--here",+ "--integration",+ "zed",+ "--script",+ "sh",+ "--ignore-agent-tools",+ ],+ catch_exceptions=False,+ )++ assert result.exit_code == 0, f"init failed: {result.output}"++ opts_path = project / ".specify" / "init-options.json"+ assert opts_path.exists()+ opts = json.loads(opts_path.read_text(encoding="utf-8"))+ assert opts.get("ai") == "zed"+ assert opts.get("ai_skills") is True, (+ f"init must persist ai_skills=true for Zed, got: {opts.get('ai_skills')}"+ )++ hook_executor = HookExecutor(project)+ message = hook_executor.format_hook_message(+ "before_plan",+ [+ {+ "extension": "test-ext",+ "command": "speckit.plan",+ "optional": False,+ }+ ],+ )+ assert "Executing: `/speckit-plan`" in message, (+ "Hook rendering must produce /speckit-plan for Zed without hint injection"+ )+ assert "EXECUTE_COMMAND_INVOCATION: /speckit-plan" in message+++class TestSlashSkillsSets:+ """Parameterized coverage for ALWAYS_SLASH_AGENTS / CONDITIONAL_SLASH_AGENTS."""++ @staticmethod+ def _render_invocation(project_path, ai: str, ai_skills: bool) -> str:+ """Return the rendered invocation for ``speckit.plan`` via HookExecutor."""+ from specify_cli.extensions import HookExecutor++ init_options = project_path / ".specify" / "init-options.json"+ init_options.parent.mkdir(parents=True, exist_ok=True)+ init_options.write_text(json.dumps({"ai": ai, "ai_skills": ai_skills}))+ hook_executor = HookExecutor(project_path)+ result = hook_executor.execute_hook(+ {"extension": "test-ext", "command": "speckit.plan", "optional": False}+ )+ return result.get("invocation", "")++ @pytest.mark.parametrize(+ ("ai", "ai_skills", "expected"),+ [+ # ALWAYS_SLASH_AGENTS β unconditional on ai_skills+ ("devin", True, "/speckit-plan"),+ ("devin", False, "/speckit-plan"),+ ("trae", True, "/speckit-plan"),+ ("trae", False, "/speckit-plan"),+ ("zed", True, "/speckit-plan"),+ ("zed", False, "/speckit-plan"),+ # CONDITIONAL_SLASH_AGENTS β only when ai_skills is enabled+ ("agy", True, "/speckit-plan"),+ ("agy", False, "/speckit.plan"),+ ("claude", True, "/speckit-plan"),+ ("claude", False, "/speckit.plan"),+ ("copilot", True, "/speckit-plan"),+ ("copilot", False, "/speckit.plan"),+ ("cursor-agent", True, "/speckit-plan"),+ ("cursor-agent", False, "/speckit.plan"),+ ],+ )+ def test_hook_invocation_format(self, tmp_path, ai, ai_skills, expected):+ result = self._render_invocation(tmp_path, ai, ai_skills)+ assert result == expected, (+ f"{ai} (ai_skills={ai_skills}): expected {expected!r}, got {result!r}"+ )diff --git a/tests/integrations/test_registry.py b/tests/integrations/test_registry.pyindex 08bf0ba8f..7582bd671 100644--- a/tests/integrations/test_registry.py+++ b/tests/integrations/test_registry.py@@ -27,7 +27,7 @@ ALL_INTEGRATION_KEYS = [# Stage 4 β TOML integrations"gemini", "tabnine",# Stage 5 β skills, generic & option-driven integrations- "codex", "kimi", "agy", "generic",+ "codex", "kimi", "agy", "zed", "generic",]