Document the implemented extension architecture

[mnriem]

Description

Documents the extension architecture as it is implemented and tested today in design/extension.md, including manifest validation, catalog trust and precedence, lifecycle and rollback behavior, integration delivery, configuration and hooks, artifact resolution, bundled packaging, persistence, filesystem ownership, and current CLI/MCP boundaries.

Deletes the historical extensions/RFC-EXTENSION-SYSTEM.md after replacing its still-valid implemented architecture, and links the CLI design to the new normative document. This PR intentionally does not reorganize the public extension guides or change runtime behavior.

Testing

• npx --no-install markdownlint-cli2 design/extension.md design/cli.md — passed with 0 issues.

• Relative Markdown link and deleted-path validation script — passed; all relative links resolve and the obsolete RFC path is absent.

• git diff --check — passed.

• Tested locally with uv run specify --help

• Ran existing tests with uv sync && uv run pytest

• Tested with a sample project (if applicable)

Documentation-only architecture change; executable behavior and user workflows were not changed, so CLI, full-suite, and sample-project testing were not run.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: GitHub Copilot using GPT-5.6 Sol in autonomous mode traced the implemented extension code and tests, authored the architecture documentation, removed the obsolete RFC, updated the cross-link, and ran the listed documentation validations on behalf of the contributor.

[Copilot]

🟡 Changes recommended

The new reference contains inaccurate lifecycle and safety guarantees that need correction.

5 open findings

• Normalized alias collisions bypass extension conflict validation · New
• Document that local-config.yml is preserved during removal · New
• Disabled integrations leave existing commands and skills invocable · New
• Scope alias and preservation claims to the applicable renderer · New
• Limit force-install guarantees to pre-removal validation · New

What changed in this PR

Documents Spec Kit’s implemented extension architecture without changing runtime behavior.

Changes:

• Adds an architecture reference covering contracts, lifecycle, delivery, and trust boundaries.
• Removes the historical RFC and links CLI design to the replacement.

AI disclosure: GitHub Copilot (model unknown, automated mode), reviewing for the requester (identity unavailable); analysis and wording are AI-generated.

File	Description
extensions/​RFC-EXTENSION-SYSTEM.md	Removes the historical RFC.
design/​extension.md	Documents current extension architecture and boundaries.
design/​cli.md	Links to the extension architecture reference.

🧠 Review effort: Max

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mnriem]

Addressed the review findings in 8372ec5739ff6bd30a7a58c975b136db8b5f6f48:

• distinguished exact installed-extension name checks from normalized core-command collision checks;
• corrected local-config.yml preservation behavior;
• separated registry disablement from cleanup of already-generated non-generic invocations;
• documented native skill registration separately from supplemental skills-mode rendering;
• limited force-install pre-removal guarantees and documented post-removal .extensionignore validation.

Validation:

• npx --no-install markdownlint-cli2 design/extension.md design/cli.md — passed, 0 issues
• relative Markdown link validation for design/extension.md and design/cli.md — passed
• deleted RFC path/reference check — passed
• git diff --check — passed

AI disclosure: Written on behalf of contributor Manfred Riem by GitHub Copilot using GPT-5.6 Sol in autonomous mode; the review-fix documentation changes, inline replies, validation summary, and this comment are AI-generated.

[Copilot]

🔵 Needs a closer look

The architecture reference contains verified inaccuracies about hook delivery and filesystem safety guarantees.

0 open findings

5 resolved since last review

• Limit force-install guarantees to pre-removal validation
• Scope alias and preservation claims to the applicable renderer
• Disabled integrations leave existing commands and skills invocable
• Document that local-config.yml is preserved during removal
• Normalized alias collisions bypass extension conflict validation

Previously missed (4)

In code that hasn't changed since last review

Scope pre-copy and collision checks to generic registration

design/​extension.md:187

These pre-copy settings and output-collision checks are specific to generic command registration (src/specify_cli/extensions/__init__.py:2484-2564). Other integrations do not run this output preflight, so the common lifecycle list promises protection they do not have. Scope this step to the generic integration.

AI disclosure: GitHub Copilot (model unknown, automated mode), for the requester (identity unavailable); review analysis and wording are AI-generated.

Separate configuration scaffolding from shared installation steps

design/​extension.md:196

Configuration scaffolding is caller-specific, not shared by all installation routes. extension add, extension enable, and bundle installs call scaffold_config(), but _install_extension_during_init() and the update modules do not. Separate scaffolding from the manager's numbered steps so readers do not assume init --extension or an update creates declared configuration files.

AI disclosure: GitHub Copilot (model unknown, automated mode), for the requester (identity unavailable); review analysis and wording are AI-generated.

Distinguish HookExecutor behavior from command-template hook delivery

design/​extension.md:272

