diff --git a/docs/README.md b/docs/README.md index 4bd3657d10..6849107b38 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,6 +33,7 @@ To build the documentation locally: - `guides/assessment.md` - Idea assessment walkthrough - `guides/customization.md` - Choosing and combining customization building blocks - `reference/catalogs.md` - Catalog discovery, trust, private sources, and precedence +- `extensions/overview.md` - Extension user guide - `extensions/publishing.md` - Extension publishing and catalog submission guide - `integrations/index.md` - Integration directory and shared setup guidance - `integrations/cli.md` - Shared integration management CLI reference diff --git a/extensions/EXTENSION-USER-GUIDE.md b/docs/extensions/overview.md similarity index 90% rename from extensions/EXTENSION-USER-GUIDE.md rename to docs/extensions/overview.md index 1561b3c9fc..7343ce1cda 100644 --- a/extensions/EXTENSION-USER-GUIDE.md +++ b/docs/extensions/overview.md @@ -1,4 +1,4 @@ -# Extension User Guide +# Extensions Overview Complete guide for using Spec Kit extensions to enhance your workflow. @@ -68,8 +68,8 @@ specify extension add jira vim .specify/extensions/jira/jira-config.yml # 5. Use it -# (Commands are now available in Claude Code) -/speckit.jira.specstoissues +# (Skills are now available in GitHub Copilot) +/speckit-jira-specstoissues ``` --- @@ -179,45 +179,25 @@ Jira Integration (v1.0.0) Create Jira Epics, Stories, and Issues from spec-kit artifacts Provided commands: - • speckit.jira.specstoissues - Create Jira hierarchy from spec and tasks - • speckit.jira.discover-fields - Discover Jira custom fields for configuration - • speckit.jira.sync-status - Sync task completion status to Jira + • speckit-jira-specstoissues - Create Jira hierarchy from spec and tasks + • speckit-jira-discover-fields - Discover Jira custom fields for configuration + • speckit-jira-sync-status - Sync task completion status to Jira ⚠ Configuration may be required Check: .specify/extensions/jira/ ``` -Command names are listed the way your agent registers them. Skills-based integrations such as Claude Code and Codex, projects initialized with `--integration-options="--skills"`, and agents such as Cline, Forge, and Junie show hyphenated names (for example `speckit-jira-specstoissues`). - -### Automatic Agent Skill Registration - -If your project uses a skills-based integration (e.g., `--integration claude`, `--integration codex`) or was initialized with `--integration-options="--skills"`, extension commands are **automatically registered as agent skills** during installation. This ensures that extensions are discoverable by agents that use the [agentskills.io](https://agentskills.io) skill specification. - -```text -✓ Extension installed successfully! - -Jira Integration (v1.0.0) - ... - -✓ 3 agent skill(s) auto-registered -``` - -When an extension is removed, its corresponding skills are also cleaned up automatically. Pre-existing skills that were manually customized are never overwritten. - --- ## Using Extensions ### Using Extension Commands -Extensions add commands that appear in your coding agent (Claude Code): +Extensions add skills that appear in GitHub Copilot: ```text -# In Claude Code -> /speckit.jira.specstoissues - -# Or use a namespaced alias (if provided) -> /speckit.jira.sync +# In GitHub Copilot +> /speckit-jira-specstoissues ``` ### Extension Configuration @@ -243,21 +223,21 @@ vim .specify/extensions/jira/jira-config.yml Some extensions provide hooks that execute after core commands: -**Example**: Jira extension hooks into `/speckit.tasks` +**Example**: Jira extension hooks into `/speckit-tasks` ```text # Run core command -> /speckit.tasks +> /speckit-tasks # Output includes: ## Extension Hooks **Optional Hook**: jira -Command: `/speckit.jira.specstoissues` +Command: `/speckit-jira-specstoissues` Description: Automatically create Jira hierarchy after task generation Prompt: Create Jira issues from tasks? -To execute: `/speckit.jira.specstoissues` +To execute: `/speckit-jira-specstoissues` ``` You can then choose to run the hook or skip it. @@ -348,7 +328,7 @@ Extensions can have multiple configuration files: ```text .specify/extensions/jira/ ├── jira-config.yml # Main config (version controlled) -├── jira-config.local.yml # Local overrides (gitignored) +├── local-config.yml # Local overrides (gitignored) └── jira-config.template.yml # Template (reference) ``` @@ -358,7 +338,7 @@ Configuration is merged in this order (highest priority last): 1. **Extension defaults** (from `extension.yml`) 2. **Project config** (`jira-config.yml`) -3. **Local overrides** (`jira-config.local.yml`) +3. **Local overrides** (`local-config.yml`) 4. **Environment variables** (`SPECKIT_JIRA_*`) ### Example: Jira Configuration @@ -374,7 +354,7 @@ defaults: labels: ["spec-driven"] ``` -**Local override** (`.specify/extensions/jira/jira-config.local.yml`): +**Local override** (`.specify/extensions/jira/local-config.yml`): ```yaml project: @@ -805,11 +785,11 @@ specify extension add --dev /path/to/extension **Solutions**: 1. Check extension is enabled: `specify extension list` -2. Restart coding agent (Claude Code) -3. Check command file exists: +2. Restart GitHub Copilot +3. Check the skill file exists: ```bash - ls .claude/commands/speckit.jira.*.md + ls .github/skills/speckit-jira-*/SKILL.md ``` 4. Reinstall extension @@ -868,7 +848,7 @@ specify extension add --dev /path/to/extension - `.specify/extensions/.cache/` (catalog cache) - `.specify/extensions/.backup/` (config backups) -- `.specify/extensions/*/*.local.yml` (local overrides) +- `.specify/extensions/*/local-config.yml` (local overrides) - `.specify/extensions/.registry` (installation state) Add to `.gitignore`: @@ -876,7 +856,7 @@ Add to `.gitignore`: ```gitignore .specify/extensions/.cache/ .specify/extensions/.backup/ -.specify/extensions/*/*.local.yml +.specify/extensions/*/local-config.yml .specify/extensions/.registry ``` @@ -907,7 +887,7 @@ To install: `specify extension add jira` Use local config for development: ```yaml -# .specify/extensions/jira/jira-config.local.yml +# .specify/extensions/jira/local-config.yml project: key: "DEVTEST" # Your test project @@ -966,9 +946,9 @@ Document extension usage in your project: ## Working with Jira After creating tasks, sync to Jira: -1. Run `/speckit.tasks` to generate tasks -2. Run `/speckit.jira.specstoissues` to create Jira issues -3. Run `/speckit.jira.sync-status` to update status +1. Run `/speckit-tasks` to generate tasks +2. Run `/speckit-jira-specstoissues` to create Jira issues +3. Run `/speckit-jira-sync-status` to update status ``` --- @@ -1020,11 +1000,13 @@ After creating tasks, sync to Jira: ## Support - **Extension Issues**: Report to extension repository (see `specify extension info`) -- **Spec Kit Issues**: -- **Extension Catalog**: -- **Documentation**: See EXTENSION-DEVELOPMENT-GUIDE.md and the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html) +- **Spec Kit Issues**: +- **Extension Catalog**: +- **Documentation**: See the [Extension Development Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md) and [Extension Publishing Guide](publishing.md) --- *Last Updated: 2026-01-28* *Spec Kit Version: 0.1.0* + +> Agent invocation examples on this page use GitHub Copilot's default skills syntax (`/speckit-*`). For other integrations and modes, see [Command invocation](../integrations/cli.md#command-invocation). diff --git a/docs/toc.yml b/docs/toc.yml index 31a64b61d2..f1ee2c31a4 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -135,6 +135,15 @@ - name: Contributing Integrations href: integrations/contributing.md +# Extensions +- name: Extensions + href: extensions/overview.md + items: + - name: Overview + href: extensions/overview.md + - name: Publishing + href: extensions/publishing.md + # Reference - name: Reference items: @@ -199,8 +208,6 @@ href: community/overview.md - name: Extensions href: community/extensions.md - - name: Publishing Extensions - href: extensions/publishing.md - name: Presets href: community/presets.md - name: Bundles diff --git a/extensions/EXTENSION-API-REFERENCE.md b/extensions/EXTENSION-API-REFERENCE.md index 2be2f43123..3ba1641839 100644 --- a/extensions/EXTENSION-API-REFERENCE.md +++ b/extensions/EXTENSION-API-REFERENCE.md @@ -44,7 +44,6 @@ provides: - name: string # Required, pattern: ^speckit\.[a-z0-9-]+\.[a-z0-9-]+$ file: string # Required, relative path to command file description: string # Required - aliases: [string] # Optional, same pattern as name; namespace must match extension.id and must not shadow core or installed extension commands templates: # Optional, array of declared templates. Always resolve # as "replace" -- 'strategy' is not an authorable field here. diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md index fb06f72305..155a50b4be 100644 --- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md +++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md @@ -41,7 +41,6 @@ provides: - name: "speckit.my-ext.hello" # Must follow pattern: speckit.{ext-id}.{cmd} file: "commands/hello.md" description: "Say hello" - aliases: ["speckit.my-ext.hi"] # Optional aliases, same pattern config: # Optional: Config files - name: "my-ext-config.yml" @@ -193,7 +192,6 @@ of `provides.commands`, `provides.templates`, `provides.scripts`, `hooks`, or - `name`: Command name (must match `speckit.{ext-id}.{command}`) - `file`: Path to command file (relative to extension root) - `description`: Command description (optional) -- `aliases`: Alternative command names (optional, array; each must match `speckit.{ext-id}.{command}`) **Template object**: diff --git a/extensions/README.md b/extensions/README.md index 70156a8fce..8012c8b4b5 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -120,4 +120,4 @@ specify extension add --from https://github.com///ar specify extension list ``` -For more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md). +For more information, see the [Extension User Guide](../docs/extensions/overview.md). diff --git a/extensions/github/README.md b/extensions/github/README.md index f6debdc5d4..6ee2100acb 100644 --- a/extensions/github/README.md +++ b/extensions/github/README.md @@ -112,7 +112,7 @@ available during this deprecation period until the removal stage. | ------------------------- | --------------------------------- | | `/speckit.taskstoissues` | `/speckit.github.taskstoissues` | -Apart from the core command's deprecation warning, conversion behavior is unchanged: the same feature resolution, the same `plan.md` and `tasks.md` prerequisites, the same remote validation, the same deduplication across open and closed issues, the same issue titles, and the same hook contract. This extension does **not** register `speckit.taskstoissues` as an alias, so the two commands coexist without shadowing each other while the core command still exists. +Apart from the core command's deprecation warning, conversion behavior is unchanged: the same feature resolution, the same `plan.md` and `tasks.md` prerequisites, the same remote validation, the same deduplication across open and closed issues, the same issue titles, and the same hook contract. The extension command and deprecated core command coexist without shadowing each other while the core command still exists. ### Presets and dependent extensions diff --git a/extensions/template/README.md b/extensions/template/README.md index 8b4274aa43..7865144f9c 100644 --- a/extensions/template/README.md +++ b/extensions/template/README.md @@ -70,7 +70,7 @@ Starter template for creating a Spec Kit extension. - **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md - **API Reference**: See EXTENSION-API-REFERENCE.md - **Publishing Guide**: See the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html) -- **User Guide**: See EXTENSION-USER-GUIDE.md +- **User Guide**: See the [Extension User Guide](https://github.github.io/spec-kit/extensions/overview.html) ## Template Version diff --git a/tests/extensions/bug/test_bug_hooks.py b/tests/extensions/bug/test_bug_hooks.py index 045265cb4a..1e5c425309 100644 --- a/tests/extensions/bug/test_bug_hooks.py +++ b/tests/extensions/bug/test_bug_hooks.py @@ -83,7 +83,7 @@ def test_assess_ensures_bug_directory_before_hook_checks(): @pytest.mark.parametrize("path", [ ROOT / "extensions/EXTENSION-API-REFERENCE.md", ROOT / "extensions/EXTENSION-DEVELOPMENT-GUIDE.md", - ROOT / "extensions/EXTENSION-USER-GUIDE.md", + ROOT / "docs/extensions/overview.md", EXT_DIR / "README.md", ]) def test_hook_events_documented(path):