Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions design/extension.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,8 @@ archive extraction when applicable. The manager:
3. preserves eligible configuration before any destructive force reinstall;
4. copies the extension under `.specify/extensions/<id>/`, honoring
`.extensionignore`;
5. renders commands or skills for the active integration;
5. renders commands or skills for the active integration unless the caller
explicitly defers registration to a complete post-install refresh;
6. registers hooks and the installed projection in `extensions.yml`;
7. commits lifecycle and ownership metadata to `.registry`;
8. restores executable bits for project scripts.
Expand All @@ -200,6 +201,18 @@ manager step. `extension add`, `extension enable`, and bundle installation call
installation during `init` and extension update paths do not scaffold declared
configuration templates.

`extension add` defers artifact registration, commits installation, and calls the
integration domain refresh before reporting success. It refreshes shared assets
for the unchanged default and every recorded installed integration's managed
setup, including effective enabled extensions/presets, saved modes, settings,
and native events. Missing state or unavailable/untrusted adapters cannot be
replaced by directory detection or implicit consent. The add force flag authorizes
extension replacement, not overwriting unrelated customized integration files.
Failures retain the extension and completed refreshes and report explicit
completed/failed/unattempted state and recovery guidance, rather than success
after a warning. Shared manager callers such as init, update, and bundles do not
acquire this add-only policy.

Development installs may use symlinks to rendered caches where the selected
integration and platform support them. Integrations that prohibit such
symlinks receive ordinary files instead.
Expand All @@ -215,7 +228,8 @@ and skill files until an integration switch, uninstall, or other reconciliation
removes them, so those stale files may remain invocable while the extension is
disabled.

An extension install targets the active integration recorded in project state.
Outside the explicit `extension add` post-install refresh, extension registration
targets the active integration recorded in project state.
Projects predating that state may fall back to detected agent directories;
present but invalid active-integration state fails closed and registers no
agent outputs. Selecting, switching, upgrading, or removing integrations
Expand Down
8 changes: 6 additions & 2 deletions design/integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -485,8 +485,12 @@ The integration does **not** own agent context files such as `AGENTS.md` or
`CLAUDE.md`. The opt-in `extensions/agent-context/` owns their defaults,
configuration, and managed sections; do not add `context_file` fields or
context-file handling to the CLI. `specify init` does not enable the extension
implicitly. Extensions and presets register command or skill overrides for the
current default integration, not every installed integration.
implicitly. Successful `extension add` regenerates every recorded installed
integration's managed setup with its saved options, then layers enabled extension
and preset contributions. Shared assets stay aligned with the unchanged default.
The domain refresh preserves ownership and adapter consent and reports partial
failure without undoing completed refreshes. Other extension/preset lifecycle
operations retain their existing active-integration registration policy.

## Integration delivery boundary

Expand Down
6 changes: 4 additions & 2 deletions docs/how-to/customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,10 @@ The default replacement order is:
4. Spec Kit core templates in `.specify/templates/`.

Templates are resolved when needed, using the first match by default.
Commands are different: installing extensions or presets materializes command
files into the active integration's directory. Agents do not re-resolve that
Commands are different: successful extension addition materializes the effective
command stack for every recorded installed integration without changing the
default. Preset installation and other extension/preset lifecycle operations
retain active-integration registration. Agents do not re-resolve that
stack every time they invoke a command. Removing an overriding component
restores the surviving command layer through reconciliation.

Expand Down
6 changes: 6 additions & 0 deletions docs/integrations/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -300,10 +300,16 @@ Format bases implement setup and teardown. Custom layouts may override:
| `setup(project_root, manifest, parsed_options=None, **opts) -> list[Path]` | Write and record agent files; return created paths |
| `teardown(project_root, manifest, *, force=False) -> tuple[list[Path], list[Path]]` | Return removed and preserved paths; inherited behavior preserves modified files unless forced |
| `stale_cleanup_exclusions() -> set[str]` | Project-relative paths upgrade must not delete as stale |
| `mergeable_settings_paths() -> set[str]` | Settings with content-preserving integration mergers; does not authorize replacing generated files protected from stale deletion |

