github/github-spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-07-03 12:28:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add Zed integration (#2780)

Browse Source 
* feat: add Zed integration

* fix: update integrations stats grid to 31 for consistency

* fix: address Copilot review feedback

- Remove non-actionable --skills flag from ZedIntegration (Zed is always
  skills-based, like Agy)
- Align zed_skill_mode predicate with ai_skills for consistency across
  init output and hook rendering
- Consolidate claude/cursor/zed slash-skill return blocks in
  _render_hook_invocation to reduce duplication
- Override test_options_include_skills_flag for Zed (no --skills flag)

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix: address Copilot review round 2

- Make zed_skill_mode unconditional in hook rendering (Zed is always
  skills-based, no --skills option)
- Add test_init_persists_ai_skills_for_zed that exercises the actual
  CLI init path and verifies HookExecutor renders /speckit-plan
  without manual init-options manipulation

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix: address copilot review feedback for zed integration

- Update integration count from 31 to 33 in docs/index.md (32 integrations + Generic)
- Make zed_skill_mode unconditional to match extensions.py behavior
- Consolidate slash-skill integrations into a set for consistency
- Move os import to module level in test_integration_zed.py

* fix: refine slash-skill logic and ai-skills validation

- Fix slash-skill integrations: Claude/Cursor require ai_skills=true; Zed/Agy/Devin are always skills
- Allow --ai-skills with --integration (not just --ai) to fix validation error

* fix: remove unused variables and update ai-skills help text

- Add agy_skill_mode and devin_skill_mode variables to fix F841 lint error
- Use all skill mode variables in the slash-skill conditional check
- Update --ai-skills help text to reflect it works with --integration too

* fix: add trae_skill_mode to hook invocation for consistency

Trae is a SkillsIntegration like Zed/Agy/Devin, so it should also be treated
as always-skills-based in hook invocation rendering.

* fix: make Agy always skills-based for consistency

AgyIntegration is a SkillsIntegration subclass with no --skills option,
so it should be treated as always skills-based (like Zed, Devin, Trae).
This aligns init.py skill mode detection with extensions.py hook rendering.

* fix: gate agy_skill_mode and refactor _render_hook_invocation to use sets

Addressed Copilot review comments:

- Restored _is_skills_integration guard on agy_skill_mode in init.py
  to be defensive about runtime integration type.
- Refactored _render_hook_invocation() in extensions.py to use
  always_slash/conditional_slash frozensets instead of individual
  per-agent booleans, eliminating unused variables (F841) and making
  it harder for conditions to drift between integrations.
- Centralized slash-skill determination so adding a new unconditional
  slash-skill integration is a one-key addition.

* fix: address latest Copilot review comments

- Added copilot to CONDITIONAL_SLASH_AGENTS for consistent
  hook invocation rendering with init.py
- Moved always_slash/conditional_slash frozensets to module
  scope to avoid per-call reallocation
- Replaced manual os.chdir() with monkeypatch.chdir() in test
- Overrode test_options_include_skills_flag for Zed (no --skills)

* fix: address latest Copilot review comments

- Removed redundant local import yaml in _register_extension_skills
  (yaml is already imported at module scope)
- Split --ai-skills usage hint into two separate print statements
  for better readability
- Changed integrations count from '33' to '30+' to avoid future drift

* fix: re-add _is_skills_integration definition lost in merge

The _is_skills_integration variable was accidentally dropped during the
web UI merge resolution of upstream/main's removal of legacy --ai flags.
Re-added the definition via isinstance(resolved_integration, SkillsIntegration)
check so that skill-mode booleans work correctly.

* fix: gate zed_skill_mode on _is_skills_integration for consistency

Aligns zed_skill_mode with the other skills-based agents (codex, claude,
cursor-agent, copilot) which all use _is_skills_integration gating.
Since ZedIntegration extends SkillsIntegration, behavior is unchanged.

* fix: remove unused claude_skill_mode and cursor_skill_mode locals in _render_hook_invocation

These variables became unused after the refactor to ALWAYS_SLASH_AGENTS /
CONDITIONAL_SLASH_AGENTS sets. Claude and Cursor-Agent are now handled by the
CONDITIONAL_SLASH_AGENTS path, so the separate boolean locals are dead code.

Fixes ruff F841 and addresses Copilot review feedback that was repeated across
multiple review rounds.

* fix: align agy/trae invocation format in init next-steps with hook rendering and build_command_invocation

- Moved agy and trae from '-<name>' (dollar/Codex format) to
  '/speckit-<name>' (slash format) in _display_cmd() to match:
  - HookExecutor._render_hook_invocation() (ALWAYS_SLASH_AGENTS for trae,
    CONDITIONAL_SLASH_AGENTS for agy)
  - SkillsIntegration.build_command_invocation() (default: /speckit-<name>)
- The '$' prefix is specific to Codex; all other skills agents use '/'.

* fix: address Copilot review comments on hook invocation consistency

- Add is_slash_skills_agent() helper to extensions.py to centralize the
  agent-to-invocation-format mapping, reducing drift risk between
  HookExecutor._render_hook_invocation() and init.py _display_cmd()
- Use the shared helper in both locations; init.py now imports and
  delegates to is_slash_skills_agent() instead of maintaining its own
  per-agent boolean matrix
- Fix test_hooks_render_skill_invocation to use ai_skills=False,
  proving Zed renders /speckit-<name> unconditionally
- Add parameterized TestSlashSkillsSets covering all agents in
  ALWAYS_SLASH_AGENTS and CONDITIONAL_SLASH_AGENTS with ai_skills
  both true and false

* fix: address Copilot review comments on type safety and test API

- Make is_slash_skills_agent() accept str | None to match its call sites
  (init_options.get("ai") can return None)
- Refactor TestSlashSkillsSets to use public execute_hook() API instead of
  private _render_hook_invocation() method

* fix: address Copilot review comments on typing and naming clarity

- Add from __future__ import annotations to extensions.py so PEP 604
  unions (str | None) are safe regardless of Python version
- Add clarifying _ai_skills_enabled local variable in init.py's
  _display_cmd() to make the semantic meaning explicit when passing it
  to is_slash_skills_agent()

* fix: move invocation-style logic into shared _invocation_style module

- Extract ALWAYS_SLASH_AGENTS, CONDITIONAL_SLASH_AGENTS, and
  is_slash_skills_agent() from extensions.py into new _invocation_style.py
  module, eliminating the awkward init.py -> extensions.py import
  dependency for invocation-style decision logic
- Both HookExecutor._render_hook_invocation() and init.py _display_cmd()
  now import from the shared module instead of one subsystem importing
  from the other
- Revert /SKILL.md change: the leading slash is semantically significant
  (path component vs filename suffix)

* fix: add None guard before i.options() in test_options_include_skills_flag

get_integration() returns IntegrationBase | None, so i.options()
is a type error without a None check.

* fix: override test_options_include_skills_flag for Zed (always skills, no --skills flag)

Zed is always skills-based and doesn't expose a --skills option.
Override the inherited base test to assert --skills is absent.

* fix: rename test and skip inherited test_options_include_skills_flag for Zed

- Skip inherited test_options_include_skills_flag (not applicable — Zed
  is always skills-based with no --skills flag)
- Add test_options_do_not_include_skills_flag with correct name matching
  the assertion (--skills is absent)

* fix: add defensive non-string check in is_slash_skills_agent

Reject non-string values for selected_ai to prevent TypeError from
set membership checks when persisted init-options contain corrupted
data (e.g. list or dict instead of string).

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Ahmet TOK
2026-06-17 01:29:08 +03:00
committed by GitHub
parent 0fad994e86
commit 1150d32aee
10 changed files with 798 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/index.md
View File

@@ -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>&nbsp;
<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">

1
docs/reference/integrations.md
View File

@@ -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 Integrations

45
src/specify_cli/_invocation_style.py Normal file
View File

@@ -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
)

