Merge branch 'main' into add-status-command

2026-03-17 19:03:08 +00:00 · 2026-03-16 17:11:47 +05:00
parent c8e9f16cf9 4a3234496e
commit 25bfc42210
49 changed files with 7272 additions and 890 deletions
--- a/extensions/README.md
+++ b/extensions/README.md
@@ -74,8 +74,10 @@ The following community-contributed extensions are available in [`catalog.commun
 |-----------|---------|-----|
 | Azure DevOps Integration | Sync user stories and tasks to Azure DevOps work items using OAuth authentication | [spec-kit-azure-devops](https://github.com/pragya247/spec-kit-azure-devops) |
 | Cleanup Extension | Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues | [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup) |
+| DocGuard — CDD Enforcement | Canonical-Driven Development enforcement. Generates, validates, scores, and traces project documentation against 92 automated checks with config-aware traceability, quality labels, and AI-ready fix prompts. Zero dependencies. | [spec-kit-docguard](https://github.com/raccioly/docguard) |
 | Fleet Orchestrator | Orchestrate a full feature lifecycle with human-in-the-loop gates across all SpecKit phases | [spec-kit-fleet](https://github.com/sharathsatish/spec-kit-fleet) |
 | Jira Integration | Create Jira Epics, Stories, and Issues from spec-kit specifications and task breakdowns with configurable hierarchy and custom field support | [spec-kit-jira](https://github.com/mbachorik/spec-kit-jira) |
+| Project Health Check | Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git | [spec-kit-doctor](https://github.com/KhawarHabibKhan/spec-kit-doctor) |
 | Project Status | Show current SDD workflow progress — active feature, artifact status, task completion, workflow phase, and extensions summary | [spec-kit-status](https://github.com/KhawarHabibKhan/spec-kit-status) |
 | Ralph Loop | Autonomous implementation loop using AI agent CLI | [spec-kit-ralph](https://github.com/Rubiss/spec-kit-ralph) |
 | Retrospective Extension | Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates | [spec-kit-retrospective](https://github.com/emi-dm/spec-kit-retrospective) |
--- a/extensions/RFC-EXTENSION-SYSTEM.md
+++ b/extensions/RFC-EXTENSION-SYSTEM.md
@@ -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:
+
+### 1. Extension Namespace ✅ RESOLVED

 **Question**: Should extension commands use namespace prefix?

-**Options**:
+**Decision**: **Option C** - Both prefixed and aliases are supported. Commands use `speckit.{extension}.{command}` as canonical name, with optional aliases defined in manifest.

- 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
-
-**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**:
+**Decision**: **Option A** - Extension directory (`.specify/extensions/{ext-id}/{ext-id}-config.yml`). This keeps extensions self-contained and easier to manage.

- 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)
-
-**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**:
+**Decision**: **Option A** - Universal Markdown format. Extensions write commands once, CLI converts to agent-specific format during registration.

- 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
-
-**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**:
+**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.

- 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)
-
-**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?

-**Options**:
+**Decision**: **Option A** - ZIP archives downloaded from GitHub releases (via catalog `download_url`). Local development uses `--dev` flag with directory path.

- A) ZIP archives: Downloaded from GitHub releases
- B) Git repos: Cloned directly (`git clone`)
- C) Python packages: Installable via `uv tool install`
-
-**Recommendation**: A (ZIP), simpler for non-Python extensions in future
+**Implementation**: `ExtensionManager.install_from_zip()` handles ZIP extraction and validation.

 ---

-### 6. Multi-Version Support
+### 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) 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 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 initially (simpler), consider B in future if needed
+**Status**: Deferred to future version. Currently using trust-based model where users trust extension authors.
+
+---
+
+### 2. Package Signatures (Future)
+
+**Question**: Should extensions be cryptographically signed?
+
+**Options**:
+
+- A) No signatures (current): Trust based on catalog source
+- B) GPG/Sigstore signatures: Verify package integrity
+- C) Catalog-level verification: Catalog maintainers verify packages
+
+**Status**: Deferred to future version. `checksum` field is available in catalog schema but not enforced.

 ---

--- a/extensions/catalog.community.json
+++ b/extensions/catalog.community.json
@@ -1,6 +1,6 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-03-09T00:00:00Z",
+  "updated_at": "2026-03-13T12:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
  "extensions": {
    "azure-devops": {
@@ -74,6 +74,79 @@
      "created_at": "2026-02-22T00:00:00Z",
      "updated_at": "2026-02-22T00:00:00Z"
    },
+    "docguard": {
+      "name": "DocGuard — CDD Enforcement",
+      "id": "docguard",
+      "description": "Canonical-Driven Development enforcement. Generates, validates, scores, and traces project documentation against 92 automated checks. Zero dependencies.",
+      "author": "raccioly",
+      "version": "0.8.0",
+      "download_url": "https://github.com/raccioly/docguard/releases/download/v0.8.0/spec-kit-docguard-v0.8.0.zip",
+      "repository": "https://github.com/raccioly/docguard",
+      "homepage": "https://www.npmjs.com/package/docguard-cli",
+      "documentation": "https://github.com/raccioly/docguard/blob/main/extensions/spec-kit-docguard/README.md",
+      "changelog": "https://github.com/raccioly/docguard/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0",
+        "tools": [
+          {
+            "name": "node",
+            "version": ">=18.0.0",
+            "required": true
+          }
+        ]
+      },
+      "provides": {
+        "commands": 6,
+        "hooks": 1
+      },
+      "tags": [
+        "documentation",
+        "validation",
+        "quality",
+        "cdd",
+        "traceability",
+        "ai-agents",
+        "enforcement",
+        "scoring"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-13T00:00:00Z",
+      "updated_at": "2026-03-13T00:00:00Z"
+    },
+    "doctor": {
+      "name": "Project Health Check",
+      "id": "doctor",
+      "description": "Diagnose a Spec Kit project and report health issues across structure, agents, features, scripts, extensions, and git.",
+      "author": "KhawarHabibKhan",
+      "version": "1.0.0",
+      "download_url": "https://github.com/KhawarHabibKhan/spec-kit-doctor/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/KhawarHabibKhan/spec-kit-doctor",
+      "homepage": "https://github.com/KhawarHabibKhan/spec-kit-doctor",
+      "documentation": "https://github.com/KhawarHabibKhan/spec-kit-doctor/blob/main/README.md",
+      "changelog": "https://github.com/KhawarHabibKhan/spec-kit-doctor/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 0
+      },
+      "tags": [
+        "diagnostics",
+        "health-check",
+        "validation",
+        "project-structure"
+      ],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-03-13T00:00:00Z",
+      "updated_at": "2026-03-13T00:00:00Z"
+    },
    "fleet": {
      "name": "Fleet Orchestrator",
      "id": "fleet",
@@ -93,7 +166,12 @@
        "commands": 2,
        "hooks": 1
      },
-      "tags": ["orchestration", "workflow", "human-in-the-loop", "parallel"],
+      "tags": [
+        "orchestration",
+        "workflow",
+        "human-in-the-loop",
+        "parallel"
+      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
@@ -160,7 +238,12 @@
        "commands": 2,
        "hooks": 1
      },
-      "tags": ["implementation", "automation", "loop", "copilot"],
+      "tags": [
+        "implementation",
+        "automation",
+        "loop",
+        "copilot"
+      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
@@ -218,7 +301,15 @@
        "commands": 7,
        "hooks": 1
      },
-      "tags": ["code-review", "quality", "review", "testing", "error-handling", "type-design", "simplification"],
+      "tags": [
+        "code-review",
+        "quality",
+        "review",
+        "testing",
+        "error-handling",
+        "type-design",
+        "simplification"
+      ],
      "verified": false,
      "downloads": 0,
      "stars": 0,
--- a/extensions/catalog.json
+++ b/extensions/catalog.json
@@ -1,6 +1,21 @@
 {
  "schema_version": "1.0",
-  "updated_at": "2026-02-03T00:00:00Z",
+  "updated_at": "2026-03-10T00:00:00Z",
  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
-  "extensions": {}
-}
+  "extensions": {
+    "selftest": {
+      "name": "Spec Kit Self-Test Utility",
+      "id": "selftest",
+      "version": "1.0.0",
+      "description": "Verifies catalog extensions by programmatically walking through the discovery, installation, and registration lifecycle.",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "download_url": "https://github.com/github/spec-kit/releases/download/selftest-v1.0.0/selftest.zip",
+      "tags": [
+        "testing",
+        "core",
+        "utility"
+      ]
+    }
+  }
+}
--- a/extensions/selftest/commands/selftest.md
+++ b/extensions/selftest/commands/selftest.md
@@ -0,0 +1,69 @@
+---
+description: "Validate the lifecycle of an extension from the catalog."
+---
+
+# Extension Self-Test: `$ARGUMENTS`
+
+This command drives a self-test simulating the developer experience with the `$ARGUMENTS` extension.
+
+## Goal
+
+Validate the end-to-end lifecycle (discovery, installation, registration) for the extension: `$ARGUMENTS`.
+If `$ARGUMENTS` is empty, you must tell the user to provide an extension name, for example: `/speckit.selftest.extension linear`.
+
+## Steps
+
+### Step 1: Catalog Discovery Validation
+
+Check if the extension exists in the Spec Kit catalog.
+Execute this command and verify that it completes successfully and that the returned extension ID exactly matches `$ARGUMENTS`. If the command fails or the ID does not match `$ARGUMENTS`, fail the test.
+
+```bash
+specify extension info "$ARGUMENTS"
+```
+
+### Step 2: Simulate Installation
+
+First, try to add the extension to the current workspace configuration directly. If the catalog provides the extension as `install_allowed: false` (discovery-only), this step is *expected* to fail.
+
+```bash
+specify extension add "$ARGUMENTS"
+```
+
+Then, simulate adding the extension by installing it from its catalog download URL, which should bypass the restriction.
+Obtain the extension's `download_url` from the catalog metadata (for example, via a catalog info command or UI), then run:
+
+```bash
+specify extension add "$ARGUMENTS" --from "<download_url>"
+```
+
+### Step 3: Registration Verification
+
+Once the `add` command completes, verify the installation by checking the project configuration.
+Use terminal tools (like `cat`) to verify that the following file contains a record for `$ARGUMENTS`.
+
+```bash
+cat .specify/extensions/.registry/$ARGUMENTS.json
+```
+
+### Step 4: Verification Report
+
+Analyze the standard output of the three steps. 
+Generate a terminal-style test output format detailing the results of discovery, installation, and registration. Return this directly to the user.
+
+Example output format:
+```text
+============================= test session starts ==============================
+collected 3 items
+
+test_selftest_discovery.py::test_catalog_search [PASS/FAIL]
+  Details: [Provide execution result of specify extension search]
+
+test_selftest_installation.py::test_extension_add [PASS/FAIL]
+  Details: [Provide execution result of specify extension add]
+
+test_selftest_registration.py::test_config_verification [PASS/FAIL]
+  Details: [Provide execution result of registry record verification]
+
+============================== [X] passed in ... ==============================
+```
--- a/extensions/selftest/extension.yml
+++ b/extensions/selftest/extension.yml
@@ -0,0 +1,16 @@
+schema_version: "1.0"
+extension:
+  id: selftest
+  name: Spec Kit Self-Test Utility
+  version: 1.0.0
+  description: Verifies catalog extensions by programmatically walking through the discovery, installation, and registration lifecycle.
+  author: spec-kit-core
+  repository: https://github.com/github/spec-kit
+  license: MIT
+requires:
+  speckit_version: ">=0.2.0"
+provides:
+  commands:
+    - name: speckit.selftest.extension
+      file: commands/selftest.md
+      description: Validate the lifecycle of an extension from the catalog.