Call inherited behavior where appropriate and preserve host-supplied options,
including `script_type`, `events`, and `force`. Keep generated files under the
declared agent root; the host owns shared Spec Kit scripts and templates.
Extension-add refresh also supplies `strict=True`: required managed settings
that cannot be merged must fail rather than report readiness after a warning.
The default mergeable-settings paths include the native event configuration;
override `mergeable_settings_paths()` for additional content-preserving settings
mergers. Stale-cleanup exclusions alone do not authorize overwriting files.

The host supplies an `IntegrationManifest` to setup and teardown. For custom
writes, use these supported operations:
Expand Down
29 changes: 26 additions & 3 deletions docs/integrations/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,11 @@ remains discovery-only.

Installing an additional integration does not change the default integration. Use `specify integration use <key>` to change the default.

Extensions and presets follow the default integration only. Use `use <key>` or
`switch <key>` to activate another integration and register their commands for it.
Successful `extension add` refreshes every recorded installed integration,
including effective extension and preset commands, without changing the default.
Other extension and preset lifecycle operations retain default-integration
registration. Use `use <key>` or `switch <key>` to change the default and refresh
its commands.

### Catalog-installed external adapters

Expand Down Expand Up @@ -555,4 +558,24 @@ Use `upgrade` when you've upgraded Spec Kit and want to refresh an installed int

### Do extensions and presets I install apply to every installed integration?

No. Extensions (`specify extension add`) and presets (`specify preset add`) register their command overrides for the currently active (default) integration only, even if other integrations are installed. A non-default integration does not receive those artifacts until it becomes the default: `specify integration use <key>` (or `switch <key>`) rescaffolds every enabled extension and preset for the newly active integration. `specify integration upgrade` follows the same rule — it only re-registers extensions and presets when upgrading the active integration.
Successful `specify extension add` refreshes every integration recorded as installed,
using each integration's saved options and output mode. It regenerates core
commands/skills, enabled extension and preset contributions, managed settings and
native events, and shared templates/scripts aligned with the unchanged default.
Agent directories alone do not make an integration eligible. Regeneration is
local; it does not install agent CLIs, upgrade components, or grant adapter trust.
Comment on lines +561 to +566

Customized or unsafe outputs and unavailable/untrusted adapters cause a nonzero
result rather than a readiness claim. The extension and completed refreshes remain
installed; the command identifies completed, failed, and unattempted integrations.
Obsolete legacy invocation files without verifiable ownership require manual
reconciliation; registry names alone do not authorize deleting them.
Back up and reconcile reported conflicts, restore any required reviewed adapter,
then retry addition with the same source and `--force` to replace the retained
extension. That flag does not authorize overwriting customized integration files.

Preset addition alone still targets the current default. `specify integration use
<key>` (or `switch <key>`) refreshes enabled contributions for the newly active
integration; `specify integration upgrade` re-registers contributions only when
upgrading the active integration. Update, remove, enable/disable, and bundle
operations are not given the extension-add full-refresh guarantee.
4 changes: 4 additions & 0 deletions docs/integrations/copilot.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,10 @@ cannot be parsed as a JSON object, the merge is skipped with a warning and
manual instructions. An existing merged settings file is retained on uninstall;
a newly created settings file is manifest-tracked.

Extension addition is stricter: if the required settings cannot be merged,
`specify extension add` reports integration readiness failure and preserves the
existing settings. Reconcile the file before retrying the addition.

## Runtime Events and Workflow Permissions

Native events use `.github/hooks/speckit.json`.
Expand Down
10 changes: 5 additions & 5 deletions docs/integrations/generic.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,11 @@ does not add native command discovery to the agent.

## Extensions

Once `generic` is the active integration, `specify extension add` registers
extension commands in its configured `--commands-dir`, as command files or
skills according to `--skills`. `specify extension remove` removes unchanged
extension-owned artifacts while leaving core commands, user files, and edited
extension files intact.
When `generic` is recorded as installed, `specify extension add` registers
extension commands in its configured `--commands-dir`, even when it is not the
default integration, as command files or skills according to `--skills`.
`specify extension remove` removes unchanged extension-owned artifacts while
leaving core commands, user files, and edited extension files intact.

