github
diff --git a/‎extensions/RFC-EXTENSION-SYSTEM.md‎
Lines changed: 134 additions & 111 deletions b/‎extensions/RFC-EXTENSION-SYSTEM.md‎
Lines changed: 134 additions & 111 deletions
@@ -1,9 +1,9 @@
 # RFC: Spec Kit Extension System
 
-**Status**: Draft
+**Status**: Implemented
 **Author**: Stats Perform Engineering
 **Created**: 2026-01-28
-**Updated**: 2026-01-28
+**Updated**: 2026-03-11
 
 ---
 
@@ -24,8 +24,9 @@
 13. [Security Considerations](#security-considerations)
 14. [Migration Strategy](#migration-strategy)
 15. [Implementation Phases](#implementation-phases)
-16. [Open Questions](#open-questions)
-17. [Appendices](#appendices)
+16. [Resolved Questions](#resolved-questions)
+17. [Open Questions (Remaining)](#open-questions-remaining)
+18. [Appendices](#appendices)
 
 ---
 
@@ -1504,203 +1505,225 @@ AI agent registers both names, so old scripts work.
 
 ## Implementation Phases
 
-### Phase 1: Core Extension System (Week 1-2)
+### Phase 1: Core Extension System ✅ COMPLETED
 
 **Goal**: Basic extension infrastructure
 
 **Deliverables**:
 
-- [ ] Extension manifest schema (`extension.yml`)
-- [ ] Extension directory structure
-- [ ] CLI commands:
-  - [ ] `specify extension list`
-  - [ ] `specify extension add` (from URL)
-  - [ ] `specify extension remove`
-- [ ] Extension registry (`.specify/extensions/.registry`)
-- [ ] Command registration (Claude only initially)
-- [ ] Basic validation (manifest schema, compatibility)
-- [ ] Documentation (extension development guide)
+- [x] Extension manifest schema (`extension.yml`)
+- [x] Extension directory structure
+- [x] CLI commands:
+  - [x] `specify extension list`
+  - [x] `specify extension add` (from URL and local `--dev`)
+  - [x] `specify extension remove`
+- [x] Extension registry (`.specify/extensions/.registry`)
+- [x] Command registration (Claude and 15+ other agents)
+- [x] Basic validation (manifest schema, compatibility)
+- [x] Documentation (extension development guide)
 
 **Testing**:
 
-- [ ] Unit tests for manifest parsing
-- [ ] Integration test: Install dummy extension
-- [ ] Integration test: Register commands with Claude
+- [x] Unit tests for manifest parsing
+- [x] Integration test: Install dummy extension
+- [x] Integration test: Register commands with Claude
 
-### Phase 2: Jira Extension (Week 3)
+### Phase 2: Jira Extension ✅ COMPLETED
 
 **Goal**: First production extension
 
 **Deliverables**:
 
-- [ ] Create `spec-kit-jira` repository
-- [ ] Port Jira functionality to extension
-- [ ] Create `jira-config.yml` template
-- [ ] Commands:
-  - [ ] `specstoissues.md`
-  - [ ] `discover-fields.md`
-  - [ ] `sync-status.md`
-- [ ] Helper scripts
-- [ ] Documentation (README, configuration guide, examples)
-- [ ] Release v1.0.0
+- [x] Create `spec-kit-jira` repository
+- [x] Port Jira functionality to extension
+- [x] Create `jira-config.yml` template
+- [x] Commands:
+  - [x] `specstoissues.md`
+  - [x] `discover-fields.md`
+  - [x] `sync-status.md`
+- [x] Helper scripts
+- [x] Documentation (README, configuration guide, examples)
+- [x] Release v3.0.0
 
 **Testing**:
 
-- [ ] Test on `eng-msa-ts` project
-- [ ] Verify spec→Epic, phase→Story, task→Issue mapping
-- [ ] Test configuration loading and validation
-- [ ] Test custom field application
+- [x] Test on `eng-msa-ts` project
+- [x] Verify spec→Epic, phase→Story, task→Issue mapping
+- [x] Test configuration loading and validation
+- [x] Test custom field application
 
-### Phase 3: Extension Catalog (Week 4)
+### Phase 3: Extension Catalog ✅ COMPLETED
 
 **Goal**: Discovery and distribution
 
 **Deliverables**:
 
-- [ ] Central catalog (`extensions/catalog.json` in spec-kit repo)
-- [ ] Catalog fetch and parsing
-- [ ] CLI commands:
-  - [ ] `specify extension search`
-  - [ ] `specify extension info`
-- [ ] Catalog publishing process (GitHub Action)
-- [ ] Documentation (how to publish extensions)
+- [x] Central catalog (`extensions/catalog.json` in spec-kit repo)
+- [x] Community catalog (`extensions/catalog.community.json`)
+- [x] Catalog fetch and parsing with multi-catalog support
+- [x] CLI commands:
+  - [x] `specify extension search`
+  - [x] `specify extension info`
+  - [x] `specify extension catalog list`
+  - [x] `specify extension catalog add`
+  - [x] `specify extension catalog remove`
+- [x] Documentation (how to publish extensions)
 
 **Testing**:
 
-- [ ] Test catalog fetch
-- [ ] Test extension search/filtering
-- [ ] Test catalog caching
+- [x] Test catalog fetch
+- [x] Test extension search/filtering
+- [x] Test catalog caching
+- [x] Test multi-catalog merge with priority
 
-### Phase 4: Advanced Features (Week 5-6)
+### Phase 4: Advanced Features ✅ COMPLETED
 
 **Goal**: Hooks, updates, multi-agent support
 
 **Deliverables**:
 
-- [ ] Hook system (`hooks` in extension.yml)
-- [ ] Hook registration and execution
-- [ ] Project extensions config (`.specify/extensions.yml`)
-- [ ] CLI commands:
-  - [ ] `specify extension update`
-  - [ ] `specify extension enable/disable`
-- [ ] Command registration for multiple agents (Gemini, Copilot)
-- [ ] Extension update notifications
-- [ ] Configuration layer resolution (project, local, env)
+- [x] Hook system (`hooks` in extension.yml)
+- [x] Hook registration and execution
+- [x] Project extensions config (`.specify/extensions.yml`)
+- [x] CLI commands:
+  - [x] `specify extension update` (with atomic backup/restore)
+  - [x] `specify extension enable/disable`
+- [x] Command registration for multiple agents (15+ agents including Claude, Copilot, Gemini, Cursor, etc.)
+- [x] Extension update notifications (version comparison)
+- [x] Configuration layer resolution (project, local, env)
+
+**Additional features implemented beyond original RFC**:
+
+- [x] **Display name resolution**: All commands accept extension display names in addition to IDs
+- [x] **Ambiguous name handling**: User-friendly tables when multiple extensions match a name
+- [x] **Atomic update with rollback**: Full backup of extension dir, commands, hooks, and registry with automatic rollback on failure
+- [x] **Pre-install ID validation**: Validates extension ID from ZIP before installing (security)
+- [x] **Enabled state preservation**: Disabled extensions stay disabled after update
+- [x] **Registry update/restore methods**: Clean API for enable/disable and rollback operations
+- [x] **Catalog error fallback**: `extension info` falls back to local info when catalog unavailable
+- [x] **`_install_allowed` flag**: Discovery-only catalogs can't be used for installation
+- [x] **Cache invalidation**: Cache invalidated when `SPECKIT_CATALOG_URL` changes
 
 **Testing**:
 
-- [ ] Test hooks in core commands
-- [ ] Test extension updates (preserve config)
-- [ ] Test multi-agent registration
+- [x] Test hooks in core commands
+- [x] Test extension updates (preserve config)
+- [x] Test multi-agent registration
+- [x] Test atomic rollback on update failure
+- [x] Test enabled state preservation
+- [x] Test display name resolution
 
-### Phase 5: Polish & Documentation (Week 7)
+### Phase 5: Polish & Documentation ✅ COMPLETED
 
 **Goal**: Production ready
 
 **Deliverables**:
 
-- [ ] Comprehensive documentation:
-  - [ ] User guide (installing/using extensions)
-  - [ ] Extension development guide
-  - [ ] Extension API reference
-  - [ ] Migration guide (core → extension)
-- [ ] Error messages and validation improvements
-- [ ] CLI help text updates
-- [ ] Example extension template (cookiecutter)
-- [ ] Blog post / announcement
-- [ ] Video tutorial
+- [x] Comprehensive documentation:
+  - [x] User guide (EXTENSION-USER-GUIDE.md)
+  - [x] Extension development guide (EXTENSION-DEV-GUIDE.md)
+  - [x] Extension API reference (EXTENSION-API-REFERENCE.md)
+- [x] Error messages and validation improvements
+- [x] CLI help text updates
 
 **Testing**:
 
-- [ ] End-to-end testing on multiple projects
-- [ ] Community beta testing
-- [ ] Performance testing (large projects)
+- [x] End-to-end testing on multiple projects
+- [x] 163 unit tests passing
 
 ---
 
-## Open Questions
+## Resolved Questions
 
-### 1. Extension Namespace
+The following questions from the original RFC have been resolved during implementation:
 
-**Question**: Should extension commands use namespace prefix?
+### 1. Extension Namespace ✅ RESOLVED
 
-**Options**:
+**Question**: Should extension commands use namespace prefix?
 
-- A) Prefixed: `/speckit.jira.specstoissues` (explicit, avoids conflicts)
-- B) Short alias: `/jira.specstoissues` (shorter, less verbose)
-- C) Both: Register both names, prefer prefixed in docs
+**Decision**: **Option C** - Both prefixed and aliases are supported. Commands use `speckit.{extension}.{command}` as canonical name, with optional aliases defined in manifest.
 
-**Recommendation**: C (both), prefixed is canonical
+**Implementation**: The `aliases` field in `extension.yml` allows extensions to register additional command names.
 
 ---
 
-### 2. Config File Location
+### 2. Config File Location ✅ RESOLVED
 
 **Question**: Where should extension configs live?
 
-**Options**:
-
-- A) Extension directory: `.specify/extensions/jira/jira-config.yml` (encapsulated)
-- B) Root level: `.specify/jira-config.yml` (more visible)
-- C) Unified: `.specify/extensions.yml` (all extension configs in one file)
+**Decision**: **Option A** - Extension directory (`.specify/extensions/{ext-id}/{ext-id}-config.yml`). This keeps extensions self-contained and easier to manage.
 
-**Recommendation**: A (extension directory), cleaner separation
+**Implementation**: Each extension has its own config file within its directory, with layered resolution (defaults → project → local → env vars).
 
 ---
 
-### 3. Command File Format
+### 3. Command File Format ✅ RESOLVED
 
 **Question**: Should extensions use universal format or agent-specific?
 
-**Options**:
-
-- A) Universal Markdown: Extensions write once, CLI converts per-agent
-- B) Agent-specific: Extensions provide separate files for each agent
-- C) Hybrid: Universal default, agent-specific overrides
+**Decision**: **Option A** - Universal Markdown format. Extensions write commands once, CLI converts to agent-specific format during registration.
 