382
src/specify_cli/commands/init.py
View File

@@ -1,4 +1,5 @@
"""specify init command."""
from __future__ import annotations
import 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_setting
show_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 = None
if 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 = False
if 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 = integration
elif 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_type
else:
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 WorkflowRegistry
from ..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"] = True
save_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 = None
try:
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:
raise
except 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 = 2
else:
steps_lines.append("1. You're already in the project directory!")
step_num = 2
from ..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_integration
claude_skill_mode = selected_ai == "claude" and _is_skills_integration
kimi_skill_mode = selected_ai == "kimi"
agy_skill_mode = selected_ai == "agy" and _is_skills_integration
trae_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_integration
devin_skill_mode = selected_ai == "devin"
zed_skill_mode = selected_ai == "zed" and _is_skills_integration
cline_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 += 1
if 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 += 1
if 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 += 1
if 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 += 1
usage_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)

423
src/specify_cli/extensions.py
View File

@@ -6,39 +6,44 @@ Extensions are modular packages that add commands and functionality to spec-kit
without bloating the core framework.
"""
import json
from __future__ import annotations
import copy
import hashlib
import json
import os
import re
import shutil
import tempfile
import zipfile
import shutil
import copy
from dataclasses import dataclass
from pathlib import Path
from typing import Optional, Dict, List, Any, Callable, Set
from datetime import datetime, timezone
import re
from pathlib import Path
from typing import Any, Callable, Dict, List, Optional, Set
import pathspec
import yaml
from packaging import version as pkg_version
from packaging.specifiers import SpecifierSet, InvalidSpecifier
from packaging.specifiers import InvalidSpecifier, SpecifierSet
from .catalogs import CatalogEntry as BaseCatalogEntry, CatalogStackBase
from ._init_options import is_ai_skills_enabled
from ._invocation_style import is_slash_skills_agent
from .catalogs import CatalogEntry as BaseCatalogEntry
from .catalogs import CatalogStackBase
_FALLBACK_CORE_COMMAND_NAMES = frozenset({
"analyze",
"clarify",
"constitution",
"implement",
"plan",
"checklist",
"specify",
"tasks",
"taskstoissues",
})
_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."""
pass
class ValidationError(ExtensionError):
"""Raised when extension manifest validation fails."""
pass
class 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 data
except (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):
continue
metadata_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_options
from .agents import CommandRegistrar
from .integrations import get_integration
import yaml
written: 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_name
if 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 name
short_name = cmd_name
if 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:
continue
try:
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:
continue
try:
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 outside
except (OSError, ValueError):
continue
if not skill_subdir.is_dir():
@@ -1229,6 +1234,7 @@ class ExtensionManager:
continue
try:
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 anything
temp_path_resolved = temp_path.resolve()
for member in zf.namelist():
@@ -1495,7 +1506,9 @@ class ExtensionManager:
# Get registered commands and skills before removal
metadata = 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 errors
if 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 files
if 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")
):
continue
if 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 access
from .agents import CommandRegistrar as _AgentRegistrar
AGENT_CONFIGS = _AgentRegistrar.AGENT_CONFIGS
def __init__(self):
from .agents import CommandRegistrar as _Registrar
self._registrar = _Registrar()
# Delegate static/utility methods
@staticmethod
def parse_frontmatter(content: str) -> tuple[dict, str]:
from .agents import CommandRegistrar as _Registrar
return _Registrar.parse_frontmatter(content)
@staticmethod
def render_frontmatter(fm: dict) -> str:
from .agents import CommandRegistrar as _Registrar
return _Registrar.render_frontmatter(fm)
@staticmethod
def _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 compatibility
context_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 compatibility
base = 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_lines
def 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 seconds
CONFIG_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 = False
if 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 False
try:
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_data
return 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 file
try:
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_path
except 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 dict
current = 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 dicts
result[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_enabled
kimi_skill_mode = selected_ai == "kimi"
cursor_skill_mode = selected_ai == "cursor-agent" and ai_skills_enabled
cline_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_name
return 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 result
except (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:
continue
kept = [
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 hook
for 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_list
if 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 safety
return 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 condition
executable_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):

2
src/specify_cli/integrations/__init__.py
View File

@@ -80,6 +80,7 @@ def _register_builtins() -> None:
from .trae import TraeIntegration
from .vibe import VibeIntegration
from .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()

34
src/specify_cli/integrations/zed/__init__.py Normal file
View File

@@ -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 []

1
tests/integrations/test_integration_subcommand.py
View File

@@ -120,6 +120,7 @@ class TestIntegrationList:
# Should show multiple integrations
assert "claude" in result.output
assert "gemini" in result.output
assert "zed" in result.output
def test_list_shows_multi_install_safe_status(self, tmp_path):
project = _init_project(tmp_path, "claude")

164
tests/integrations/test_integration_zed.py Normal file
View File

@@ -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}"
)

2
tests/integrations/test_registry.py
View File

@@ -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",
]