## Workflow Limitation

Expand Down
5 changes: 5 additions & 0 deletions docs/integrations/hermes.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ The optional `--integration-options="--skills"` flag restates the default.

Setup can replace another project's global Spec Kit skill files.

Extension addition is more conservative: it compares untracked global skills
against the fully regenerated content, preserving identical files and reporting
a readiness failure instead of overwriting differing content. Missing skills are
restored. The project default is unchanged.

**Uninstall removes every global `speckit-*` skill directory, even if edited
and even without `--force`.** These global files are not protected by the
project-local manifest's modified-file checks. Back up customizations before
Expand Down
11 changes: 11 additions & 0 deletions src/specify_cli/_init_options.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,11 @@ def save_init_options(project_path: Path, options: dict[str, Any]) -> None:

def load_init_options(project_path: Path) -> dict[str, Any]:
"""Load persisted init options, returning an empty dict when unavailable."""
from .integration_runtime import current_registration_options

scoped = current_registration_options(project_path)
if scoped is not None:
return scoped
path = project_path / INIT_OPTIONS_FILE
if not path.exists():
return {}
Expand Down Expand Up @@ -65,6 +70,12 @@ def resolve_active_agent_for_registration(
or pass a non-string key into agent-config lookups.
- Returns the active agent key (a non-empty string) otherwise.
"""
from .integration_runtime import current_registration_options

scoped = current_registration_options(project_path)
if scoped is not None:
active = scoped.get("ai")
return active if isinstance(active, str) and active else None
path = project_path / INIT_OPTIONS_FILE
# A dangling symlink's target doesn't exist, so Path.exists() (which
# follows symlinks) returns False even though the path itself is
Expand Down
12 changes: 9 additions & 3 deletions src/specify_cli/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -1002,8 +1002,11 @@ def _write_registered_output(
agent_config: dict[str, Any] | None = None,
) -> None:
"""Write a rendered agent artifact, optionally as a dev-mode symlink."""
from .integration_runtime import should_write_file
from .integrations._file_changes import after_file_change, before_file_change

if not should_write_file(dest_file, content.replace("\n", os.linesep).encode("utf-8")):
return
if dest_file.is_symlink():
before_file_change(dest_file, removal=True)
dest_file.unlink()
Expand Down Expand Up @@ -1057,11 +1060,14 @@ def write_copilot_prompt(project_root: Path, cmd_name: str) -> None:
prompt_file = prompts_dir / f"{cmd_name}.prompt.md"
CommandRegistrar._ensure_inside(prompt_file, prompts_dir)
prompt_file.parent.mkdir(parents=True, exist_ok=True)
from .integration_runtime import should_write_file
from .integrations._file_changes import after_file_change, before_file_change

before_file_change(prompt_file)
prompt_file.write_text(f"---\nagent: {cmd_name}\n---\n", encoding="utf-8")
after_file_change(prompt_file)
content = f"---\nagent: {cmd_name}\n---\n"
if should_write_file(prompt_file, content.replace("\n", os.linesep).encode("utf-8")):
before_file_change(prompt_file)
prompt_file.write_text(content, encoding="utf-8")
after_file_change(prompt_file)

@staticmethod
def _resolve_agent_dir(
Expand Down
6 changes: 2 additions & 4 deletions src/specify_cli/events/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -1401,9 +1401,8 @@ def install_integration_events(
dispatcher_dir.mkdir(parents=True, exist_ok=True)
_write_text(dispatcher_path, _EVENTS_DISPATCHER_TEMPLATE, encoding="utf-8")
dispatcher_path.chmod(0o755)
manifest.record_file(
manifest.record_existing(
str(dispatcher_path.relative_to(project_root)),
dispatcher_path.read_bytes(),
ownership="shared",
)
created.append(dispatcher_path)
Expand All @@ -1428,9 +1427,8 @@ def install_integration_events(
_build_opencode_plugin(filtered, canonical_to_native),
encoding="utf-8",
)
manifest.record_file(
manifest.record_existing(
plugin_rel,
plugin_path.read_bytes(),
)
created.append(plugin_path)

Expand Down
Loading
Loading