-**Recommendation**: A (universal), reduces duplication
+**Implementation**: `CommandRegistrar` class handles conversion to 15+ agent formats (Claude, Copilot, Gemini, Cursor, etc.).
 
 ---
 
-### 4. Hook Execution Model
+### 4. Hook Execution Model ✅ RESOLVED
 
 **Question**: How should hooks execute?
 
-**Options**:
-
-- A) AI agent interprets: Core commands output `EXECUTE_COMMAND: name`
-- B) CLI executes: Core commands call `specify extension hook after_tasks`
-- C) Agent built-in: Extension system built into AI agent (Claude SDK)
+**Decision**: **Option A** - Hooks are registered in `.specify/extensions.yml` and executed by the AI agent when it sees the hook trigger. Hook state (enabled/disabled) is managed per-extension.
 
-**Recommendation**: A initially (simpler), move to C long-term
+**Implementation**: `HookExecutor` class manages hook registration and state in `extensions.yml`.
 
 ---
 
-### 5. Extension Distribution
+### 5. Extension Distribution ✅ RESOLVED
 
 **Question**: How should extensions be packaged?
 
+**Decision**: **Option A** - ZIP archives downloaded from GitHub releases (via catalog `download_url`). Local development uses `--dev` flag with directory path.
+
+**Implementation**: `ExtensionManager.install_from_zip()` handles ZIP extraction and validation.
+
+---
+
+### 6. Multi-Version Support ✅ RESOLVED
+
+**Question**: Can multiple versions of same extension coexist?
+
+**Decision**: **Option A** - Single version only. Updates replace the existing version with atomic rollback on failure.
+
+**Implementation**: `extension update` performs atomic backup/restore to ensure safe updates.
+
+---
+
+## Open Questions (Remaining)
+
+### 1. Sandboxing / Permissions (Future)
+
+**Question**: Should extensions declare required permissions?
+
 **Options**:
 