This describes the HookExecutor helper API, but omits the shipped hook-delivery path. Core command templates read .specify/extensions.yml directly, skip every hook with a non-empty condition, and preserve YAML order rather than sorting by priority (templates/commands/tasks.md:28-58; docs/reference/extensions.md:341-350). Readers could otherwise expect a true condition to run a hook that the templates actually skip. Distinguish the helper behavior from the command-template behavior.

AI disclosure: GitHub Copilot (model unknown, automated mode), for the requester (identity unavailable); review analysis and wording are AI-generated.

Limit registry-write guarantees for symlinked extension roots

design/​extension.md:346

This guarantee is not universal. ExtensionRegistry._save() (src/specify_cli/extensions/__init__.py:827-835) writes through a symlinked .specify/extensions root without checking containment. A focused check using the actual save method and file-change observer module confirmed that .registry is written outside the project when no observer is active. Scope the guarantee to guarded paths and document this registry-write limitation.

AI disclosure: GitHub Copilot (model unknown, automated mode), for the requester (identity unavailable); review analysis and wording are AI-generated.

🧠 Review effort: Max

[mnriem]

Addressed the four previously missed findings from review 5537779958 in 0550d541d3d42c2f2db491dc9324e1495f113d75:

• scoped integration-state, command-source, and output-collision preflight checks to generic registration;
• separated caller-owned configuration scaffolding from the shared installation lifecycle, including the init and update exceptions;
• distinguished HookExecutor behavior from shipped command-template hook delivery, including condition skipping and YAML ordering;
• limited filesystem-containment guarantees and documented that unobserved registry saves can follow a symlinked extension root outside the project.

Validation:

• npx --no-install markdownlint-cli2 design/extension.md design/cli.md — passed, 0 issues
• relative Markdown link validation for design/extension.md and design/cli.md — passed
• deleted RFC path/reference check — passed
• git diff --check — passed

AI disclosure: Written on behalf of contributor Manfred Riem by GitHub Copilot using GPT-5.6 Sol in autonomous mode; the documentation review fixes, validation summary, and this comment are AI-generated.

[Copilot]

🟢 Approval recommended

The changes affect documentation only, and the remaining wording corrections are non-blocking.

0 open findings

Previously missed (2)

In code that hasn't changed since last review

Check Spec Kit compatibility before offering updates

design/​extension.md:230

discover_updates() compares versions and checks catalog installability, but does not check Spec Kit compatibility (_command_update_discovery.py:87-143). Compatibility is enforced in preflight_update_archive() (_command_update_artifacts.py:137-138), after confirmation and before mutation. An incompatible release can therefore appear in the offered update list. Please attribute the compatibility check to preflight rather than discovery.

AI disclosure: GitHub Copilot (model unknown, autonomous review mode), for the requester (identity unavailable); analysis and wording are AI-generated.

Prevent undeclared root templates from shadowing core templates

design/​extension.md:306

The no-fallback guarantee applies only to successfully validated manifests. _extension_manifest_declared_template() returns (None, None) on loading or validation errors (src/specify_cli/presets/_resolver.py:124-127), allowing conventional lookup. That lookup also searches the extension root for templates, so an undeclared root-level <name>.md can shadow a core template (:243-244,306-319,524-546). Please qualify the guarantee and include the root-level template fallback.

AI disclosure: GitHub Copilot (model unknown, autonomous review mode), for the requester (identity unavailable); analysis and wording are AI-generated.

🧠 Review effort: Max

[mnriem]

Addressed the two previously missed wording findings from review 5538558312 in 3375ff6e7e33ee01a4bf979d84f5ef046162e9d3:

• moved Spec Kit compatibility enforcement from update discovery to the post-selection, pre-mutation archive preflight where it actually occurs;
• qualified manifest-authoritative artifact resolution and documented conventional fallback for absent, unreadable, invalid, or non-declaring manifests, including root-level template lookup before core assets.

Validation:

• npx --no-install markdownlint-cli2 design/extension.md design/cli.md — passed, 0 issues
• relative Markdown link validation for design/extension.md and design/cli.md — passed
• deleted RFC path/reference check — passed
• git diff --check — passed

AI disclosure: Written on behalf of contributor Manfred Riem by GitHub Copilot using GPT-5.6 Sol in autonomous mode; the documentation review fixes, validation summary, and this comment are AI-generated.

[Copilot]

🟢 Approval recommended

Only a minor documentation clarification remains, with no blocking issues or runtime changes.

0 open findings

Previously missed (1)

In code that hasn't changed since last review

Fix extension command hierarchy reference

design/​cli.md:15

The linked document describes extension-domain behavior and defers command adapter conventions back to cli.md (design/extension.md:8–14); it does not define a command-group layout. Keep the reference tied to the extension command hierarchy shown under “Nested command groups”, and link the domain architecture separately.

AI disclosure: GitHub Copilot (model unknown, automated review mode), for the requester (identity unavailable); review wording and suggested edit are AI-generated.

🧠 Review effort: Max