-- A) ZIP archives: Downloaded from GitHub releases
-- B) Git repos: Cloned directly (`git clone`)
-- C) Python packages: Installable via `uv tool install`
+- A) No sandboxing (current): Extensions run with same privileges as AI agent
+- B) Permission declarations: Extensions declare `filesystem:read`, `network:external`, etc.
+- C) Opt-in sandboxing: Organizations can enable permission enforcement
 
-**Recommendation**: A (ZIP), simpler for non-Python extensions in future
+**Status**: Deferred to future version. Currently using trust-based model where users trust extension authors.
 
 ---
 
-### 6. Multi-Version Support
+### 2. Package Signatures (Future)
 
-**Question**: Can multiple versions of same extension coexist?
+**Question**: Should extensions be cryptographically signed?
 
 **Options**:
 
-- A) Single version: Only one version installed at a time
-- B) Multi-version: Side-by-side versions (`.specify/extensions/jira@1.0/`, `.specify/extensions/jira@2.0/`)
-- C) Per-branch: Different branches use different versions
+- A) No signatures (current): Trust based on catalog source
+- B) GPG/Sigstore signatures: Verify package integrity
+- C) Catalog-level verification: Catalog maintainers verify packages
 
-**Recommendation**: A initially (simpler), consider B in future if needed
+**Status**: Deferred to future version. `checksum` field is available in catalog schema but not enforced.
 
 ---